EventEmitter

"Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically." — Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides, Design Patterns (1994)

Part II was about results that arrive once. A promise settles, exactly one time, and everything built on it — await, the combinators, cancellation — assumes that single transition. This Part is about results that arrive repeatedly, and about data that is too large to hold at all.

It starts with EventEmitter, because most of Node is made of it. A TCP socket emits data, end, error and close. An HTTP server emits request and connection. A readable stream emits data, readable, end and error. The process itself emits exit, uncaughtException and warning. If you have written Node at all, you have used EventEmitter — the question is whether you have used it deliberately.

The class is about a hundred lines of quite ordinary JavaScript, and the reason to know it precisely is that its behaviour differs from promises in exactly the places you would not think to check. emit is completely synchronous. Listeners run in registration order, on the caller's stack, before emit returns — which is the opposite of the always-asynchronous guarantee the last three chapters relied on. Nothing is queued, nothing is deferred, and a slow listener blocks the emitter.

There is no events module in this playground, so — as with the module loaders — the chapter builds one. The implementation below reproduces the behaviour of real Node's EventEmitter, including the subtle parts, and every claim was checked against it.

A result that arrives more than once

The distinction from a promise is not a detail; it decides which tool the problem needs.

Three properties fall out of that contrast, and each is a reason to pick one or the other.

A promise has memory; an emitter does not. Await a settled promise a year later and you get the value. Attach a listener one millisecond after an event fired and you have missed it permanently. That makes emitters unsuitable for anything where the consumer might arrive late — a "ready" signal that fires before the listener attaches is a classic and maddening startup bug.

A promise has exactly one outcome; an emitter has none in particular. There is no completion, no return value that composes, nothing for await to unwrap. This is why you cannot await an emitter directly, and why §5 is about bridging.

A promise's failure is part of its type; an emitter's is a convention. Rejection is one of the two settled states. An error event is just an event named "error" — with, as §3 shows, one special rule attached to it.

Building the emitter

The whole class, with the semantics that matter, in about fifty lines.

Five design decisions in that code, each matching real Node.

emit returns a boolean — whether anything was listening. Rarely useful, occasionally exactly what you need to decide whether to fall back.

once is on plus a self-removing wrapper. It removes itself before invoking the listener, so a listener that throws is still removed and cannot fire twice.

The wrapper carries .listener, so off(event, originalFunction) can find it. Without that, a once listener would be unremovable except by the wrapper you never see.

off removes only the first match. Registering the same function twice creates two listeners and needs two removals — a genuine surprise, and a real source of half-removed handlers.

The listener array is copied before dispatch. The big question's subject, and the reason a listener may safely modify the listener list.

emit is synchronous — and error is special

This is where instincts trained on promises actively mislead.

Three rules, all of which contradict something you learned in Part II.

Listeners are called synchronously, in order, on the caller's stack. emit is a function call loop. If you need a listener's work deferred, you must defer it yourself.

A slow listener blocks everything. emit returned after 30 ms because the listener spun for 30 ms. This is the Part I blocking problem arriving through a side door: a CPU-heavy listener on a hot event stalls the entire loop, and the stack trace during profiling shows emit, not your handler.

An error event with no listener throws. This is the one genuinely special-cased event name in the class. The reasoning is sound — an unobserved error is worse than a crash — and the consequence is that every long-lived emitter needs an error listener, or one bad socket takes the process down. The error is thrown synchronously from emit, so it surfaces wherever the emit happened, which is usually deep inside library code.

Removal, duplicates, and mutation during dispatch

Every trap in this section produces a program that works and leaks, or works and half-works.

The three traps have one thing in common: none of them throws.

Anonymous listeners are permanent. off compares function identity, and an inline arrow written twice is two different objects. Any listener you intend to remove must be stored in a variable — which is also why once exists, since it removes itself.

