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.

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()

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"));  // ← UnhandledEmitterError: 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("data", handler, { signal });  // Node.js 22+ — auto-removes on abort
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.