Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Events and Timers

Node.js emitter.on() method

Reference for emitter.on() and addListener() in Node.js: registering listeners, chaining, duplicates, the this value and the newListener event.

emitter.on(eventName, listener) registers a function that runs every time the emitter emits eventName. addListener() is an exact alias. The call returns the emitter, so registrations can be chained.

Registering a listener does not call it, and it does not check whether the event has ever been emitted or ever will be. Listeners that were added before the emit() call are the only ones that run.

NODE
emitter.on('data', (chunk) => console.log(chunk));

Try it

Node.js Registering and chaining

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Duplicates and this

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
emitter.on(eventName: string | symbol, listener: (...args: any[]) => void): this
emitter.addListener(eventName: string | symbol, listener: (...args: any[]) => void): this
Name Description
eventName The event to listen for. Strings and symbols are allowed.
listener A function called with the arguments given to emit().

Returns: the emitter itself.

Errors: ERR_INVALID_ARG_TYPE if listener is not a function. Adding the eleventh listener for one event prints a MaxListenersExceededWarning (not an error).

Usage notes

  • No de-duplication. Registering the same function twice calls it twice for each emit. Remove it twice, too.
  • 'newListener' first. If someone listens for 'newListener', it is emitted with (eventName, listener) before the new listener is inserted. Listeners added for 'newListener' itself are not announced to themselves.
  • Added during emit. A listener added by another listener while an emit() is running is not called for that emit; it only takes part in the next one.
  • Keep a reference to remove it. Anonymous arrow functions cannot be removed later with off() because you have nothing to pass. Store the function in a variable if you will need it.
  • One-shot variant. Use once() when the handler should run a single time.
  • Order control. on() appends to the end of the list; prependListener() inserts at the front.
  • Async listeners. An async listener returns a promise that emit() ignores. A rejection becomes an unhandled rejection unless captureRejections is enabled.
  • Streams. For readable streams, adding a 'data' listener also switches the stream into flowing mode, which is why on('data') has side effects beyond plain emitters.