Duplicate registration is allowed and silent. The same function added twice fires twice per emit, and one off leaves one behind. This shows up when a setup function runs more than once — a reconnect handler, a re-initialised module — and the symptom is an action happening twice rather than an error.

Dispatch is unaffected by mutation, because of the copy. Worth knowing in both directions: a listener that adds a listener will not see it fire on the current emit either.

Left unaddressed, these produce the classic leak. Node's MaxListenersExceededWarning at eleven listeners exists precisely for it — the number is arbitrary, and the warning is a heuristic for "you are probably adding in a loop and never removing".

Bridging events and promises

Most real code needs both: an emitter for the ongoing stream, and a promise for "wake me when this particular thing happens".

Node ships this bridge, and a second one for the repeating case:

import { once, on } from "node:events";

// once(): the next occurrence of one event, as a promise.
// It resolves to an ARRAY of the emitted arguments, not a single value.
const [sessionId, options] = await once(connection, "ready");

// on(): every occurrence, as an async iterable.
for await (const [chunk] of on(socket, "data")) {
  process(chunk);              // yields arg arrays, same as once()
}

Three things to know when using either.

once resolves to an array, because an event can carry several arguments and a promise resolves to one value. Destructure it.

Always handle error too. Both helpers do this for you; a hand-rolled bridge that forgets leaves the promise pending forever when the operation fails, which is a hang rather than an error.

on as an async iterator does not apply backpressure. Events keep arriving whether or not your loop has consumed the previous one, and they queue in memory. That is exactly the problem streams exist to solve, and it is the subject of the next two chapters.

Common Mistakes

1. Expecting an emitter to remember. A listener attached after the event fired has missed it permanently — the classic "ready fired before I subscribed" startup bug.

2. Assuming emit is asynchronous. Listeners run synchronously on the caller's stack, before emit returns.

3. Doing heavy work in a listener. emit waits for it, so a CPU-bound listener on a hot event blocks the loop.

4. No error listener on a long-lived emitter. The emit throws from inside library code, and since Node 15 that terminates the process.

5. Trying to remove an anonymous listener. off compares identity; an inline arrow written twice is two objects.

6. Registering the same function twice by accident. Two listeners, two calls per emit, and one off removes only one.

7. Request-scoped listeners on a process-scoped emitter. The standard leak; each retains its whole request closure.

8. Ignoring MaxListenersExceededWarning. It is a heuristic for exactly that leak, not noise.

9. Depending on listener order implicitly. It is registration order, and a refactor that swaps two on calls silently changes behaviour.

10. A hand-rolled event-to-promise bridge without an error path. On failure the promise stays pending forever — a hang, not an error.

Interview Corner

Hands-on

Summary

• A promise is one remembered outcome; an emitter is many remembered by nobody. A listener attached late has missed the event permanently.
• emit is synchronous — listeners run in registration order, on the caller's stack, before emit returns.
• A slow listener blocks the loop, and profiles as time spent in emit rather than in your handler.
• emit copies the listener array before dispatching, so removals during dispatch affect the next emit, not the current one.
• once is on plus a self-removing wrapper, which carries .listener so off(original) can find it.
• off removes only the first match, so a function registered twice needs two removals.
• Anonymous listeners cannot be removed — off compares identity.
• An error event with no listener throws, which since Node 15 terminates the process.
• MaxListenersExceededWarning is a leak heuristic, usually request-scoped listeners on a process-scoped emitter.
• Bridge to a promise with events.once — it resolves to an argument array, and it handles error so failures reject rather than hang.

The bridge at the end of this chapter has a gap the last paragraph named: an async iterator over events keeps receiving whether or not you have consumed the previous one, and the surplus queues in memory. That is fine for a click handler and fatal for a file. The next chapter is about streams — the abstraction Node uses for data that does not fit in memory, and which exists precisely to make "arrives in pieces" composable. The chapter after it is about the property that makes streaming actually work rather than merely postponing the problem: backpressure, the ability of a slow consumer to tell a fast producer to wait.