events — EventEmitter

The backbone of Node.js's async model — EventEmitter, on/off/emit/once, error events, and async event patterns.

What it is, in plain English: EventEmitter is the foundation of Node.js's event-driven architecture. Almost everything in Node.js (streams, HTTP servers, file watchers) extends EventEmitter. You call emitter.on(event, listener) to subscribe, emitter.emit(event, ...args) to publish, and emitter.off(event, listener) to unsubscribe. The 'error' event is special — if emitted with no listener, Node.js crashes.

Where this bites you

emit() is synchronous: it calls each listener in turn, right there, before returning. If one listener throws, the error flies out of emit() into the code that emitted it, and the listeners after it never run. One failing email listener means the stock never gets updated, and the code that placed the order sees an exception it knows nothing about.

import { EventEmitter } from "events";

const orders = new EventEmitter();
orders.on("placed", (order) => {
  throw new Error(`email service down for order ${order.id}`);   // one listener fails...
});
orders.on("placed", (order) => {
  console.log("stock updated for", order.id);                     // ...so this one never runs
});

try {
  orders.emit("placed", { id: 42 });
  console.log("order saved");
} catch (e) {
  console.log("emit threw:", e.message);
}
// emit threw: email service down for order 42

Publishing and subscribing to events

import { EventEmitter } from "events";

const emitter = new EventEmitter();

// Subscribe (.on — fires every time):
emitter.on("data", (payload) => {
  console.log("Received:", payload);
});

// Subscribe once (.once — fires only the first time):
emitter.once("connect", () => {
  console.log("Connected! (fires once only)");
});

// Publish (emit an event):
emitter.emit("connect");              // "Connected! (fires once only)"
emitter.emit("connect");              // nothing — listener removed after first call
emitter.emit("data", { id: 1 });     // "Received: { id: 1 }"
emitter.emit("data", { id: 2 });     // "Received: { id: 2 }"

// Unsubscribe:
function handler(data) { console.log(data); }
emitter.on("event", handler);
emitter.off("event", handler);        // alias: removeListener()

Listeners are independent subscribers, so make each one responsible for its own failures. Catch inside the listener and report it, for example through the emitter's "error" event, so emit() carries on to the next listener and returns normally:

import { EventEmitter } from "events";

const orders = new EventEmitter();
orders.on("error", (e) => console.log("logged:", e.message));

orders.on("placed", (order) => {
  try {
    throw new Error(`email service down for order ${order.id}`);
  } catch (e) {
    orders.emit("error", e);           // report it; don't let it escape into emit()
  }
});
orders.on("placed", (order) => {
  console.log("stock updated for", order.id);
});

orders.emit("placed", { id: 42 });
console.log("order saved");
// logged: email service down for order 42
// stock updated for 42
// order saved

Extending EventEmitter

// Most Node.js built-ins extend EventEmitter:
import { EventEmitter } from "events";

class DatabaseConnection extends EventEmitter {
  async connect(url) {
    try {
      // ... connect to db ...
      this.emit("connect", { url, status: "connected" });
    } catch (e) {
      this.emit("error", e);  // ALWAYS handle 'error' event
    }
  }

  async query(sql) {
    const rows = []; // ... execute query ...
    this.emit("query", { sql, rowCount: rows.length });
    return rows;
  }

  close() {
    // ... close connection ...
    this.emit("close");
  }
}

const db = new DatabaseConnection();
db.on("connect", ({ url }) => console.log("Connected to:", url));
db.on("error",   (e) => console.error("DB error:", e.message));  // REQUIRED
db.on("close",   () => console.log("Disconnected"));

The error event is special

// If 'error' is emitted with no listener → Node.js CRASHES:
const emitter = new EventEmitter();
emitter.emit("error", new Error("oops"));  // ← throws the Error itself ("Unhandled 'error' event"): crash!

// Always add an error listener:
emitter.on("error", (err) => {
  console.error("Emitter error:", err.message);
  // handle or log — don't let it crash your server
});

Try It Yourself

// EventEmitter — the backbone of Node.js async architecture
// Available in Node.js, also usable in browsers via the events package

// In Node.js:
// import { EventEmitter } from "events";

