{"id":12844,"library":"async-listener","title":"Node.js process.addAsyncListener Polyfill","description":"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.","status":"abandoned","version":"0.6.10","language":"javascript","source_language":"en","source_url":"https://github.com/othiym23/async-listener","tags":["javascript","polyfill","shim","zesty","crazed","experimental"],"install":[{"cmd":"npm install async-listener","lang":"bash","label":"npm"},{"cmd":"yarn add async-listener","lang":"bash","label":"yarn"},{"cmd":"pnpm add async-listener","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used in CommonJS environments due to its target Node.js versions (0.11.x). ESM imports will fail.","wrong":"import { createAsyncListener } from 'async-listener';","symbol":"createAsyncListener","correct":"const { createAsyncListener } = require('async-listener');"},{"note":"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.","wrong":"import addAsyncListener from 'async-listener';","symbol":"addAsyncListener","correct":"const { addAsyncListener } = require('async-listener');"},{"note":"Standard named CommonJS import. Directly accessing properties off the require statement is less idiomatic than destructuring.","wrong":"const removeListener = require('async-listener').removeAsyncListener;","symbol":"removeAsyncListener","correct":"const { removeAsyncListener } = require('async-listener');"}],"quickstart":{"code":"const { addAsyncListener } = require('async-listener');\nconst fs = require('fs');\n\n// Add a global async listener\nconst myListener = addAsyncListener({\n  create: function(storage) {\n    console.log(`[${process.pid}] Listener created for async event.`);\n    return { id: Math.random().toString(36).substring(7), startTime: Date.now() };\n  },\n  before: function(context, storage) {\n    console.log(`[${process.pid}] Before async event ID: ${storage.id}, Time: ${Date.now() - storage.startTime}ms`);\n  },\n  after: function(context, storage) {\n    console.log(`[${process.pid}] After async event ID: ${storage.id}, Duration: ${Date.now() - storage.startTime}ms`);\n  },\n  error: function(storage, error) {\n    console.error(`[${process.pid}] Error in async event ID: ${storage.id}, Error: ${error.message}`);\n    return true; // Handle the error\n  }\n}, 'initial data');\n\nconsole.log(`[${process.pid}] Main application started.`);\n\n// Simulate an asynchronous operation (e.g., file read)\nfs.readFile(__filename, { encoding: 'utf8' }, (err, data) => {\n  if (err) {\n    console.error(`[${process.pid}] File read failed: ${err.message}`);\n    return;\n  }\n  console.log(`[${process.pid}] File content length: ${data.length} chars.`);\n});\n\n// Simulate another async operation\nsetTimeout(() => {\n  console.log(`[${process.pid}] Timeout completed.`);\n}, 100);\n\n// removeAsyncListener(myListener); // Can be removed later if needed\n\nconsole.log(`[${process.pid}] Main application finished scheduling.`);","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"The `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.","severity":"breaking","affected_versions":">=0.12.0"},{"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`.","message":"This 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.","severity":"gotcha","affected_versions":">=0.12.0"},{"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.","message":"The 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.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"TypeError: process.addAsyncListener is not a function"},{"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.","cause":"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.","error":"Error: Cannot find module 'async-listener'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}