EventEmitter

The backbone of Node’s event-driven model

EventEmitter (from node:events) is the class that powers virtually every I/O object in Node.js. The HTTP server, TCP sockets, file streams, child processes, and many third-party libraries all extend EventEmitter. Understanding it means understanding how Node communicates between components.

🟢 EventEmitter is the backbone of Node's streams, HTTP, and more

http.Server, net.Socket, fs.ReadStream — all of these extend EventEmitter. When a request arrives, the server emits 'request'. When a socket disconnects, it emits 'close'. Learning EventEmitter is learning the fundamental communication contract of Node.js.

Basic usage: on, emit, removeListener

Node.jsOpen in StackBlitz ▸

import { EventEmitter } from 'node:events'; var emitter = new EventEmitter(); // Register a listener emitter.on('greet', function(name) { console.log('Hello, ' + name + '!'); }); // Emit the event — listener runs synchronously emitter.emit('greet', 'Alice'); emitter.emit('greet', 'Bob'); // Remove the listener var handler = function(msg) { console.log('message:', msg); }; emitter.on('message', handler); emitter.emit('message', 'first'); emitter.removeListener('message', handler); emitter.emit('message', 'second'); // no output — listener removed

Output (verified on Node 24)

Hello, Alice!
Hello, Bob!
message: first

once — fire exactly one time

once registers a listener that automatically removes itself after the first emission.

Node.jsOpen in StackBlitz ▸

import { EventEmitter } from 'node:events'; var emitter = new EventEmitter(); emitter.once('connect', function() { console.log('Connected! (fires once only)'); }); emitter.emit('connect'); // prints "Connected!" emitter.emit('connect'); // nothing — listener already removed emitter.emit('connect'); // nothing console.log('listener count:', emitter.listenerCount('connect')); // 0

Output (verified on Node 24)

Connected! (fires once only)
listener count: 0

Building a custom EventEmitter class

Extend EventEmitter to give your own classes event-driven capabilities.

Node.jsOpen in StackBlitz ▸

import { EventEmitter } from 'node:events'; class DataLoader extends EventEmitter { constructor() { super(); this._items = []; } load(item) { this._items.push(item); this.emit('data', item); if (this._items.length >= 3) { this.emit('done', this._items); } } } var loader = new DataLoader(); loader.on('data', function(item) { console.log('loaded item:', item); }); loader.once('done', function(all) { console.log('all done! total:', all.length, 'items'); console.log('items:', all.join(', ')); }); loader.load('alpha'); loader.load('beta'); loader.load('gamma');

Output (verified on Node 24)

loaded item: alpha
loaded item: beta
loaded item: gamma
all done! total: 3 items
items: alpha, beta, gamma

Listener count and off()

off is an alias for removeListener added in Node 10. listenerCount lets you inspect how many listeners are registered for an event — useful for detecting potential memory leaks.

Node.jsOpen in StackBlitz ▸

import { EventEmitter } from 'node:events'; var ee = new EventEmitter(); var handler1 = function() { console.log('handler1'); }; var handler2 = function() { console.log('handler2'); }; ee.on('event', handler1); ee.on('event', handler2); console.log('count before off:', ee.listenerCount('event')); // 2 ee.off('event', handler1); console.log('count after off:', ee.listenerCount('event')); // 1 ee.emit('event'); // only handler2 runs

Output (verified on Node 24)

count before off: 2
count after off: 1
handler2

The listener leak warning

EventEmitter defaults to a maximum of 10 listeners per event (defaultMaxListeners). This is not a hard limit — it’s a heuristic tripwire: the #1 EventEmitter bug in AI-generated code is a listener registered inside a loop, a request handler, or a React-style re-render, which silently adds a new listener on every call instead of reusing one. Left unnoticed, that’s an unbounded memory leak.

When the count exceeds the max, Node emits a process warning — normally printed to stderr only. To surface it in a script’s own output (and to handle it programmatically, e.g. shipping it to your logs), listen for process.on('warning', ...):

Node.jsOpen in StackBlitz ▸

const { EventEmitter } = require('node:events'); process.on('warning', function(warning) { console.log('warning name:', warning.name); console.log('warning message:', warning.message); }); var emitter = new EventEmitter(); console.log('default max listeners:', emitter.getMaxListeners()); // Adding more listeners than the default max (10) for the same event is // almost always a bug -- usually a listener registered inside a loop or on // every request instead of once at startup. for (var i = 0; i < 11; i++) { emitter.on('data', function() {}); } console.log('listener count:', emitter.listenerCount('data'));

Output (verified on Node 24)

default max listeners: 10
listener count: 11
warning name: MaxListenersExceededWarning
warning message: Possible EventEmitter memory leak detected. 11 data listeners added to [EventEmitter]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit

