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.
import { once } from 'node:events'; const [value] = await once(emitter, 'ready');
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 { 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 notawaitsomething slow between creating the emitter and callingonce(). - 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, thenawait Promise.all(...). Awaiting them one by one can miss events that fire during the first wait. - Racing. With
Promise.racethe losing waits stay registered until you cancel them with a sharedsignal. - Timeouts. Combine with
AbortSignal.timeout(ms)to give up after a delay; the rejection is aTimeoutError. EventTargetsupport. ForEventTarget, 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 needsawait.