Node.js Events Module Guide

The events module provides the EventEmitter class for building event-driven applications. Here's how to use it effectively.

Basic EventEmitter#

import { EventEmitter } from 'node:events';

// Create emitter
const emitter = new EventEmitter();

// Listen for event
emitter.on('message', (data) => {
  console.log('Received:', data);
});

// Emit event
emitter.emit('message', 'Hello, World!');
// Received: Hello, World!

// Multiple arguments
emitter.on('user:login', (user, timestamp) => {
  console.log(`${user.name} logged in at ${timestamp}`);
});

emitter.emit('user:login', { name: 'John' }, new Date());

Once Listeners#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

// Listen only once
emitter.once('connect', () => {
  console.log('Connected!');
});

emitter.emit('connect'); // Connected!
emitter.emit('connect'); // Nothing happens

Custom Event Emitter Class#

import { EventEmitter } from 'node:events';

class Server extends EventEmitter {
  constructor() {
    super();
    this.connections = [];
  }

  start(port) {
    // Simulate starting server
    setTimeout(() => {
      this.emit('listening', port);
    }, 100);
  }

  addConnection(client) {
    this.connections.push(client);
    this.emit('connection', client);
  }

  close() {
    this.emit('close');
    this.connections = [];
  }
}

// Usage
const server = new Server();

server.on('listening', (port) => {
  console.log(`Server listening on port ${port}`);
});

server.on('connection', (client) => {
  console.log(`New connection: ${client.id}`);
});

server.on('close', () => {
  console.log('Server closed');
});

server.start(3000);
server.addConnection({ id: 'client-1' });

Error Handling#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

// Always handle error events
emitter.on('error', (error) => {
  console.error('Error occurred:', error.message);
});

// Emit error
emitter.emit('error', new Error('Something went wrong'));

// Unhandled errors crash the process
// If no error listener, emit('error') throws

// Check for error listeners
if (emitter.listenerCount('error') === 0) {
  emitter.on('error', (err) => console.error(err));
}

Async Events#

import { EventEmitter } from 'node:events';

class AsyncEmitter extends EventEmitter {
  async emitAsync(event, ...args) {
    const listeners = this.listeners(event);
    for (const listener of listeners) {
      await listener(...args);
    }
  }
}

const emitter = new AsyncEmitter();

emitter.on('process', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 100));
  console.log('Processed:', data);
});

// Wait for async handlers
await emitter.emitAsync('process', { id: 1 });
console.log('Done');

Event Names and Listeners#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

emitter.on('event1', () => {});
emitter.on('event1', () => {});
emitter.on('event2', () => {});

// Get event names
console.log(emitter.eventNames()); // ['event1', 'event2']

// Get listener count
console.log(emitter.listenerCount('event1')); // 2

// Get listeners
const listeners = emitter.listeners('event1');
console.log(listeners.length); // 2

// Get raw listeners (includes once wrappers)
const rawListeners = emitter.rawListeners('event1');

Removing Listeners#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

function handler(data) {
  console.log(data);
}

// Add listener
emitter.on('data', handler);

// Remove specific listener
emitter.off('data', handler);
// or
emitter.removeListener('data', handler);

// Remove all listeners for event
emitter.removeAllListeners('data');

// Remove all listeners for all events
emitter.removeAllListeners();

Prepending Listeners#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

emitter.on('message', () => console.log('Second'));

// Add to beginning of listener array
emitter.prependListener('message', () => console.log('First'));

// Once at beginning
emitter.prependOnceListener('message', () => console.log('Once First'));

emitter.emit('message');
// Once First
// First
// Second

Max Listeners#

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();

// Default is 10 listeners per event
// Get warning if exceeded

// Set max listeners
emitter.setMaxListeners(20);

// Get current max
console.log(emitter.getMaxListeners()); // 20

// Set for all emitters
EventEmitter.defaultMaxListeners = 15;

// Unlimited (use carefully)
emitter.setMaxListeners(0);

Event-Based Queue#

import { EventEmitter } from 'node:events';

