Registry / http-networking / async-hook-jl

async-hook-jl

JSON →
library1.7.6jsnpmunverified

async-hook-jl is a Node.js library that provides a high-level, stable abstraction over Node.js's internal, currently undocumented `AsyncWrap` API. It enables developers to inspect and hook into the lifecycle of "handle objects" (internal resources like network connections, timers, etc.) within the Node.js runtime. This includes events like initialization (`init`), pre-execution (`pre`), post-execution (`post`), and destruction (`destroy`) of asynchronous operations. The library aims to address some inconsistencies in the native `AsyncWrap` API, offer a more uniform interface, and crucially, allow multiple hooks to be registered simultaneously. The current stable version is 1.7.6, with recent updates focusing on compatibility and minor fixes rather than new features. Its primary differentiator is making a powerful, low-level internal Node.js API accessible and more robust for userland modules, with the long-term hope that similar functionality will eventually be integrated directly into Node.js core.

http-networkingobservability
npm install async-hook-jl
github ↗package ↗
INSTALL
IMPORT
SIG · ASYNC-HOOK-JL
A
async-hook-jl
http-networkingjavascriptv1.7.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

asyncHook
✓ const asyncHook = require('async-hook-jl');
✗ import asyncHook from '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
✓ asyncHook.addHooks({ init, pre, post, destroy });
✗ import { addHooks } from 'async-hook-jl';
All API methods like `addHooks` are properties of the default `asyncHook` object, not named exports.
enable
✓ asyncHook.enable();
✗ asyncHooks.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.

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);
Debug
Known issues
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.
affects: >=1.0.0
gotchaDisabling 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.
affects: >=1.0.0
gotchaThe 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(...)`).
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: asyncHooks is not defined
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
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).
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.
Upgrade
Version history
1.7.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
31 hits · last 30 days
node
28
OpenAI (training)
1
Resources
githubhttps://github.com/jeff-lewis/async-hook-jl ↗
packagehttps://www.npmjs.com/package/async-hook-jl ↗
async-hook-jl — npm install async-hook-jl · libregistry