Registry / observability / async-listener

async-listener

library0.6.10jsnpmunverified

async-listener is a polyfill and shim for the experimental `process.addAsyncListener` API, originally proposed for Node.js versions prior to 0.12 (specifically anticipated for 0.11.7). The package, currently at version 0.6.10, aimed to provide functionality for tracking asynchronous operations through `create`, `before`, `after`, and `error` hooks in an `AsyncListener` object. This API never landed in a stable version of Node.js core; it was a predecessor to what eventually became the `async_hooks` module (introduced in Node.js v8.0.0) and later the more user-friendly `AsyncLocalStorage` API (now stable). The package's release cadence was infrequent, with the last publish many years ago, aligning with its role as a temporary shim for an abandoned core feature. Its key differentiator was providing an early glimpse and implementation of async context tracking during Node.js's nascent stages of developing such features.

observability

npm install async-listener

github ↗package ↗

INSTALL

IMPORT

SIG · ASYNC-LISTENER

async-listener

observabilityjavascriptv0.6.10

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.

createAsyncListener

✓ const { createAsyncListener } = require('async-listener');

✗ import { createAsyncListener } from 'async-listener';

Primarily used in CommonJS environments due to its target Node.js versions (0.11.x). ESM imports will fail.

addAsyncListener

✓ const { addAsyncListener } = require('async-listener');

✗ import addAsyncListener from 'async-listener';

This function is exposed as a named export. The global `process.addAsyncListener` in Node.js 0.11.x would not be the same as this polyfill's direct export.

removeAsyncListener

✓ const { removeAsyncListener } = require('async-listener');

✗ const removeListener = require('async-listener').removeAsyncListener;

Standard named CommonJS import. Directly accessing properties off the require statement is less idiomatic than destructuring.

Demonstrates how to initialize and use `async-listener` to trace the lifecycle of asynchronous operations like `fs.readFile` and `setTimeout`, including `create`, `before`, `after`, and `error` hooks.

const { addAsyncListener } = require('async-listener'); const fs = require('fs'); // Add a global async listener const myListener = addAsyncListener({ create: function(storage) { console.log(`[${process.pid}] Listener created for async event.`); return { id: Math.random().toString(36).substring(7), startTime: Date.now() }; }, before: function(context, storage) { console.log(`[${process.pid}] Before async event ID: ${storage.id}, Time: ${Date.now() - storage.startTime}ms`); }, after: function(context, storage) { console.log(`[${process.pid}] After async event ID: ${storage.id}, Duration: ${Date.now() - storage.startTime}ms`); }, error: function(storage, error) { console.error(`[${process.pid}] Error in async event ID: ${storage.id}, Error: ${error.message}`); return true; // Handle the error } }, 'initial data'); console.log(`[${process.pid}] Main application started.`); // Simulate an asynchronous operation (e.g., file read) fs.readFile(__filename, { encoding: 'utf8' }, (err, data) => { if (err) { console.error(`[${process.pid}] File read failed: ${err.message}`); return; } console.log(`[${process.pid}] File content length: ${data.length} chars.`); }); // Simulate another async operation setTimeout(() => { console.log(`[${process.pid}] Timeout completed.`); }, 100); // removeAsyncListener(myListener); // Can be removed later if needed console.log(`[${process.pid}] Main application finished scheduling.`);

Debug

Known issues

breakingThe `process.addAsyncListener` API this package polyfills was an experimental feature in very old Node.js versions (pre-0.12) and was never stabilized or widely adopted in Node.js core. Using this package in modern Node.js versions will lead to compatibility issues or simply not work as the underlying API concept has been superseded.

fix

For modern Node.js (v8.0.0+), use the built-in `async_hooks` module or the higher-level `AsyncLocalStorage` API for async context tracking. Do not use `async-listener`.

affects: >=0.12.0

gotchaThis package explicitly targets extremely old Node.js versions (engines: `<=0.11.8 || >0.11.10`). It is not compatible with any LTS or actively maintained Node.js release, and attempts to install or run it in newer environments will likely fail or cause unexpected behavior.

fix

Only use this package if you are strictly maintaining an application on Node.js 0.11.x. For any other Node.js version, consider native `async_hooks` or `AsyncLocalStorage`.

affects: >=0.12.0

deprecatedThe functionality provided by `async-listener` for `process.addAsyncListener` has been replaced by more robust and stable APIs in Node.js. `async_hooks` provides low-level access to asynchronous resource lifetimes, while `AsyncLocalStorage` offers a stable and recommended way to manage asynchronous context.

fix

Migrate to Node.js's native `async_hooks` (experimental but mature) or `AsyncLocalStorage` (stable) for similar async context tracking capabilities. For example, use `AsyncLocalStorage` for request-scoped data in web applications.

affects: *

Errors

Common errors & fixes

TypeError: process.addAsyncListener is not a function

Attempting to use `process.addAsyncListener` directly in a Node.js version where it was never implemented or has been removed, or before requiring the `async-listener` polyfill.

fix

Ensure `require('async-listener')` is executed before attempting to use its exports. If on a modern Node.js version, this API is unsupported; migrate to `async_hooks` or `AsyncLocalStorage`.

Error: Cannot find module 'async-listener'

The package `async-listener` is not installed or the `require()` path is incorrect. Could also happen in a modern ESM project without proper CJS interoperability.

fix

Run `npm install async-listener`. If in an ESM module, consider if this ancient CJS package is suitable, or use `createRequire` for explicit CJS import.

Upgrade

Version history

0.6.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/othiym23/async-listener ↗

packagehttps://www.npmjs.com/package/async-listener ↗