{"id":17498,"library":"async_hooks","title":"Node.js async_hooks Core Module (npm placeholder)","description":"This npm package, `async_hooks` (v1.0.0), is a placeholder that explicitly states it is \"squatting for node core module.\" It provides no functional code or exports. The actual `async_hooks` is a critical Node.js core module, built directly into the Node.js runtime, designed for tracking the lifecycle of asynchronous resources (like promises, timers, and I/O operations) within an application. It enables advanced use cases such as profiling, debugging, and propagating context across asynchronous operations. Historically, parts of this API were marked experimental; however, Node.js now recommends `AsyncLocalStorage` for most asynchronous context tracking, as it offers a more stable, performant, and memory-safe implementation compared to the lower-level `createHook` API. Developers should always directly import `node:async_hooks` as a built-in module and **never** install a package named `async_hooks` from npm, as it is a non-functional squat.","status":"abandoned","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install async_hooks","lang":"bash","label":"npm"},{"cmd":"yarn add async_hooks","lang":"bash","label":"yarn"},{"cmd":"pnpm add async_hooks","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This refers to the Node.js core module. The `node:` prefix is explicitly recommended to indicate a built-in module and prevent potential conflicts. Installing the npm package `async_hooks` is incorrect and will not provide the Node.js API.","wrong":"import * as async_hooks from 'async_hooks';\nconst async_hooks = require('async_hooks');\nnpm install async_hooks","symbol":"async_hooks (module import)","correct":"import * as async_hooks from 'node:async_hooks';"},{"note":"The recommended and stable API for asynchronous context tracking in Node.js, suitable for use cases like request ID propagation or tracing.","wrong":"import AsyncLocalStorage from 'node:async_hooks';\nconst { AsyncLocalStorage } = require('async_hooks');\nnpm install async_hooks","symbol":"AsyncLocalStorage","correct":"import { AsyncLocalStorage } from 'node:async_hooks';"},{"note":"This is part of the original, lower-level `async_hooks` API. Node.js documentation now discourages its use for new asynchronous context tracking, recommending `AsyncLocalStorage` instead due to usability, safety, and performance concerns.","wrong":"import createHook from 'node:async_hooks';\nconst { createHook } = require('async_hooks');\nnpm install async_hooks","symbol":"createHook","correct":"import { createHook } from 'node:async_hooks';"}],"quickstart":{"code":"import { AsyncLocalStorage } from 'node:async_hooks';\n\nconst asyncLocalStorage = new AsyncLocalStorage();\n\nfunction logWithId(message: string) {\n  const id = asyncLocalStorage.getStore()?.id ?? 'none';\n  console.log(`[Request ID: ${id}] ${message}`);\n}\n\nfunction handleRequest(requestId: string, callback: () => void) {\n  asyncLocalStorage.run({ id: requestId }, () => {\n    logWithId('Starting request processing');\n    // Simulate some asynchronous work\n    setTimeout(() => {\n      logWithId('Intermediate async step');\n      callback();\n    }, 100);\n  });\n}\n\n// Simulate incoming requests\nconsole.log('--- Request 1 ---');\nhandleRequest('req-123', () => {\n  logWithId('Request 1 completed');\n  console.log('\\n--- Request 2 ---');\n  handleRequest('req-456', () => {\n    logWithId('Request 2 completed');\n    console.log('\\n--- Request 3 (no ID) ---');\n    logWithId('This will show no ID as it is not run within a store.');\n  });\n});","lang":"typescript","description":"Demonstrates `AsyncLocalStorage` for propagating a request ID across asynchronous operations in Node.js."},"warnings":[{"fix":"Remove `async_hooks` from `package.json` and `node_modules`. Always import the core module directly using `import ... from 'node:async_hooks';` or `require('node:async_hooks');`.","message":"Do NOT install the npm package `async_hooks`. It is a non-functional placeholder for a Node.js core module. Installing it will not provide the intended API and may lead to confusion or incorrect builds.","severity":"breaking","affected_versions":">=1.0.0 (npm package)"},{"fix":"For asynchronous context tracking, migrate to the `AsyncLocalStorage` API, which is stable and optimized.","message":"The `createHook` and `AsyncHook` APIs are generally discouraged for new code in recent Node.js versions (v14+). They have known usability issues, safety risks, and performance implications.","severity":"deprecated","affected_versions":">=14.0.0 (Node.js)"},{"fix":"For debugging within `async_hooks` callbacks, use synchronous logging methods such as `fs.writeSync(1, msg)` to print to stdout without triggering further async events.","message":"Calling asynchronous operations like `console.log()` inside `async_hooks` callbacks (e.g., `init`, `before`, `after`, `destroy`) can cause infinite recursion, as these logging operations themselves trigger `async_hooks` events.","severity":"gotcha","affected_versions":">=8.0.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure you are running in a Node.js environment. If you have an `async_hooks` npm package installed, remove it. Use the explicit `node:` prefix for imports: `import * as async_hooks from 'node:async_hooks';`.","cause":"Attempting to import `async_hooks` in an environment where it's not a core module (e.g., browser) or if Node.js cannot resolve the core module due to an incorrectly installed npm package of the same name.","error":"Error: Cannot find module 'async_hooks'"},{"fix":"If your project uses CommonJS, use `const async_hooks = require('node:async_hooks');`. If your project uses ES Modules, use `import * as async_hooks from 'node:async_hooks';`. Ensure your `package.json` `\"type\": \"module\"` is set correctly for ESM projects.","cause":"Trying to use `require()` to import `node:async_hooks` (or any other ESM-only module) in a CommonJS module, or trying to `import` in a CommonJS file.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}