Events and EventEmitter

1The Core Pattern

EventEmitter (from the built-in events module) is the foundation Node's own APIs are built on — streams, http.Server, child_process, process itself all extend or use it. It implements the classic observer pattern: objects emit named events, and any number of listener functions can subscribe to react when that event fires.

const EventEmitter = require("events");

const emitter = new EventEmitter();

emitter.on("greet", (name) => {
  console.log(`Hello, ${name}!`);
});

emitter.emit("greet", "Ana"); // "Hello, Ana!" — runs listener(s) SYNCHRONOUSLY, right here

.emit() calls every registered listener for that event synchronously, in registration order, before .emit() itself returns — this is not a queued or async dispatch (contrast with a browser's DOM events, which can involve capture/bubble phases and different scheduling).

2Extending EventEmitter — the Standard Node Pattern

Almost nobody instantiates EventEmitter directly in real code; the standard pattern is to extend it so your own class becomes an emitter:

const EventEmitter = require("events");

class Downloader extends EventEmitter {
  start(url) {
    this.emit("start", url);
    // ... simulate work ...
    setTimeout(() => this.emit("progress", 50), 10);
    setTimeout(() => this.emit("done", { url, bytes: 1024 }), 20);
  }
}

const dl = new Downloader();
dl.on("start", (url) => console.log("starting", url));
dl.on("progress", (pct) => console.log("progress:", pct));
dl.on("done", (result) => console.log("done:", result));
dl.start("http://example.com/file.zip");

This is exactly how fs.createReadStream, http.Server, and child_process.spawn()'s return values work internally — they're all EventEmitter subclasses with domain-specific events layered on top.

3on vs once vs off

const emitter = new EventEmitter();

function handler(msg) { console.log("got:", msg); }

emitter.on("msg", handler);      // persistent — fires every time
emitter.once("msg", (msg) => {   // fires ONCE, then auto-removes itself
  console.log("first time only:", msg);
});

emitter.emit("msg", "a"); // both fire
emitter.emit("msg", "b"); // only `handler` fires now

emitter.off("msg", handler);     // (alias: removeListener) — must pass the SAME function reference
emitter.emit("msg", "c");        // nothing fires

Removing a listener requires the exact same function reference that was registered — an anonymous inline arrow function passed to .on() can never be .off()'d later, because there's no way to refer back to it.

4Multiple Listeners and Removal at Scale

emitter.removeAllListeners("msg");   // remove every listener for one event
emitter.removeAllListeners();        // remove ALL listeners for ALL events — dangerous in shared code

console.log(emitter.listenerCount("msg")); // how many are currently registered
console.log(emitter.eventNames());          // array of every event name with at least one listener

5Error Events Are Special

const emitter = new EventEmitter();

emitter.emit("error", new Error("boom")); // throws and CRASHES the process — no 'error' listener registered

emitter.on("error", (err) => {
  console.error("handled:", err.message); // now it's just a normal callback, process survives
});
emitter.emit("error", new Error("boom")); // caught by the listener above, no crash

The "error" event name is hard-coded as special inside EventEmitter: emitting it with zero listeners attached throws the error synchronously out of .emit(), which (if nothing catches it) crashes the process. This is a deliberate design choice — a raised error must not be silently swallowed just because nobody happened to be listening — but it means every long-lived EventEmitter-based object (especially streams and sockets) needs an 'error' listener in production code, full stop.

6Async Work Inside Listeners

emitter.on("data", async (chunk) => {
  await process(chunk); // EventEmitter has NO idea this listener is async
});

.emit() does not await anything — it calls each listener and moves to the next one immediately, regardless of whether a listener returns a Promise. An async listener that rejects produces an unhandled promise rejection, not a caught error inside the emitter; .emit()'s return value only tells you whether there WAS at least one listener (a boolean), never whether they succeeded.

7emitter.on(...) Chaining and Prepending

emitter.on("x", () => {}).on("y", () => {}); // .on() returns `this`, so calls chain

emitter.prependListener("x", fn); // registers `fn` to run FIRST, ahead of already-registered listeners

const emitter = new EventEmitter();
emitter.on("x", () => {});
console.log(emitter._events.x); // a single function

emitter.on("x", () => {});
console.log(Array.isArray(emitter._events.x)); // true — promoted to an array once there are 2+

const emitter = new EventEmitter();
emitter.setMaxListeners(5); // default is 10

for (let i = 0; i < 11; i++) {
  emitter.on("tick", () => {}); // triggers a MaxListenersExceededWarning after the 11th
}

⚠️ Common Pitfalls

1. Emitting "error" with no listener attached — crashes the process. Every long-lived emitter (streams, sockets, servers) needs an 'error' handler in real code.
2. Passing a fresh arrow function to .off(), expecting it to remove a previously .on()'d listener — reference equality fails because it's a different function object, even if the code looks identical.
3. Registering a new listener inside a hot loop or per-request handler without ever removing it — the classic listener leak; watch for the MaxListenersExceededWarning as a real signal, not noise to suppress.
4. Assuming .emit() waits for async listeners — it doesn't; it fires-and-forgets each listener call, so ordering guarantees and error handling for async work inside a listener are entirely on you.
5. Calling removeAllListeners() with no arguments on a shared/library-owned emitter — wipes listeners for every event, including ones other code registered; prefer removing your own specific listener or event name.

📋 Quick Reference

new EventEmitter() / class X extends EventEmitter → the base pattern
.on(name, fn) / .addListener(name, fn) → persistent listener
.once(name, fn)                          → fires once, then auto-removed
.off(name, fn) / .removeListener(name, fn) → needs the SAME function reference
.emit(name, ...args)                       → calls listeners SYNCHRONOUSLY, returns boolean (had listeners?)
.removeAllListeners([name])                  → strips listeners for one event, or ALL events if omitted
.listenerCount(name) / .eventNames()          → introspection
.setMaxListeners(n) / EventEmitter.defaultMaxListeners → leak-detection threshold (default 10)
'error' event                                   → special: throws/crashes if emitted with zero listeners
_events                                          → internal map: function, or array once 2+ listeners

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: node_events_eventemitter_theory.md · generated by tools/build_lessons.py