Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { on } from 'node:events';
for await (const [line] of on(emitter, 'line')) { /* ... */ }

Try it

Node.js A for await loop over events

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.

Node.js close and signal options

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

NODE
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, a close event, or a signal; otherwise the listeners stay registered.
  • Cleanup is automatic when the loop exits, including through break: the iterator's return() 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. Call on() 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. EventTarget objects are supported; each yielded array contains the Event.
  • Streams. Readable streams are already async iterable; use for await (const chunk of readable) instead of on(readable, 'data').
  • Available as events.on() since Node.js 12.16 (stable); the close and water-mark options came later, in current LTS releases.