Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Events and Timers

Node.js events.once() function

Reference for events.once() in Node.js: wait for a single event with await, the array of arguments, error rejection, AbortSignal and EventTarget support.

events.once(emitter, eventName, options) returns a promise that resolves the next time the emitter emits eventName. The promise value is an array of the arguments the event carried. It lets you write await once(server, 'listening') instead of building a new Promise around a one-shot listener.

If the emitter emits 'error' while you are waiting, the promise rejects with that error, and the listeners it installed are cleaned up either way.

NODE
import { once } from 'node:events';
const [value] = await once(emitter, 'ready');

Try it

Node.js Waiting for an event

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 Errors, cancellation and EventTarget

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 { once } from 'node:events';

once(emitter: EventEmitter | EventTarget, eventName: string | symbol, options?: { signal?: AbortSignal }): Promise<any[]>
Name Description
emitter The EventEmitter or EventTarget to listen on.
eventName The event to wait for.
options.signal An AbortSignal that cancels the wait.

Returns: a promise for an array of the event's arguments. For an EventTarget the array holds the event object.

Errors: the promise rejects with the emitted error if 'error' fires first (unless eventName is 'error'), and with an AbortError if the signal aborts. ERR_INVALID_ARG_TYPE is thrown for a bad emitter.

Usage notes

  • Array result. Even an event with one argument gives [value]; destructure it. An event with no arguments gives [].
  • Attach before the event. The listener is added when once() is called, so call it before the code that triggers the event, or you can miss it. Do not await something slow between creating the emitter and calling once().
  • Only the first event. After it resolves, further emissions are ignored. For a stream of events use events.on().
  • Several waits at once. Create all the once() promises first, then await Promise.all(...). Awaiting them one by one can miss events that fire during the first wait.
  • Racing. With Promise.race the losing waits stay registered until you cancel them with a shared signal.
  • Timeouts. Combine with AbortSignal.timeout(ms) to give up after a delay; the rejection is a TimeoutError.
  • EventTarget support. For EventTarget, the 'error' special case does not apply, since that type has no such convention.
  • Not for repeated listeners. Use emitter.once() when a plain callback is enough and nothing needs await.