Node.js Events

import { EventEmitter } from 'node:events';

const shop = new EventEmitter();

shop.on('order', (id, total) => {
  console.log(`Order ${id} for £${total}`);
});

shop.emit('order', 1042, 59.9);   // runs every 'order' listener

• on(name, listener) registers a function to run every time the event is emitted.
• emit(name, ...args) triggers the event and passes any arguments to the listeners.
• Listeners run synchronously, in the order they were added, before emit returns.
• Event names are strings; use clear, consistent names such as 'order', 'order:paid' or 'user-signed-in'.

• once(name, listener) runs the listener only the first time the event is emitted, then removes it automatically.
• off(name, listener) (also removeListener) removes a specific listener. You need a reference to the same function, so define it with a name rather than inline.
• listenerCount(name) tells you how many listeners are registered.
• Node prints a MaxListenersExceededWarning if more than 10 listeners are added for one event. That usually means a listener is being added repeatedly, for example on every request, which is a memory leak.

'error' is special. If an emitter emits 'error' and no listener is registered for it, Node throws the error, which crashes the program if nothing catches it:

emitter.on('error', (err) => {
  console.error('Something went wrong:', err.message);
});

Always add an 'error' listener to emitters that can fail, such as streams, servers and sockets.

Extend EventEmitter to give a class its own events:

class Download extends EventEmitter {
  start() {
    this.emit('progress', 50);
    this.emit('done', 'file.zip');
  }
}

The once function from node:events returns a promise that resolves the next time an event fires, so you can await it: const [file] = await once(download, 'done');. It rejects if an 'error' event happens first.

emit doesn't wait for listeners and ignores what they return. If a listener is an async function and it throws, the error becomes a rejected promise that emit never sees, so even an 'error' listener won't hear about it. Create the emitter with captureRejections: true and Node routes those rejections to the 'error' event for you:

const store = new EventEmitter({ captureRejections: true });
store.on('save', async () => { throw new Error('disk full'); });
store.on('error', (err) => console.log('caught:', err.message));
store.emit('save');   // later prints "caught: disk full"

A few other tools help with ordering and flow:

• prependListener(name, fn) adds a listener to the front of the queue, so it runs before ones added earlier.
• emit returns true if the event had listeners and false if nobody was listening, which helps when debugging a missing reaction.
• The on function from node:events (not the method) turns an event into an async iterator: for await (const [n] of on(ticker, 'tick')) handles each event in turn. The loop never finishes by itself, so pass { signal } from an AbortController to stop it; the loop then throws an AbortError.