// Browser-compatible simulation:
class EventEmitter {
  #listeners = new Map();

on(event, listener) {
    if (!this.#listeners.has(event)) this.#listeners.set(event, []);
    this.#listeners.get(event).push(listener);
    return this;  // chainable
  }

once(event, listener) {
    const wrapper = (...args) => {
      listener(...args);
      this.off(event, wrapper);
    };
    return this.on(event, wrapper);
  }

off(event, listener) {
    const list = this.#listeners.get(event) || [];
    this.#listeners.set(event, list.filter(l => l !== listener));
    return this;
  }

emit(event, ...args) {
    (this.#listeners.get(event) || []).forEach(l => l(...args));
    return this.#listeners.has(event);
  }

listenerCount(event) {
    return (this.#listeners.get(event) || []).length;
  }
}

// Example: a task queue built on EventEmitter
class TaskQueue extends EventEmitter {
  #tasks = [];
  #running = false;

add(task) {
    this.#tasks.push(task);
    this.emit("taskAdded", this.#tasks.length);
    if (!this.#running) this.#run();
    return this;
  }

async #run() {
    this.#running = true;
    while (this.#tasks.length) {
      const task = this.#tasks.shift();
      this.emit("taskStart", task.name);
      try {
        const result = await task.fn();
        this.emit("taskDone", task.name, result);
      } catch (e) {
        this.emit("taskError", task.name, e);
      }
    }
    this.#running = false;
    this.emit("drain");
  }
}

const queue = new TaskQueue();

queue
  .on("taskAdded", n  => console.log(`Task added. Queue: ${n}`))
  .on("taskStart", name => console.log(`Starting: ${name}`))
  .on("taskDone",  (name, r) => console.log(`Done: ${name} →`, r))
  .on("taskError", (name, e) => console.log(`Error in ${name}:`, e.message))
  .on("drain",     ()   => console.log("All tasks complete!"));

queue.add({ name: "fetch data",    fn: async () => ({ users: 42 }) });
queue.add({ name: "process",       fn: async () => "processed" });
queue.add({ name: "failing task",  fn: async () => { throw new Error("oops"); } });

Async events, max listeners, and promisify

// Wait for a one-time event with a Promise:
import { once } from "events";

// Wait for server to be ready:
const server = createServer(handler);
server.listen(3000);
await once(server, "listening");
console.log("Server is up!");

// Wrap event-based API in a Promise:
function readStreamToString(readable) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readable.on("data",  chunk => chunks.push(chunk));
    readable.on("end",   ()    => resolve(Buffer.concat(chunks).toString()));
    readable.on("error", reject);
  });
}

// Async iteration over events:
import { on } from "events";

async function processLines(readable) {
  for await (const [line] of on(readable, "line")) {
    processLine(line);
  }
}

// Max listeners warning (default: 10 — warns if more added):
emitter.setMaxListeners(20);       // increase for this instance
EventEmitter.defaultMaxListeners = 20;  // global default
// If you see "MaxListenersExceededWarning" — you have a listener leak!

EventTarget, AbortSignal, and Node.js EventEmitter spec

// Node.js 14+ has browser-compatible EventTarget:
const target = new EventTarget();
target.addEventListener("data", (event) => {
  console.log(event.detail);  // CustomEvent carries data in .detail
});
target.dispatchEvent(new CustomEvent("data", { detail: { id: 1 } }));

// AbortSignal as an event source:
const controller = new AbortController();
const { signal }  = controller;

// emitter.on() has no options argument (a { signal } passed there is ignored).
// The events.once() helper does take one — it rejects with AbortError on abort:
const [data] = await once(emitter, "data", { signal });
setTimeout(() => controller.abort(), 5000);

// EventEmitter vs EventTarget:
// EventEmitter: Node.js native, arbitrary event names, multiple args, error event
// EventTarget:  Web standard (browser-compatible), Event/CustomEvent objects, .detail for data

// Asynchronous event listeners (Node.js doesn't await them by default):
// If an async listener throws, the error won't be caught by the emitter.
// Use asyncLocalStorage for context propagation, or wrap with try/catch.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.