Node.js Reference ยท Events and Timers
The EventEmitter class
Reference for the Node.js EventEmitter class: on, emit, once, off, newListener and removeListener events, subclassing, and synchronous behavior.
EventEmitter is the class from node:events that implements the publish and subscribe pattern. Code registers listener functions for named events with on(), and other code calls emit() to run every listener registered for that name. Streams, HTTP servers, sockets, child processes and process itself are all event emitters.
The most important thing to remember is that emit() is synchronous: the listeners run one after another, in registration order, before emit() returns. Nothing is queued and nothing runs in the background unless a listener does that itself.
import { EventEmitter } from 'node:events'; const bus = new EventEmitter();
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 { EventEmitter } from 'node:events'; new EventEmitter({ captureRejections?: boolean }) emitter.on(eventName, listener) emitter.addListener(...) emitter.once(eventName, listener) emitter.prependListener(eventName, listener) emitter.prependOnceListener(eventName, listener) emitter.off(eventName, listener) emitter.removeListener(...) emitter.removeAllListeners([eventName]) emitter.emit(eventName, ...args): boolean emitter.listeners(eventName): Function[] emitter.rawListeners(eventName): Function[] emitter.listenerCount(eventName, listener?): number emitter.eventNames(): (string | symbol)[] emitter.setMaxListeners(n) / emitter.getMaxListeners()
| Name | Description |
|---|---|
eventName |
A string or symbol identifying the event. Any string works; 'error', 'newListener' and 'removeListener' have special meaning. |
listener |
The function to call. It receives the arguments passed to emit(). |
captureRejections |
If true, a rejected promise returned by an async listener is routed to an 'error' event. See captureRejections. |
Returns: registration methods return the emitter, so calls can be chained. emit() returns true when at least one listener ran.
Special events: 'newListener' fires before a listener is added (so listeners() does not yet include it); 'removeListener' fires after one is removed.
Usage notes
- Synchronous calls. If a listener is slow,
emit()is slow. To defer work, schedule it inside the listener withsetImmediate()orqueueMicrotask(). - Order. Listeners run in the order they were added;
prependListener()puts one first. this. In a regularfunctionlistener,thisis the emitter. In an arrow function it is whatever surrounds it.- Errors. An exception thrown by a listener propagates out of
emit()and stops later listeners. An'error'event with no listener throws; see The error event. - Leaks. Adding more than 10 listeners for one event prints a warning, because it usually means listeners are being added in a loop and never removed. See setMaxListeners().
- Inheritance versus composition.
class Foo extends EventEmitteris the common pattern. Callingsuper()in the constructor is required. - Not the DOM.
EventEmitterhas no bubbling, nopreventDefault()and no event objects: the arguments are whatever you pass. For web-style events seeEventTarget. - Async ordering. Several
awaits between emitting and listening can miss events; attach listeners first, or useevents.once().