Node.js Reference ยท Events and Timers
captureRejections in Node.js EventEmitter
Reference for the captureRejections option of Node.js EventEmitter: how rejected async listeners become 'error' events, the rejection symbol and its pitfalls.
An EventEmitter calls its listeners synchronously and ignores what they return. That is a problem for async listeners: if one throws after an await, the promise it returned rejects, nobody is watching that promise, and the process ends with an unhandled rejection. captureRejections is an opt-in feature that attaches a handler to every promise a listener returns and routes the failure back into the emitter.
With the option on, a rejected listener promise is turned into an 'error' event on the same emitter (or into a call to a custom handler method). Ordinary error handling then works the way it does for synchronous listeners.
const emitter = new EventEmitter({ captureRejections: true }); emitter.on('error', (err) => console.log('caught:', err.message));
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
new EventEmitter({ captureRejections: true }) EventEmitter.captureRejections = true // default for emitters created later emitter[Symbol.for('nodejs.rejection')] = (err, eventName, ...args) => { }
| Name | Description |
|---|---|
captureRejections (option) |
Boolean. When true, promises returned by listeners of this emitter are observed. Default false. |
EventEmitter.captureRejections |
Static property that sets the default for every emitter created afterwards. It does not change existing emitters. |
captureRejectionSymbol |
Exported by node:events; equal to Symbol.for('nodejs.rejection'). A method under this key replaces the default routing. |
What happens on rejection:
- If the emitter has a function under the rejection symbol, it is called with the error, the event name and the original emit arguments.
- Otherwise the emitter emits
'error'with the error as the only argument. If nothing listens for'error', the normal rule applies and the error is thrown, which usually means an uncaught exception.
Usage notes
- Only listeners that return a thenable are observed. Synchronous throws are not affected by this option; they still propagate out of
emit(). - The option is per emitter. Subclasses must pass it to
super(), as the second example does. - If a custom rejection handler itself throws, the error is emitted as an
'error'event. Keep that handler simple and synchronous. - The
'error'event is emitted asynchronously, after the promise rejected, so code that wrapsemit()intry/catchwill never see it. - Do not rely on the feature for flow control. A rejected listener does not stop the other listeners of the same event; they were already called.
- Enabling it globally with
EventEmitter.captureRejections = trueis convenient in applications, but libraries should set the option on their own emitters instead of changing a global. - Without the option, a rejected listener leads to the
unhandledRejectionpath, which in current Node.js versions terminates the process unless a handler exists.