If 10 listeners genuinely is too few for a legitimate use case (e.g. a shared event bus with many independent subscribers), raise the limit explicitly with emitter.setMaxListeners(n) — that documents the decision instead of silently outgrowing the default.

events.on() and events.once() — async iteration and promises

events.once(emitter, name) returns a Promise that resolves with the event’s arguments on the first emission — a one-shot alternative to emitter.once() with a callback. events.on(emitter, name) returns an async iterable that yields every emission, for use with for await:

Node.jsOpen in StackBlitz ▸

const { EventEmitter, on, once } = require('node:events'); async function main() { var emitter = new EventEmitter(); // once() as a promise -- resolves with the event's args on first emission var readyPromise = once(emitter, 'ready'); emitter.emit('ready', 'server'); var readyArgs = await readyPromise; console.log('once() resolved with:', readyArgs); // events.on() -- async-iterate every emission of an event setImmediate(function() { emitter.emit('tick', 1); emitter.emit('tick', 2); emitter.emit('tick', 3); emitter.emit('done'); }); for await (const [n] of on(emitter, 'tick')) { console.log('tick:', n); if (n === 3) break; // must break manually -- on() never ends on its own } console.log('finished iterating ticks'); } main();

Output (verified on Node 24)

once() resolved with: [ 'server' ]
tick: 1
tick: 2
tick: 3
finished iterating ticks

🟢 on() keeps a queue — you must break out of the loop yourself

Unlike a Readable stream’s async iterator, events.on() has no natural end unless the emitter itself emits 'end'/'close' (which events.on() recognizes automatically) or you break. Forgetting to break turns the for await loop into a permanent listener that never lets the function return.

captureRejections — routing async listener errors to ‘error’

An async listener that throws produces a rejected promise that EventEmitter does not await — by default that becomes an unhandled rejection, which crashes the process on modern Node (default --unhandled-rejections=throw). Passing captureRejections: true to the constructor routes that rejection to the emitter’s 'error' event instead, where you can handle it like any other error:

Node.jsOpen in StackBlitz ▸

import { EventEmitter } from 'node:events'; // Without captureRejections, a listener that returns a rejected promise // produces an unhandled rejection that crashes the process (Node >= 15). // With captureRejections: true, the rejection is routed to an 'error' event // on the emitter instead, which you can handle like any other error. var emitter = new EventEmitter({ captureRejections: true }); emitter.on('error', function(err) { console.log('caught via error event:', err.message); }); emitter.on('work', async function() { throw new Error('async listener failed'); }); emitter.emit('work'); console.log('emit() returned -- the throw happens later, on the microtask queue'); // Give the rejection a turn to be routed before the process exits await new Promise(function(resolve) { setImmediate(resolve); }); console.log('done');

Output (verified on Node 24)

emit() returned -- the throw happens later, on the microtask queue
caught via error event: async listener failed
done

An unhandled ‘error’ event throws

'error' is a special event name in EventEmitter: if it is emitted and no listener is registered for it, Node throws the error instead of silently dropping it, crashing the process. This is deliberate — it is the one event you are not allowed to ignore by accident.

Node.jsOpen in StackBlitz ▸

// @expect-throw const { EventEmitter } = require('node:events'); var emitter = new EventEmitter(); // No 'error' listener registered. console.log('about to emit error with no listener...'); emitter.emit('error', new Error('boom')); console.log('this line never runs');

Output (verified on Node 24)

about to emit error with no listener...

🟢 Always attach an 'error' listener to anything that extends EventEmitter

Sockets, streams, child processes, and HTTP servers all extend EventEmitter and can all emit 'error'. Wiring up .on('error', ...) is not optional defensive coding — without it, a single error event crashes the entire process, even one nested three streams deep in a pipeline you don’t own.

Mental Model

flowchart TB
  Loop["listener registered inside a loop / request handler"] -->|"each call adds a NEW listener"| Count["listenerCount keeps growing"]
  Count -->|"exceeds getMaxListeners() (default 10)"| Warn["MaxListenersExceededWarning"]
  Emit["emitter.emit('error', err)"] -->|"listener registered?"| Handled["'error' handler runs — process keeps going"]
  Emit -->|"no listener registered"| Crash["Node throws — process crashes"]
  Async["async listener throws"] -->|"captureRejections: false (default)"| Unhandled["unhandled rejection — crash"]
  Async -->|"captureRejections: true"| Handled

a growing listener count trips a warning; an unhandled 'error' event crashes the process; captureRejections routes async listener failures the same way

Trade-offs

Choice	Benefit	Cost
emitter.on() callback style	Works everywhere, zero dependencies, synchronous and predictable	Easy to leak — re-registering inside a loop/handler is a silent bug
events.once(emitter, name) (promise)	Reads like any other awaited call, composes with Promise.race/AbortSignal	Only fires once — not a replacement for a recurring on() listener
events.on(emitter, name) (async iterator)	for await reads top-to-bottom like a stream; backpressure-friendly	No automatic end — you must break yourself or rely on an 'end'/'close' event
captureRejections: true	Async listener errors become ordinary 'error' events instead of crashes	Off by default — every emitter you construct must opt in individually

Common Misconceptions

• “EventEmitter listeners run asynchronously, like a DOM event” — fact: .emit() calls every listener synchronously, in registration order, before emit() returns.
• “MaxListenersExceededWarning means something is broken” — fact: it’s a heuristic warning, not an error — the code keeps running. But it correctly flags the single most common EventEmitter bug: a listener added on every call to a function instead of once.
• “An unhandled 'error' event just gets ignored, like any other unlistened event” — fact: 'error' is special-cased — with zero listeners it is thrown, crashing the process.
• “An async listener’s thrown error is caught by emitter.on('error', ...) automatically” — fact: only if the emitter was constructed with captureRejections: true. Otherwise the rejection is unhandled and crashes the process independently of any 'error' listener.

Reading AI-generated code

• Is .on() called inside a loop, a request handler, a class constructor invoked per-request, or a re-render path — anywhere that runs more than once per process lifetime? Each call adds a brand-new listener that is never removed.
• Does anything that extends or wraps EventEmitter (a custom class, a socket, a stream) have zero 'error' listeners anywhere in the call chain? One unhandled 'error' emission crashes the whole process.
• Is an async function passed directly to .on() without captureRejections: true on the emitter and without an internal try/catch? Its thrown errors become unhandled rejections, not caught errors.
• Does code call events.on(emitter, name) and iterate with for await but never break or rely on an end condition? That’s a listener that never gets cleaned up, functionally the same leak as forgetting removeListener.

🐛 Spot the bug

const { EventEmitter } = require('node:events');
const http = require('node:http');

var bus = new EventEmitter();

var server = http.createServer(function(req, res) {
// registers a new listener on every single request
bus.on('request-logged', function(url) {
  console.log('logged:', url);
});
bus.emit('request-logged', req.url);
res.end('ok');
});

Show the answer

bus.on('request-logged', ...) is called inside the request handler, so a brand-new listener is registered on every incoming request and never removed. After 10 requests, Node prints MaxListenersExceededWarning; after thousands, the process leaks memory — every one of those listener closures stays alive, and every future emit('request-logged', ...) now runs all of them, multiplying the work per request. The fix is to register the listener once, outside the request handler, before server.listen() is called — the handler should only call bus.emit(...), never bus.on(...).

🟢 The one-line takeaway

.on() outside a loop/handler and one 'error' listener on everything that can emit one — those two habits prevent the two most common EventEmitter failures: silent listener leaks and crash-on-unhandled-error.

What is the key difference between emitter.on() and emitter.once()?

on() is synchronous; once() is asynchronous once() registers a listener that is automatically removed after the first emission on() can only listen to built-in events; once() works for custom events once() fires the listener immediately without waiting for emit()

When does an EventEmitter listener run relative to emitter.emit()?

Asynchronously — after the current call stack clears In the next microtask Synchronously — before emit() returns In the next setTimeout callback

Which Node.js built-in classes extend EventEmitter?

Only third-party libraries extend EventEmitter Buffer and process only http.Server, net.Socket, fs.ReadStream, and many more Only http.Server

What happens when this runs? const { EventEmitter } = require('node:events'); var e = new EventEmitter(); e.emit('error', new Error('boom')); console.log('after emit');

"after emit" is printed — emit() ignores events with no listeners Nothing is printed — the error event is silently dropped The error is thrown and the process crashes before "after emit" prints A MaxListenersExceededWarning is printed, then "after emit"

A function registers bus.on('saved', handler) every time it runs, and the function is called once per HTTP request. What is the observable symptom after ~10+ requests?

Nothing — Node deduplicates identical listener functions automatically A MaxListenersExceededWarning, and every future emit('saved') runs an ever-growing number of listeners The 11th call to the function throws a TypeError Node automatically calls bus.setMaxListeners() to raise the limit

An EventEmitter is constructed as new EventEmitter({ captureRejections: true }). What changes about a listener registered as emitter.on('work', async () => { throw new Error('x') })?

Nothing — captureRejections only affects synchronous listeners The thrown error becomes an unhandled rejection, same as without the option The rejection is routed to the emitter's 'error' event instead of becoming an unhandled rejection The listener runs synchronously instead of returning a promise

Submit

Mark as complete