Module F-9 — Event Emitters & Node's Event-Driven Core

Why? If you accidentally register a new listener on every request without removing the old one, you have a memory leak — the listener count grows unboundedly and the listeners are never garbage collected.

// ❌ BAD — registers a new listener on every call
app.get('/stream', (req, res) => {
  pipeline.on('record', (record) => {
    res.write(JSON.stringify(record));
  });
});
 
// After 11 requests: MaxListenersExceededWarning
// After 1000 requests: 1000 listeners, memory leak

Production story: a real-time settlement-webhook processor built its own pub/sub on top of a single shared EventEmitter, and registered a new listener per incoming request without ever removing it. At roughly 2K TPS, the listener count climbed into the tens of thousands within 36 hours, and the pod was eventually OOM-killed. This is the exact failure MaxListenersExceededWarning exists to catch — except someone had silenced it early on by raising defaultMaxListeners to make the warning go away, rather than fixing the leak it was pointing at. Raising the limit is sometimes the right call (see below), but only when the higher listener count is deliberate and bounded — not as a way to stop the warning from firing.

The fix: remove listeners when you are done with them.

// ✅ CORRECT — remove the listener when the request ends
app.get('/stream', (req, res) => {
  function onRecord(record) {
    res.write(JSON.stringify(record) + '\n');
  }
 
  pipeline.on('record', onRecord);
 
  // Remove when client disconnects
  req.on('close', () => {
    pipeline.off('record', onRecord);
  });
});

If you genuinely need many listeners (e.g. many subscribers to a shared emitter), increase the limit:

emitter.setMaxListeners(50);
// or globally:
EventEmitter.defaultMaxListeners = 50;

But increasing the limit should be a deliberate decision with a comment explaining why — not a way to silence the warning.

---

Synchronous vs Asynchronous Listeners

EventEmitter is synchronous by default. emit() calls all listeners immediately, in the order they were registered, before returning. There is no queuing or async scheduling:

emitter.on('ping', () => console.log('listener 1'));
emitter.on('ping', () => console.log('listener 2'));
 
console.log('before emit');
emitter.emit('ping');
console.log('after emit');
 
// Output:
// before emit
// listener 1
// listener 2
// after emit

This means if a listener does heavy synchronous work, it blocks the event loop — same as any other synchronous code. Keep listeners fast, or offload heavy work:

// ❌ Blocks the event loop
emitter.on('request', (data) => {
  const result = heavyCpuWork(data); // blocks everything
  saveToDb(result);
});
 
// ✅ Don't block — hand off async work
emitter.on('request', async (data) => {
  const result = await heavyCpuWork(data);  // if async
  await saveToDb(result);
});

Note: if a listener is async and throws, the rejection is unhandled by default. The emitter does not await its listeners. For async event handling in production, always add try/catch inside the listener or use a wrapper.

captureRejections: Node's Built-in Fix

Node has an actual built-in answer to that "unhandled by default" problem: captureRejections. Enable it per-emitter or globally, and a rejected promise from an async listener is routed to the emitter's 'error' event instead of becoming an unhandled rejection:

// Per-emitter
const emitter = new EventEmitter({ captureRejections: true });
 
emitter.on('data', async (chunk) => {
  throw new Error('boom'); // rejects — captured instead of unhandled
});
 
emitter.on('error', (err) => {
  console.error('Caught via captureRejections:', err.message);
});
 
emitter.emit('data', 'x');

// Globally, for every EventEmitter created afterward in the process
import { EventEmitter } from 'node:events';
EventEmitter.captureRejections = true;

This doesn't replace try/catch inside listeners that need custom recovery logic, but as a safety net it turns a silent, hard-to-trace unhandled rejection into a normal, handleable 'error' event — worth turning on by default in most services.

---

Async-Friendly Helpers: events.once() and events.on()

Alongside the EventEmitter class, node:events exports two standalone helpers that make waiting for events feel like ordinary async/await code instead of manual listener registration.

events.once(emitter, name) — wait for a single event as a Promise:

import { EventEmitter, once } from 'node:events';
 
const emitter = new EventEmitter();
 
setTimeout(() => emitter.emit('ready', 'ok'), 100);
 
const [result] = await once(emitter, 'ready'); // resolves when 'ready' fires
console.log(result); // 'ok'

This is the async/await equivalent of emitter.once('ready', callback) — useful anywhere you would otherwise hand-wrap a one-off event in new Promise((resolve) => emitter.once(...)).

events.on(emitter, name) — async-iterate over every occurrence of an event:

import { on } from 'node:events';
 
async function processRecords(pipeline) {
  for await (const [record] of on(pipeline, 'record')) {
    console.log('Processing:', record);
    // break out of the loop whenever you want to stop iterating
  }
}

