In-process domain notifications
A component needs to notify multiple consumers when its state changes.
Node.js · Class
EventEmitter
EventEmitter is Node.js’s base class for named, synchronous event dispatch. Register listeners with on() or once(), then trigger them with emit(), passing optional arguments.
How it works
EventEmitter provides named-event registration and emission. Listeners attached with on() or once() receive the arguments passed to emit(); dispatch is synchronous and follows registration order, while listener return values are ignored.
Syntax
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.on(eventName, listener);
emitter.once(eventName, listener);
emitter.emit(eventName, ...args);Parameters
| Name | Type | Description |
|---|---|---|
eventName | string | symbol | The event name to subscribe to or emit; event names may be strings or symbols. |
listener | Function | The function invoked when the named event is emitted. |
...args | any | Values forwarded in order to each matching listener. |
Returns
The registration methods return the emitter for chaining; emit() returns true if the event had listeners and false otherwise.
Key points
- Import the class from the built-in node:events module.
- Use on() for subscription and emit() to publish an event.
- Multiple listeners execute sequentially according to registration order.
- emit() can pass any number of positional arguments to listeners.
- emit() returns after synchronously invoking matching listeners with the supplied arguments.
Common mistakes
- Event handlers run during emit(), so a long-running listener blocks subsequent listeners and other synchronous work.
- Do not use a listener's return value to communicate a result back through emit().
- Always handle an emitter's 'error' event when failure can be emitted; otherwise the process can terminate.
Example: Registering a one-time event listener
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('ready', (name) => {
console.log(`${name} is ready`);
});
emitter.emit('ready', 'service');
emitter.emit('ready', 'service');The one-time listener runs only for the first emission, so the second emit produces no output.
When to use it
Lifecycle and resource events
A resource emits completion, close, or failure signals to coordinating code.
Initialization handshakes
A one-time readiness signal must be consumed without manual cleanup.
Reusable event-driven APIs
A custom stream-like abstraction needs a familiar Node.js event interface.
Interview questions
QWhat is EventEmitter, and how does dispatch work?
EventEmitter is Node's class for objects that publish named events. Consumers register listener functions, and emit() invokes listeners for the matching event synchronously in registration order.
Follow-up: How would you prevent a listener from running more than once? Use once(), which removes the listener after its first invocation.
QWhat is the difference between on() and once()?
on() registers a listener for every future occurrence of an event, whereas once() registers a listener that is automatically removed after its first invocation. Both receive arguments supplied to emit().
Follow-up: What happens if the same function is registered repeatedly? Each registration is treated as a separate listener and can cause another invocation.
QWhy must error events be handled?
The special error event requires explicit handling: if it is emitted without an error listener, Node throws the error and exits the process. Register an error listener when the emitter may report failures.
Follow-up: Can error be emitted with arbitrary data? It should represent an Error condition; otherwise the emitted value is thrown as described by the API behavior.
Related
EventEmitter.on()EventEmitter.once()EventEmitter.emit()EventEmitter.off()EventEmitter.removeListener()EventEmitter.addListener()EventEmitter.listenerCount()EventEmitter.listeners()