Node.js Reference ยท Events and Timers
Node.js events.on() function
Reference for events.on() in Node.js: iterate an emitter's events with for await, stop with break, close or AbortSignal, and avoid losing events.
events.on(emitter, eventName, options) returns an async iterator that yields every emission of eventName. Each yielded value is an array of the event's arguments. It turns a push-style emitter into a pull-style loop you can read with for await.
Between iterations the iterator keeps a queue, so events that arrive while your loop body is busy are not lost. The loop ends when you break, when an AbortSignal fires, or when an event named in the close option is emitted.
import { on } from 'node:events'; for await (const [line] of on(emitter, 'line')) { /* ... */ }
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 { on } from 'node:events'; on(emitter: EventEmitter | EventTarget, eventName: string | symbol, options?: { signal?: AbortSignal, close?: (string | symbol)[], highWaterMark?: number, lowWaterMark?: number, }): AsyncIterator<any[]>
| Name | Description |
|---|---|
emitter |
The emitter or EventTarget to listen to. |
eventName |
The event to turn into iteration values. |
signal |
Aborting it ends the loop with an AbortError. |
close |
Event names that end the iteration normally when emitted. |
highWaterMark, lowWaterMark |
Backpressure thresholds for emitters that can pause and resume, such as streams. |
Returns: an async iterator whose values are arrays of the emitted arguments.
Errors: an 'error' event makes the iterator throw that error on its next step and end the loop. An aborted signal throws AbortError.
Usage notes
- Always leave the loop. The iterator holds listeners on the emitter until the loop ends. Exit with
break,return, acloseevent, or a signal; otherwise the listeners stay registered. - Cleanup is automatic when the loop exits, including through
break: the iterator'sreturn()removes its listeners. - Events before the loop are lost. The listener is added when you call
on()(and not earlier), so events emitted before that are gone. Callon()first, then trigger the work. - Buffering. Events that arrive while your loop body is awaiting something are queued, and the loop sees them in order afterward. The queue is unbounded unless the emitter supports pause and resume and you set a high-water mark.
- Array values. Even a single argument arrives as
[value]. Destructure it in the loop header. - Error ordering. An
'error'event is delivered after already queued events, since it is part of the same queue. - Event targets.
EventTargetobjects are supported; each yielded array contains theEvent. - Streams. Readable streams are already async iterable; use
for await (const chunk of readable)instead ofon(readable, 'data'). - Available as
events.on()since Node.js 12.16 (stable); thecloseand water-mark options came later, in current LTS releases.