This turns a stream of events into an async iterable you can for await over — a natural fit for the "many events over time" pattern this module keeps coming back to, without registering and later removing a callback by hand.

---

How Node.js Uses EventEmitter Internally

You have been using EventEmitters since F-1 without realising it. Every major I/O object in Node.js extends EventEmitter:

HTTP Server:

import http from 'node:http';
 
const server = http.createServer();
 
// These are EventEmitter.on() calls
server.on('request', (req, res) => {
  res.end('Hello');
});
 
server.on('error', (err) => {
  console.error('Server error:', err);
});
 
server.on('close', () => {
  console.log('Server closed');
});
 
server.listen(3000);

http.createServer() returns an http.Server which extends EventEmitter. The request callback shorthand (createServer(handler)) is simply .on('request', handler).

HTTP Request (IncomingMessage):

server.on('request', (req, res) => {
  let body = '';
 
  req.on('data', (chunk) => {   // stream of data chunks
    body += chunk.toString();
  });
 
  req.on('end', () => {         // all data received
    console.log('Body:', body);
    res.end('Received');
  });
 
  req.on('error', (err) => {
    console.error('Request error:', err);
  });
});

File Streams:

import fs from 'node:fs';
 
const readable = fs.createReadStream('./large-file.csv');
 
readable.on('data', (chunk) => {
  // process chunk
});
 
readable.on('end', () => {
  console.log('File fully read');
});
 
readable.on('error', (err) => {
  console.error('Stream error:', err);
});

Process itself:

process.on('exit', (code) => {
  console.log('Exiting with code:', code);
});
 
process.on('SIGTERM', () => {
  console.log('Received SIGTERM — shutting down');
  process.exit(0);
});

process is itself an EventEmitter.

---

EventEmitter vs Callbacks vs Promises

You now have three async patterns. When to use each:

The key distinction: Promises resolve once. EventEmitters fire many times. A file read finishes once → Promise. A server receives many requests → EventEmitter. A data pipeline processes thousands of records → EventEmitter.

---

Practical Pattern: Internal Event Bus

A lightweight event bus for decoupling modules inside a single Node.js process:

// src/events/bus.js
import { EventEmitter } from 'node:events';
 
// Singleton event bus — shared across the application
export const bus = new EventEmitter();
bus.setMaxListeners(50);
 
// Event name constants — prevents typos
export const Events = {
  USER_CREATED: 'user.created',
  POST_PUBLISHED: 'post.published',
  ORDER_PLACED: 'order.placed',
  EMAIL_REQUESTED: 'email.requested',
};

// src/routes/users.js
import { bus, Events } from '../events/bus.js';
 
router.post('/', async (req, res, next) => {
  try {
    const user = await prisma.user.create({ data: req.body });
    res.status(201).json(user);
 
    // Emit after responding — don't block the response
    bus.emit(Events.USER_CREATED, user);
  } catch (err) {
    next(err);
  }
});

// src/listeners/email.js
import { bus, Events } from '../events/bus.js';
 
bus.on(Events.USER_CREATED, async (user) => {
  try {
    await sendWelcomeEmail(user.email, user.name);
  } catch (err) {
    console.error('Failed to send welcome email:', err.message);
    // Don't crash the process — log and move on
  }
});

// src/index.js — register listeners at startup
import './listeners/email.js';
import './listeners/analytics.js';

This pattern — emit from routes, listen in separate modules — keeps business logic out of HTTP handlers and makes the system easy to extend. Adding a new action when a user is created means adding a new listener file, not modifying the route.

---

Summary

• EventEmitter is Node.js's observer pattern. on() registers listeners, emit() fires them.
• once() for one-time listeners. off() to remove them. listenerCount() to check how many are attached.
• Extend EventEmitter for your own classes that emit events over time (pipelines, connection managers, worker pools).
• Always register an 'error' listener. An unhandled 'error' event crashes the process.
• Memory leaks happen when you register listeners without removing them. Use off() or once() appropriately.
• EventEmitter is synchronous. Listeners run inline when emit() is called. Async listeners need try/catch inside them, or captureRejections: true as a safety net.
• events.once() and events.on() are async-friendly helpers — await a single event as a Promise, or for await iterate over every occurrence.
• Node.js internals use EventEmitter everywhere — HTTP server, IncomingMessage, streams, process itself.
• Use EventEmitters for streams of events over time. Use Promises for one-time results. Use callbacks only when working with legacy APIs.

---

This completes Phase 1 — Foundation. You now have the mental models, tools, and patterns to understand and build basic Node.js applications. Phase 2 takes all of this and builds it into production-quality application architecture: authentication, TypeScript, testing, security, and deployment.

Phase 1 recap: Runtime model → Module system → File I/O → Async programming → npm → Express APIs → Databases → Project structure → Event-driven core. Every concept in Phase 2 and Phase 3 builds directly on one or more of these.

---