class TaskQueue extends EventEmitter {
  constructor(concurrency = 1) {
    super();
    this.concurrency = concurrency;
    this.running = 0;
    this.queue = [];
  }

  push(task) {
    this.queue.push(task);
    this.emit('task:added', task);
    this.process();
  }

  async process() {
    while (this.running < this.concurrency && this.queue.length > 0) {
      const task = this.queue.shift();
      this.running++;
      this.emit('task:start', task);

      try {
        const result = await task();
        this.emit('task:complete', result);
      } catch (error) {
        this.emit('task:error', error);
      } finally {
        this.running--;
        this.process();
      }
    }

    if (this.running === 0 && this.queue.length === 0) {
      this.emit('drain');
    }
  }
}

// Usage
const queue = new TaskQueue(2);

queue.on('task:complete', (result) => console.log('Done:', result));
queue.on('drain', () => console.log('All tasks complete'));

queue.push(async () => {
  await delay(100);
  return 'Task 1';
});

Pub/Sub Pattern#

import { EventEmitter } from 'node:events';

class PubSub extends EventEmitter {
  subscribe(channel, callback) {
    this.on(channel, callback);
    return () => this.off(channel, callback);
  }

  publish(channel, data) {
    this.emit(channel, data);
  }

  unsubscribe(channel, callback) {
    if (callback) {
      this.off(channel, callback);
    } else {
      this.removeAllListeners(channel);
    }
  }
}

// Usage
const pubsub = new PubSub();

const unsubscribe = pubsub.subscribe('news', (article) => {
  console.log('New article:', article.title);
});

pubsub.publish('news', { title: 'Breaking News!' });

unsubscribe(); // Remove subscription

Typed Events (TypeScript)#

import { EventEmitter } from 'node:events';

interface UserEvents {
  login: [user: User];
  logout: [userId: string];
  error: [error: Error];
}

class TypedEmitter<T extends Record<string, any[]>> {
  private emitter = new EventEmitter();

  on<K extends keyof T>(event: K, listener: (...args: T[K]) => void) {
    this.emitter.on(event as string, listener);
    return this;
  }

  emit<K extends keyof T>(event: K, ...args: T[K]) {
    return this.emitter.emit(event as string, ...args);
  }

  off<K extends keyof T>(event: K, listener: (...args: T[K]) => void) {
    this.emitter.off(event as string, listener);
    return this;
  }
}

// Usage
const userEmitter = new TypedEmitter<UserEvents>();

userEmitter.on('login', (user) => {
  console.log(user.name); // TypeScript knows user type
});

userEmitter.emit('login', { id: '1', name: 'John' });

Promise-Based Events#

import { EventEmitter, once } from 'node:events';

const emitter = new EventEmitter();

// Wait for event with promise
async function waitForConnection() {
  const [socket] = await once(emitter, 'connect');
  console.log('Connected:', socket);
}

// With timeout
async function waitWithTimeout(event, timeout) {
  const ac = new AbortController();
  const timeoutId = setTimeout(() => ac.abort(), timeout);

  try {
    const result = await once(emitter, event, { signal: ac.signal });
    clearTimeout(timeoutId);
    return result;
  } catch (error) {
    if (error.name === 'AbortError') {
      throw new Error(`Timeout waiting for ${event}`);
    }
    throw error;
  }
}

Best Practices#

Patterns:
✓ Always handle 'error' events
✓ Use descriptive event names
✓ Namespace events (user:login)
✓ Document event signatures

Memory:
✓ Remove listeners when done
✓ Use once() for single events
✓ Set appropriate maxListeners
✓ Clean up in destroy methods

Async:
✓ Handle async errors
✓ Use once() for promises
✓ Consider event ordering
✓ Emit after state changes

Avoid:
✗ Circular event emissions
✗ Heavy work in handlers
✗ Ignoring error events
✗ Memory leaks from listeners

The events module provides a solid foundation for event-driven architecture in Node.js. Extend EventEmitter for custom classes, always handle error events, and manage listeners properly to avoid memory leaks. Use typed events in TypeScript for better developer experience and use the once function for promise-based event handling.