Node.js Async Hook Abstraction

Common errors

• ReferenceError: asyncHooks is not defined

  cause The module's main export is named `asyncHook` (singular), but the user might have mistakenly used `asyncHooks` (plural) based on a typo in the README's `removeHooks` example.
  fix Change `asyncHooks` to `asyncHook`. For example, `asyncHook.removeHooks(...)` instead of `asyncHooks.removeHooks(...)`.

• TypeError: asyncHook.addHooks is not a function

  cause This typically occurs if `require('async-hook-jl')` failed to correctly load the module, or if `asyncHook` was reassigned or shadowed, or if the module was imported incorrectly in an ESM context.
  fix Ensure `const asyncHook = require('async-hook-jl');` is used at the top of your file. Verify that `async-hook-jl` is correctly installed in `node_modules` and that no other variable named `asyncHook` is conflicting.

• Hooks are registered but not firing (no console output from hook functions).

  cause The `async-hook-jl` hooks are disabled by default and must be explicitly enabled using `asyncHook.enable()` after registration.
  fix Ensure you call `asyncHook.enable();` after calling `asyncHook.addHooks(...)` to activate the hook callbacks.

Warnings

• breaking `async-hook-jl` relies on Node.js's internal, undocumented `AsyncWrap` API. Future Node.js major or even minor versions might introduce breaking changes to `AsyncWrap` that could affect this library's functionality without prior notice, potentially requiring updates or causing unexpected runtime errors.
  Fix: Monitor Node.js release notes closely for changes to internal async APIs. Test `async-hook-jl` extensively when upgrading Node.js versions. Consider forking or using a specific, tested version of Node.js for critical applications.
• gotcha Disabling hooks globally using `asyncHook.disable()` can lead to conflicts or unexpected behavior with other modules that might also be using `async-hook-jl` or directly interacting with `AsyncWrap`. This can break their functionality or lead to difficult-to-debug side effects.
  Fix: Only disable hooks if you are certain no other part of your application or its dependencies relies on `async-hook-jl` being active. Prefer conditional hook registration or removal over global disabling where possible.
• gotcha The package's README, specifically in the `removeHooks` example, contains a typo. It incorrectly uses `asyncHooks.removeHooks` (plural) instead of `asyncHook.removeHooks` (singular). Copying this code verbatim will result in a `ReferenceError`.
  Fix: Always use `asyncHook` (singular) when interacting with the module's exported object and its methods (e.g., `asyncHook.removeHooks(...)`).
• gotcha The `async-hook-jl` module is primarily designed for CommonJS (`require`) environments. While Node.js itself supports ESM, directly importing this module using `import ... from 'async-hook-jl'` may not work as intended or could lead to compatibility issues depending on your Node.js version and configuration.
  Fix: Always use `const asyncHook = require('async-hook-jl');` to ensure correct module loading, especially in older Node.js versions or mixed CJS/ESM projects.

Install

• npm install async-hook-jl npm
• yarn add async-hook-jl yarn
• pnpm add async-hook-jl pnpm

Imports

• asyncHook
  wrong:

  import asyncHook from 'async-hook-jl';

  correct:

  const asyncHook = require('async-hook-jl');

  This library is primarily designed for CommonJS (`require`) environments, consistent with its target Node.js versions. Direct ESM `import` is not officially supported and may not work as expected.
• addHooks
  wrong:

  import { addHooks } from 'async-hook-jl';

  correct:

  asyncHook.addHooks({ init, pre, post, destroy });

  All API methods like `addHooks` are properties of the default `asyncHook` object, not named exports.
• enable
  wrong:

  asyncHooks.enable();

  correct:

  asyncHook.enable();

  The main module export is `asyncHook` (singular). Be careful not to confuse it with a plural form or a global `async_hooks` module from Node.js core when referring to its methods.

Quickstart

This quickstart demonstrates how to initialize `async-hook-jl`, register all four types of lifecycle hooks (`init`, `pre`, `post`, `destroy`), enable them, and observe their output during a simple `setTimeout` operation.

const asyncHook = require('async-hook-jl');

function init(uid, handle, provider, parentUid, parentHandle) {
  console.log(`[INIT] UID: ${uid}, Provider: ${asyncHook.providers[provider]}, Parent UID: ${parentUid}`);
}
function pre(uid, handle) {
  console.log(`[PRE] UID: ${uid}`);
}
function post(uid, handle, didThrow) {
  console.log(`[POST] UID: ${uid}, DidThrow: ${didThrow}`);
}
function destroy(uid) {
  console.log(`[DESTROY] UID: ${uid}`);
}

// Add the defined hooks
asyncHook.addHooks({ init, pre, post, destroy });

// Enable the hooks globally
asyncHook.enable();

// Demonstrate an asynchronous operation
console.log('Starting timer...');
setTimeout(() => {
  console.log('Timer finished after 100ms.');
}, 100);

// Optional: Disable after some time or specific operations
// setTimeout(() => {
//   asyncHook.disable();
//   console.log('Async hooks disabled.');
// }, 500);