Node.js Reference ยท Events and Timers
Node.js EventEmitterAsyncResource class
Reference for EventEmitterAsyncResource in Node.js: an EventEmitter whose listeners run in the async context captured at creation, with options and members.
EventEmitterAsyncResource is a subclass of EventEmitter from node:events that is also an async resource. Its listeners always run in the async context that was active when the emitter was created, not in the context of whoever calls emit().
This matters with AsyncLocalStorage. A normal emitter runs listeners in the context of the emit() caller, so a pooled or long-lived emitter shared by many requests can show the wrong request's data. With EventEmitterAsyncResource each emitter keeps the context it was born in, which is what you want for objects such as connections or queue consumers that belong to one logical operation.
const emitter = new EventEmitterAsyncResource({ name: 'MyEmitter' });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import { EventEmitterAsyncResource } from 'node:events'; new EventEmitterAsyncResource([options]) emitter.emitDestroy(): void emitter.asyncId: number emitter.triggerAsyncId: number emitter.asyncResource: EventEmitterReferencingAsyncResource
| Name | Description |
|---|---|
options.name |
String type name of the resource, shown in async diagnostics. Defaults to the class name. |
options.triggerAsyncId |
Async ID of the execution context that created this resource. Defaults to the current execution async ID. |
options.requireManualDestroy |
If true, the resource is not destroyed when it is garbage collected; you must call emitDestroy(). |
| other options | Everything EventEmitter accepts, such as captureRejections. |
Members:
emitDestroy()marks the async resource as destroyed (it emits thedestroyhook event). Call it once, when the emitter is finished.asyncIdandtriggerAsyncIdreturn the numbers of the underlying resource.asyncResourceis the underlyingAsyncResourceinstance. ItsrunInAsyncScope()is whatemit()uses to call listeners.
Usage notes
- Use it only when you need context isolation per emitter. For ordinary events the plain
EventEmitteris lighter. - The context captured is the one at construction time. Creating the emitter at module top level captures the top-level (empty) context, so create emitters inside the scope that owns them.
- The class does not change when listeners run; they are still invoked synchronously inside
emit(). - Without
requireManualDestroy, destruction is tied to garbage collection and therefore non-deterministic. Tools that track resource lifetimes (APM agents, diagnostics) work best if you callemitDestroy()when the emitter is finished. - It was added in Node.js 17.4 and 16.14 and is stable in Node.js 24.
- Do not subclass it just to add behavior that a wrapper object could provide; the double inheritance of
EventEmitterand an internalAsyncResourceis easy to get wrong.