Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { EventEmitter } from 'node:events';
const bus = new EventEmitter();

Try it

Node.js Subclassing and listening

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 newListener and removeListener 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.

Syntax

NODE
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 with setImmediate() or queueMicrotask().
  • Order. Listeners run in the order they were added; prependListener() puts one first.
  • this. In a regular function listener, this is 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 EventEmitter is the common pattern. Calling super() in the constructor is required.
  • Not the DOM. EventEmitter has no bubbling, no preventDefault() and no event objects: the arguments are whatever you pass. For web-style events see EventTarget.
  • Async ordering. Several awaits between emitting and listening can miss events; attach listeners first, or use events.once().