EventEmitter Patterns

Use Node.js EventEmitter for publish-subscribe patterns, with typed events and async handlers.

Recipe

Quick-reference recipe card - copy-paste ready.

import { EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
 
// Subscribe
emitter.on("message", (text: string) => {
  console.log("got:", text);
});
 
// One-shot subscribe
emitter.once("ready", () => {
  console.log("ready fired once");
});
 
// Unsubscribe
const handler = (n: number) => console.log(n);
emitter.on("tick", handler);
emitter.off("tick", handler);
 
// Publish
emitter.emit("message", "hello");
emitter.emit("ready");
 
// Always handle errors - unhandled 'error' crashes the process
emitter.on("error", (err) => {
  console.error("emitter error:", err);
});
emitter.emit("error", new Error("boom"));

When to reach for this: Decoupling producers from consumers inside a single Node process - job queues, log pipelines, stream lifecycle, plugin hooks.

Working Example

A typed EventEmitter wrapper class for a job queue.

import { EventEmitter } from "node:events";
 
// Type map: event name to argument tuple
interface JobEvents {
  "job:start": [id: string];
  "job:progress": [id: string, percent: number];
  "job:complete": [id: string, result: unknown];
  "job:error": [id: string, err: Error];
}
 
class JobQueue extends EventEmitter {
  override on<K extends keyof JobEvents>(
    event: K,
    listener: (...args: JobEvents[K]) => void
  ): this {
    return super.on(event, listener as (...args: unknown[]) => void);
  }
 
  override emit<K extends keyof JobEvents>(
    event: K,
    ...args: JobEvents[K]
  ): boolean {
    return super.emit(event, ...args);
  }
 
  async run(id: string, task: (report: (p: number) => void) => Promise<unknown>) {
    this.emit("job:start", id);
    try {
      const result = await task((percent) => {
        this.emit("job:progress", id, percent);
      });
      this.emit("job:complete", id, result);
    } catch (err) {
      this.emit("job:error", id, err as Error);
    }
  }
}
 
const queue = new JobQueue();
 
queue.on("job:start", (id) => console.log(`[${id}] start`));
queue.on("job:progress", (id, pct) => console.log(`[${id}] ${pct}%`));
queue.on("job:complete", (id, result) => console.log(`[${id}] done`, result));
queue.on("job:error", (id, err) => console.error(`[${id}] failed`, err));
 
await queue.run("job-1", async (report) => {
  for (let i = 0; i <= 100; i += 25) {
    report(i);
    await new Promise((r) => setTimeout(r, 50));
  }
  return { ok: true };
});

What this demonstrates:

• Typed overrides for on and emit give full autocomplete and payload safety.
• Error events are explicit - no silent failures.
• The producer (run) and consumers (the on handlers) are fully decoupled.

Deep Dive

How It Works

EventEmitter keeps an internal map of event name to an array of listener functions. emit iterates that array synchronously, calling each listener in the order it was registered. There is no built-in queue and no backpressure - listeners run on the current tick unless they themselves schedule async work.

on appends, once appends a wrapper that removes itself after the first call, off (alias removeListener) removes by reference, and removeAllListeners(event?) clears everything.

The 'error' event is special: if nothing is listening when you emit('error', err), Node throws the error and, if uncaught, terminates the process.

Variations

Typed EventEmitter with generics. The JobQueue pattern above is the idiomatic approach in modern Node + TypeScript. Libraries like tsee or typed-emitter package the same idea.

Async iteration with events.on(). Consume events like a stream:

import { on, EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
 
setTimeout(() => emitter.emit("data", 1), 10);
setTimeout(() => emitter.emit("data", 2), 20);
 
for await (const [value] of on(emitter, "data")) {
  console.log("value:", value);
  if (value === 2) break;
}

once as a Promise. Great for waiting on a single lifecycle event:

import { once, EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
setTimeout(() => emitter.emit("ready", "ok"), 50);
 
const [value] = await once(emitter, "ready");
console.log(value); // "ok"

Extending EventEmitter. Subclass when the emitter is the primary identity of your object (the JobQueue example). Compose (have an internal #emitter) when events are a secondary concern.

Removing all listeners. emitter.removeAllListeners() with no argument nukes every event; with an argument, only that event. Handy in teardown but dangerous if you do not own the emitter.

Max listeners warning. Node prints MaxListenersExceededWarning at 11 listeners per event. Raise with emitter.setMaxListeners(50) or globally via EventEmitter.defaultMaxListeners. The warning is a leak hint, not an error.

TypeScript Notes

Define an event type map as an interface where each key is the event name and each value is a tuple of the listener arguments - for example interface Events \{ start: [id: string]; progress: [percent: number] \}. Use this map with a generic base class like TypedEmitter<Events> (from typed-emitter), or write your own overrides of on, once, off, and emit that constrain the event name with K extends keyof Events and the args with Events[K]. This gives you autocomplete on event names and compile-time checking of payload shapes.

Gotchas

1. Forgetting error handlers crashes the process. Emitting 'error' with no listener throws. Always attach an error listener before any code path that can emit one.
2. MaxListeners warning at 10. Adding the same handler in a loop, or subscribing inside a React effect without cleanup, quickly exceeds the default. The warning is printed once per emitter per event - easy to miss.
3. emit is synchronous. Listeners run in registration order on the same tick. A slow synchronous listener blocks every other listener and the event loop.
4. once does not prevent other registrations. It only wraps that one handler. Other on listeners keep firing forever.
5. Anonymous listeners cannot be removed. emitter.off("x", () => {}) passes a brand-new function reference and removes nothing. Store the handler in a variable if you ever need to remove it.
6. Throwing inside a listener. A synchronous throw propagates out of emit and can take down unrelated listeners. Wrap risky work in try/catch or use async handlers that reject into an error event.
7. Async listeners are fire-and-forget. emit does not await anything. Rejected promises in listeners become unhandled rejections unless you attach .catch inside the listener.

Alternatives

FAQs

Related

• docs/nodejs-scripts/http-server.md - HTTP servers, which are themselves EventEmitter instances.
• docs/browser-apis/postmessage-basics.md - cross-window messaging, a browser-side pub-sub pattern.
• docs/react-hooks/use-effect.md - subscribing and cleaning up event listeners from React.