Passing arguments andthis to listeners#

TheeventEmitter.emit() method allows an arbitrary set of arguments to bepassed to the listener functions. Keep in mind that whenan ordinary listener function is called, the standardthis keywordis intentionally set to reference theEventEmitter instance to which thelistener is attached.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',function(a, b) {console.log(a, b,this,this === myEmitter);// Prints://   a b MyEmitter {//     _events: [Object: null prototype] { event: [Function (anonymous)] },//     _eventsCount: 1,//     _maxListeners: undefined,//     Symbol(shapeMode): false,//     Symbol(kCapture): false//   } true});myEmitter.emit('event','a','b');constEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',function(a, b) {console.log(a, b,this,this === myEmitter);// Prints://   a b MyEmitter {//     _events: [Object: null prototype] { event: [Function (anonymous)] },//     _eventsCount: 1,//     _maxListeners: undefined,//     Symbol(shapeMode): false,//     Symbol(kCapture): false//   } true});myEmitter.emit('event','a','b');copy

It is possible to use ES6 Arrow Functions as listeners, however, when doing so,thethis keyword will no longer reference theEventEmitter instance:

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',(a, b) => {console.log(a, b,this);// Prints: a b undefined});myEmitter.emit('event','a','b');constEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',(a, b) => {console.log(a, b,this);// Prints: a b {}});myEmitter.emit('event','a','b');copy

Asynchronous vs. synchronous#

TheEventEmitter calls all listeners synchronously in the order in whichthey were registered. This ensures the proper sequencing ofevents and helps avoid race conditions and logic errors. When appropriate,listener functions can switch to an asynchronous mode of operation usingthesetImmediate() orprocess.nextTick() methods:

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',(a, b) => {setImmediate(() => {console.log('this happens asynchronously');  });});myEmitter.emit('event','a','b');constEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('event',(a, b) => {setImmediate(() => {console.log('this happens asynchronously');  });});myEmitter.emit('event','a','b');copy

Handling events only once#

When a listener is registered using theeventEmitter.on() method, thatlistener is invokedevery time the named event is emitted.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();let m =0;myEmitter.on('event',() => {console.log(++m);});myEmitter.emit('event');// Prints: 1myEmitter.emit('event');// Prints: 2constEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();let m =0;myEmitter.on('event',() => {console.log(++m);});myEmitter.emit('event');// Prints: 1myEmitter.emit('event');// Prints: 2copy

Using theeventEmitter.once() method, it is possible to register a listenerthat is called at most once for a particular event. Once the event is emitted,the listener is unregistered andthen called.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();let m =0;myEmitter.once('event',() => {console.log(++m);});myEmitter.emit('event');// Prints: 1myEmitter.emit('event');// IgnoredconstEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();let m =0;myEmitter.once('event',() => {console.log(++m);});myEmitter.emit('event');// Prints: 1myEmitter.emit('event');// Ignoredcopy

Error events#

When an error occurs within anEventEmitter instance, the typical action isfor an'error' event to be emitted. These are treated as special caseswithin Node.js.

If anEventEmitter doesnot have at least one listener registered for the'error' event, and an'error' event is emitted, the error is thrown, astack trace is printed, and the Node.js process exits.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.emit('error',newError('whoops!'));// Throws and crashes Node.jsconstEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.emit('error',newError('whoops!'));// Throws and crashes Node.jscopy

To guard against crashing the Node.js process thedomain module can beused. (Note, however, that thenode:domain module is deprecated.)

As a best practice, listeners should always be added for the'error' events.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('error',(err) => {console.error('whoops! there was an error');});myEmitter.emit('error',newError('whoops!'));// Prints: whoops! there was an errorconstEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();myEmitter.on('error',(err) => {console.error('whoops! there was an error');});myEmitter.emit('error',newError('whoops!'));// Prints: whoops! there was an errorcopy

It is possible to monitor'error' events without consuming the emitted errorby installing a listener using the symbolevents.errorMonitor.

import {EventEmitter, errorMonitor }from'node:events';const myEmitter =newEventEmitter();myEmitter.on(errorMonitor,(err) => {MyMonitoringTool.log(err);});myEmitter.emit('error',newError('whoops!'));// Still throws and crashes Node.jsconst {EventEmitter, errorMonitor } =require('node:events');const myEmitter =newEventEmitter();myEmitter.on(errorMonitor,(err) => {MyMonitoringTool.log(err);});myEmitter.emit('error',newError('whoops!'));// Still throws and crashes Node.jscopy

Capture rejections of promises#

Usingasync functions with event handlers is problematic, because itcan lead to an unhandled rejection in case of a thrown exception:

import {EventEmitter }from'node:events';const ee =newEventEmitter();ee.on('something',async (value) => {thrownewError('kaboom');});constEventEmitter =require('node:events');const ee =newEventEmitter();ee.on('something',async (value) => {thrownewError('kaboom');});copy

ThecaptureRejections option in theEventEmitter constructor or the globalsetting change this behavior, installing a.then(undefined, handler)handler on thePromise. This handler routes the exceptionasynchronously to theSymbol.for('nodejs.rejection') methodif there is one, or to'error' event handler if there is none.

import {EventEmitter }from'node:events';const ee1 =newEventEmitter({captureRejections:true });ee1.on('something',async (value) => {thrownewError('kaboom');});ee1.on('error',console.log);const ee2 =newEventEmitter({captureRejections:true });ee2.on('something',async (value) => {thrownewError('kaboom');});ee2[Symbol.for('nodejs.rejection')] =console.log;constEventEmitter =require('node:events');const ee1 =newEventEmitter({captureRejections:true });ee1.on('something',async (value) => {thrownewError('kaboom');});ee1.on('error',console.log);const ee2 =newEventEmitter({captureRejections:true });ee2.on('something',async (value) => {thrownewError('kaboom');});ee2[Symbol.for('nodejs.rejection')] =console.log;copy

Settingevents.captureRejections = true will change the default for allnew instances ofEventEmitter.

import {EventEmitter }from'node:events';EventEmitter.captureRejections =true;const ee1 =newEventEmitter();ee1.on('something',async (value) => {thrownewError('kaboom');});ee1.on('error',console.log);const events =require('node:events');events.captureRejections =true;const ee1 =new events.EventEmitter();ee1.on('something',async (value) => {thrownewError('kaboom');});ee1.on('error',console.log);copy

The'error' events that are generated by thecaptureRejections behaviordo not have a catch handler to avoid infinite error loops: therecommendation is tonot useasync functions as'error' event handlers.

Class:EventEmitter#

TheEventEmitter class is defined and exposed by thenode:events module:

import {EventEmitter }from'node:events';constEventEmitter =require('node:events');copy

AllEventEmitters emit the event'newListener' when new listeners areadded and'removeListener' when existing listeners are removed.

It supports the following option:

• captureRejections<boolean> It enablesautomatic capturing of promise rejection.Default:false.

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();// Only do this once so we don't loop forevermyEmitter.once('newListener',(event, listener) => {if (event ==='event') {// Insert a new listener in front    myEmitter.on('event',() => {console.log('B');    });  }});myEmitter.on('event',() => {console.log('A');});myEmitter.emit('event');// Prints://   B//   AconstEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();// Only do this once so we don't loop forevermyEmitter.once('newListener',(event, listener) => {if (event ==='event') {// Insert a new listener in front    myEmitter.on('event',() => {console.log('B');    });  }});myEmitter.on('event',() => {console.log('A');});myEmitter.emit('event');// Prints://   B//   Acopy

import {EventEmitter }from'node:events';const myEmitter =newEventEmitter();// First listenermyEmitter.on('event',functionfirstListener() {console.log('Helloooo! first listener');});// Second listenermyEmitter.on('event',functionsecondListener(arg1, arg2) {console.log(`event with parameters${arg1},${arg2} in second listener`);});// Third listenermyEmitter.on('event',functionthirdListener(...args) {const parameters = args.join(', ');console.log(`event with parameters${parameters} in third listener`);});console.log(myEmitter.listeners('event'));myEmitter.emit('event',1,2,3,4,5);// Prints:// [//   [Function: firstListener],//   [Function: secondListener],//   [Function: thirdListener]// ]// Helloooo! first listener// event with parameters 1, 2 in second listener// event with parameters 1, 2, 3, 4, 5 in third listenerconstEventEmitter =require('node:events');const myEmitter =newEventEmitter();// First listenermyEmitter.on('event',functionfirstListener() {console.log('Helloooo! first listener');});// Second listenermyEmitter.on('event',functionsecondListener(arg1, arg2) {console.log(`event with parameters${arg1},${arg2} in second listener`);});// Third listenermyEmitter.on('event',functionthirdListener(...args) {const parameters = args.join(', ');console.log(`event with parameters${parameters} in third listener`);});console.log(myEmitter.listeners('event'));myEmitter.emit('event',1,2,3,4,5);// Prints:// [//   [Function: firstListener],//   [Function: secondListener],//   [Function: thirdListener]// ]// Helloooo! first listener// event with parameters 1, 2 in second listener// event with parameters 1, 2, 3, 4, 5 in third listenercopy

import {EventEmitter }from'node:events';const myEE =newEventEmitter();myEE.on('foo',() => {});myEE.on('bar',() => {});const sym =Symbol('symbol');myEE.on(sym,() => {});console.log(myEE.eventNames());// Prints: [ 'foo', 'bar', Symbol(symbol) ]constEventEmitter =require('node:events');const myEE =newEventEmitter();myEE.on('foo',() => {});myEE.on('bar',() => {});const sym =Symbol('symbol');myEE.on(sym,() => {});console.log(myEE.eventNames());// Prints: [ 'foo', 'bar', Symbol(symbol) ]copy

server.on('connection',(stream) => {console.log('someone connected!');});console.log(util.inspect(server.listeners('connection')));// Prints: [ [Function] ]copy

server.on('connection',(stream) => {console.log('someone connected!');});copy

import {EventEmitter }from'node:events';const myEE =newEventEmitter();myEE.on('foo',() =>console.log('a'));myEE.prependListener('foo',() =>console.log('b'));myEE.emit('foo');// Prints://   b//   aconstEventEmitter =require('node:events');const myEE =newEventEmitter();myEE.on('foo',() =>console.log('a'));myEE.prependListener('foo',() =>console.log('b'));myEE.emit('foo');// Prints://   b//   acopy

server.once('connection',(stream) => {console.log('Ah, we have our first user!');});copy

import {EventEmitter }from'node:events';const myEE =newEventEmitter();myEE.once('foo',() =>console.log('a'));myEE.prependOnceListener('foo',() =>console.log('b'));myEE.emit('foo');// Prints://   b//   aconstEventEmitter =require('node:events');const myEE =newEventEmitter();myEE.once('foo',() =>console.log('a'));myEE.prependOnceListener('foo',() =>console.log('b'));myEE.emit('foo');// Prints://   b//   acopy

server.prependListener('connection',(stream) => {console.log('someone connected!');});copy

server.prependOnceListener('connection',(stream) => {console.log('Ah, we have our first user!');});copy

constcallback = (stream) => {console.log('someone connected!');};server.on('connection', callback);// ...server.removeListener('connection', callback);copy

import {EventEmitter }from'node:events';classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();constcallbackA = () => {console.log('A');  myEmitter.removeListener('event', callbackB);};constcallbackB = () => {console.log('B');};myEmitter.on('event', callbackA);myEmitter.on('event', callbackB);// callbackA removes listener callbackB but it will still be called.// Internal listener array at time of emit [callbackA, callbackB]myEmitter.emit('event');// Prints://   A//   B// callbackB is now removed.// Internal listener array [callbackA]myEmitter.emit('event');// Prints://   AconstEventEmitter =require('node:events');classMyEmitterextendsEventEmitter {}const myEmitter =newMyEmitter();constcallbackA = () => {console.log('A');  myEmitter.removeListener('event', callbackB);};constcallbackB = () => {console.log('B');};myEmitter.on('event', callbackA);myEmitter.on('event', callbackB);// callbackA removes listener callbackB but it will still be called.// Internal listener array at time of emit [callbackA, callbackB]myEmitter.emit('event');// Prints://   A//   B// callbackB is now removed.// Internal listener array [callbackA]myEmitter.emit('event');// Prints://   Acopy

import {EventEmitter }from'node:events';const ee =newEventEmitter();functionpong() {console.log('pong');}ee.on('ping', pong);ee.once('ping', pong);ee.removeListener('ping', pong);ee.emit('ping');ee.emit('ping');constEventEmitter =require('node:events');const ee =newEventEmitter();functionpong() {console.log('pong');}ee.on('ping', pong);ee.once('ping', pong);ee.removeListener('ping', pong);ee.emit('ping');ee.emit('ping');copy

import {EventEmitter }from'node:events';const emitter =newEventEmitter();emitter.once('log',() =>console.log('log once'));// Returns a new Array with a function `onceWrapper` which has a property// `listener` which contains the original listener bound aboveconst listeners = emitter.rawListeners('log');const logFnWrapper = listeners[0];// Logs "log once" to the console and does not unbind the `once` eventlogFnWrapper.listener();// Logs "log once" to the console and removes the listenerlogFnWrapper();emitter.on('log',() =>console.log('log persistently'));// Will return a new Array with a single function bound by `.on()` aboveconst newListeners = emitter.rawListeners('log');// Logs "log persistently" twicenewListeners[0]();emitter.emit('log');constEventEmitter =require('node:events');const emitter =newEventEmitter();emitter.once('log',() =>console.log('log once'));// Returns a new Array with a function `onceWrapper` which has a property// `listener` which contains the original listener bound aboveconst listeners = emitter.rawListeners('log');const logFnWrapper = listeners[0];// Logs "log once" to the console and does not unbind the `once` eventlogFnWrapper.listener();// Logs "log once" to the console and removes the listenerlogFnWrapper();emitter.on('log',() =>console.log('log persistently'));// Will return a new Array with a single function bound by `.on()` aboveconst newListeners = emitter.rawListeners('log');// Logs "log persistently" twicenewListeners[0]();emitter.emit('log');copy

import {EventEmitter, captureRejectionSymbol }from'node:events';classMyClassextendsEventEmitter {constructor() {super({captureRejections:true });  }  [captureRejectionSymbol](err, event, ...args) {console.log('rejection happened for', event,'with', err, ...args);this.destroy(err);  }destroy(err) {// Tear the resource down here.  }}const {EventEmitter, captureRejectionSymbol } =require('node:events');classMyClassextendsEventEmitter {constructor() {super({captureRejections:true });  }  [captureRejectionSymbol](err, event, ...args) {console.log('rejection happened for', event,'with', err, ...args);this.destroy(err);  }destroy(err) {// Tear the resource down here.  }}copy

events.defaultMaxListeners#

By default, a maximum of10 listeners can be registered for any singleevent. This limit can be changed for individualEventEmitter instancesusing theemitter.setMaxListeners(n) method. To change the defaultforallEventEmitter instances, theevents.defaultMaxListenersproperty can be used. If this value is not a positive number, aRangeErroris thrown.

Take caution when setting theevents.defaultMaxListeners because thechange affectsallEventEmitter instances, including those created beforethe change is made. However, callingemitter.setMaxListeners(n) still hasprecedence overevents.defaultMaxListeners.

This is not a hard limit. TheEventEmitter instance will allowmore listeners to be added but will output a trace warning to stderr indicatingthat a "possible EventEmitter memory leak" has been detected. For any singleEventEmitter, theemitter.getMaxListeners() andemitter.setMaxListeners()methods can be used to temporarily avoid this warning:

defaultMaxListeners has no effect onAbortSignal instances. While it isstill possible to useemitter.setMaxListeners(n) to set a warning limitfor individualAbortSignal instances, per defaultAbortSignal instances will not warn.

import {EventEmitter }from'node:events';const emitter =newEventEmitter();emitter.setMaxListeners(emitter.getMaxListeners() +1);emitter.once('event',() => {// do stuff  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() -1,0));});constEventEmitter =require('node:events');const emitter =newEventEmitter();emitter.setMaxListeners(emitter.getMaxListeners() +1);emitter.once('event',() => {// do stuff  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() -1,0));});copy

The--trace-warnings command-line flag can be used to display thestack trace for such warnings.

The emitted warning can be inspected withprocess.on('warning') and willhave the additionalemitter,type, andcount properties, referring tothe event emitter instance, the event's name and the number of attachedlisteners, respectively.Itsname property is set to'MaxListenersExceededWarning'.

events.errorMonitor#

This symbol shall be used to install a listener for only monitoring'error'events. Listeners installed using this symbol are called before the regular'error' listeners are called.

Installing a listener using this symbol does not change the behavior once an'error' event is emitted. Therefore, the process will still crash if noregular'error' listener is installed.

events.getEventListeners(emitterOrTarget, eventName)#

• emitterOrTarget<EventEmitter> |<EventTarget>
• eventName<string> |<symbol>
• Returns:<Function[]>

Returns a copy of the array of listeners for the event namedeventName.

ForEventEmitters this behaves exactly the same as calling.listeners onthe emitter.

ForEventTargets this is the only way to get the event listeners for theevent target. This is useful for debugging and diagnostic purposes.

import { getEventListeners,EventEmitter }from'node:events';{const ee =newEventEmitter();constlistener = () =>console.log('Events are fun');  ee.on('foo', listener);console.log(getEventListeners(ee,'foo'));// [ [Function: listener] ]}{const et =newEventTarget();constlistener = () =>console.log('Events are fun');  et.addEventListener('foo', listener);console.log(getEventListeners(et,'foo'));// [ [Function: listener] ]}const { getEventListeners,EventEmitter } =require('node:events');{const ee =newEventEmitter();constlistener = () =>console.log('Events are fun');  ee.on('foo', listener);console.log(getEventListeners(ee,'foo'));// [ [Function: listener] ]}{const et =newEventTarget();constlistener = () =>console.log('Events are fun');  et.addEventListener('foo', listener);console.log(getEventListeners(et,'foo'));// [ [Function: listener] ]}copy

events.getMaxListeners(emitterOrTarget)#

• emitterOrTarget<EventEmitter> |<EventTarget>
• Returns:<number>

Returns the currently set max amount of listeners.

ForEventEmitters this behaves exactly the same as calling.getMaxListeners onthe emitter.

ForEventTargets this is the only way to get the max event listeners for theevent target. If the number of event handlers on a single EventTarget exceedsthe max set, the EventTarget will print a warning.

import { getMaxListeners, setMaxListeners,EventEmitter }from'node:events';{const ee =newEventEmitter();console.log(getMaxListeners(ee));// 10setMaxListeners(11, ee);console.log(getMaxListeners(ee));// 11}{const et =newEventTarget();console.log(getMaxListeners(et));// 10setMaxListeners(11, et);console.log(getMaxListeners(et));// 11}const { getMaxListeners, setMaxListeners,EventEmitter } =require('node:events');{const ee =newEventEmitter();console.log(getMaxListeners(ee));// 10setMaxListeners(11, ee);console.log(getMaxListeners(ee));// 11}{const et =newEventTarget();console.log(getMaxListeners(et));// 10setMaxListeners(11, et);console.log(getMaxListeners(et));// 11}copy

events.once(emitter, name[, options])#

• emitter<EventEmitter>
• name<string> |<symbol>
• options<Object>
  • signal<AbortSignal> Can be used to cancel waiting for the event.
• Returns:<Promise>

Creates aPromise that is fulfilled when theEventEmitter emits the givenevent or that is rejected if theEventEmitter emits'error' while waiting.ThePromise will resolve with an array of all the arguments emitted to thegiven event.

This method is intentionally generic and works with the web platformEventTarget interface, which has no special'error' event semantics and does not listen to the'error' event.

import { once,EventEmitter }from'node:events';import processfrom'node:process';const ee =newEventEmitter();process.nextTick(() => {  ee.emit('myevent',42);});const [value] =awaitonce(ee,'myevent');console.log(value);const err =newError('kaboom');process.nextTick(() => {  ee.emit('error', err);});try {awaitonce(ee,'myevent');}catch (err) {console.error('error happened', err);}const { once,EventEmitter } =require('node:events');asyncfunctionrun() {const ee =newEventEmitter();  process.nextTick(() => {    ee.emit('myevent',42);  });const [value] =awaitonce(ee,'myevent');console.log(value);const err =newError('kaboom');  process.nextTick(() => {    ee.emit('error', err);  });try {awaitonce(ee,'myevent');  }catch (err) {console.error('error happened', err);  }}run();copy

The special handling of the'error' event is only used whenevents.once()is used to wait for another event. Ifevents.once() is used to wait for the'error' event itself, then it is treated as any other kind of event withoutspecial handling:

import {EventEmitter, once }from'node:events';const ee =newEventEmitter();once(ee,'error')  .then(([err]) =>console.log('ok', err.message))  .catch((err) =>console.error('error', err.message));ee.emit('error',newError('boom'));// Prints: ok boomconst {EventEmitter, once } =require('node:events');const ee =newEventEmitter();once(ee,'error')  .then(([err]) =>console.log('ok', err.message))  .catch((err) =>console.error('error', err.message));ee.emit('error',newError('boom'));// Prints: ok boomcopy

An<AbortSignal> can be used to cancel waiting for the event:

import {EventEmitter, once }from'node:events';const ee =newEventEmitter();const ac =newAbortController();asyncfunctionfoo(emitter, event, signal) {try {awaitonce(emitter, event, { signal });console.log('event emitted!');  }catch (error) {if (error.name ==='AbortError') {console.error('Waiting for the event was canceled!');    }else {console.error('There was an error', error.message);    }  }}foo(ee,'foo', ac.signal);ac.abort();// Prints: Waiting for the event was canceled!const {EventEmitter, once } =require('node:events');const ee =newEventEmitter();const ac =newAbortController();asyncfunctionfoo(emitter, event, signal) {try {awaitonce(emitter, event, { signal });console.log('event emitted!');  }catch (error) {if (error.name ==='AbortError') {console.error('Waiting for the event was canceled!');    }else {console.error('There was an error', error.message);    }  }}foo(ee,'foo', ac.signal);ac.abort();// Prints: Waiting for the event was canceled!copy

import {EventEmitter, once }from'node:events';import processfrom'node:process';const myEE =newEventEmitter();asyncfunctionfoo() {awaitonce(myEE,'bar');console.log('bar');// This Promise will never resolve because the 'foo' event will// have already been emitted before the Promise is created.awaitonce(myEE,'foo');console.log('foo');}process.nextTick(() => {  myEE.emit('bar');  myEE.emit('foo');});foo().then(() =>console.log('done'));const {EventEmitter, once } =require('node:events');const myEE =newEventEmitter();asyncfunctionfoo() {awaitonce(myEE,'bar');console.log('bar');// This Promise will never resolve because the 'foo' event will// have already been emitted before the Promise is created.awaitonce(myEE,'foo');console.log('foo');}process.nextTick(() => {  myEE.emit('bar');  myEE.emit('foo');});foo().then(() =>console.log('done'));copy

import {EventEmitter, once }from'node:events';import processfrom'node:process';const myEE =newEventEmitter();asyncfunctionfoo() {awaitPromise.all([once(myEE,'bar'),once(myEE,'foo')]);console.log('foo','bar');}process.nextTick(() => {  myEE.emit('bar');  myEE.emit('foo');});foo().then(() =>console.log('done'));const {EventEmitter, once } =require('node:events');const myEE =newEventEmitter();asyncfunctionfoo() {awaitPromise.all([once(myEE,'bar'),once(myEE,'foo')]);console.log('foo','bar');}process.nextTick(() => {  myEE.emit('bar');  myEE.emit('foo');});foo().then(() =>console.log('done'));copy

events.captureRejections#

• Type:<boolean>

Change the defaultcaptureRejections option on all newEventEmitter objects.

events.captureRejectionSymbol#

• Type:<symbol>Symbol.for('nodejs.rejection')

See how to write a customrejection handler.

events.listenerCount(emitterOrTarget, eventName)#

• emitterOrTarget<EventEmitter> |<EventTarget>
• eventName<string> |<symbol>
• Returns:<integer>

Returns the number of registered listeners for the event namedeventName.

ForEventEmitters this behaves exactly the same as calling.listenerCounton the emitter.

ForEventTargets this is the only way to obtain the listener count. This canbe useful for debugging and diagnostic purposes.

import {EventEmitter, listenerCount }from'node:events';{const ee =newEventEmitter();  ee.on('event',() => {});  ee.on('event',() => {});console.log(listenerCount(ee,'event'));// 2}{const et =newEventTarget();  et.addEventListener('event',() => {});  et.addEventListener('event',() => {});console.log(listenerCount(et,'event'));// 2}const {EventEmitter, listenerCount } =require('node:events');{const ee =newEventEmitter();  ee.on('event',() => {});  ee.on('event',() => {});console.log(listenerCount(ee,'event'));// 2}{const et =newEventTarget();  et.addEventListener('event',() => {});  et.addEventListener('event',() => {});console.log(listenerCount(et,'event'));// 2}copy

events.on(emitter, eventName[, options])#

• emitter<EventEmitter>
• eventName<string> |<symbol> The name of the event being listened for
• options<Object>
  • signal<AbortSignal> Can be used to cancel awaiting events.
  • close<string[]> Names of events that will end the iteration.
  • highWaterMark<integer>Default:Number.MAX_SAFE_INTEGERThe high watermark. The emitter is paused every time the size of eventsbeing buffered is higher than it. Supported only on emitters implementingpause() andresume() methods.
  • lowWaterMark<integer>Default:1The low watermark. The emitter is resumed every time the size of eventsbeing buffered is lower than it. Supported only on emitters implementingpause() andresume() methods.
• Returns:<AsyncIterator> that iterateseventName events emitted by theemitter

import { on,EventEmitter }from'node:events';import processfrom'node:process';const ee =newEventEmitter();// Emit later onprocess.nextTick(() => {  ee.emit('foo','bar');  ee.emit('foo',42);});forawait (const eventofon(ee,'foo')) {// The execution of this inner block is synchronous and it// processes one event at a time (even with await). Do not use// if concurrent execution is required.console.log(event);// prints ['bar'] [42]}// Unreachable hereconst { on,EventEmitter } =require('node:events');(async () => {const ee =newEventEmitter();// Emit later on  process.nextTick(() => {    ee.emit('foo','bar');    ee.emit('foo',42);  });forawait (const eventofon(ee,'foo')) {// The execution of this inner block is synchronous and it// processes one event at a time (even with await). Do not use// if concurrent execution is required.console.log(event);// prints ['bar'] [42]  }// Unreachable here})();copy

Returns anAsyncIterator that iterateseventName events. It will throwif theEventEmitter emits'error'. It removes all listeners whenexiting the loop. Thevalue returned by each iteration is an arraycomposed of the emitted event arguments.

An<AbortSignal> can be used to cancel waiting on events:

import { on,EventEmitter }from'node:events';import processfrom'node:process';const ac =newAbortController();(async () => {const ee =newEventEmitter();// Emit later on  process.nextTick(() => {    ee.emit('foo','bar');    ee.emit('foo',42);  });forawait (const eventofon(ee,'foo', {signal: ac.signal })) {// The execution of this inner block is synchronous and it// processes one event at a time (even with await). Do not use// if concurrent execution is required.console.log(event);// prints ['bar'] [42]  }// Unreachable here})();process.nextTick(() => ac.abort());const { on,EventEmitter } =require('node:events');const ac =newAbortController();(async () => {const ee =newEventEmitter();// Emit later on  process.nextTick(() => {    ee.emit('foo','bar');    ee.emit('foo',42);  });forawait (const eventofon(ee,'foo', {signal: ac.signal })) {// The execution of this inner block is synchronous and it// processes one event at a time (even with await). Do not use// if concurrent execution is required.console.log(event);// prints ['bar'] [42]  }// Unreachable here})();process.nextTick(() => ac.abort());copy

events.setMaxListeners(n[, ...eventTargets])#

• n<number> A non-negative number. The maximum number of listeners perEventTarget event.
• ...eventsTargets<EventTarget[]> |<EventEmitter[]> Zero or more<EventTarget>or<EventEmitter> instances. If none are specified,n is set as the defaultmax for all newly created<EventTarget> and<EventEmitter> objects.

import { setMaxListeners,EventEmitter }from'node:events';const target =newEventTarget();const emitter =newEventEmitter();setMaxListeners(5, target, emitter);const {  setMaxListeners,EventEmitter,} =require('node:events');const target =newEventTarget();const emitter =newEventEmitter();setMaxListeners(5, target, emitter);copy

events.addAbortListener(signal, listener)#

• signal<AbortSignal>
• listener<Function> |<EventListener>
• Returns:<Disposable> A Disposable that removes theabort listener.

Listens once to theabort event on the providedsignal.

Listening to theabort event on abort signals is unsafe and maylead to resource leaks since another third party with the signal cancalle.stopImmediatePropagation(). Unfortunately Node.js cannot changethis since it would violate the web standard. Additionally, the originalAPI makes it easy to forget to remove listeners.

This API allows safely usingAbortSignals in Node.js APIs by solving thesetwo issues by listening to the event such thatstopImmediatePropagation doesnot prevent the listener from running.

Returns a disposable so that it may be unsubscribed from more easily.

const { addAbortListener } =require('node:events');functionexample(signal) {let disposable;try {    signal.addEventListener('abort',(e) => e.stopImmediatePropagation());    disposable =addAbortListener(signal,(e) => {// Do something when signal is aborted.    });  }finally {    disposable?.[Symbol.dispose]();  }}import { addAbortListener }from'node:events';functionexample(signal) {let disposable;try {    signal.addEventListener('abort',(e) => e.stopImmediatePropagation());    disposable =addAbortListener(signal,(e) => {// Do something when signal is aborted.    });  }finally {    disposable?.[Symbol.dispose]();  }}copy

Class:events.EventEmitterAsyncResource extends EventEmitter#

IntegratesEventEmitter with<AsyncResource> forEventEmitters thatrequire manual async tracking. Specifically, all events emitted by instancesofevents.EventEmitterAsyncResource will run within itsasync context.

import {EventEmitterAsyncResource,EventEmitter }from'node:events';import { notStrictEqual, strictEqual }from'node:assert';import { executionAsyncId, triggerAsyncId }from'node:async_hooks';// Async tracking tooling will identify this as 'Q'.const ee1 =newEventEmitterAsyncResource({name:'Q' });// 'foo' listeners will run in the EventEmitters async context.ee1.on('foo',() => {strictEqual(executionAsyncId(), ee1.asyncId);strictEqual(triggerAsyncId(), ee1.triggerAsyncId);});const ee2 =newEventEmitter();// 'foo' listeners on ordinary EventEmitters that do not track async// context, however, run in the same async context as the emit().ee2.on('foo',() => {notStrictEqual(executionAsyncId(), ee2.asyncId);notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);});Promise.resolve().then(() => {  ee1.emit('foo');  ee2.emit('foo');});const {EventEmitterAsyncResource,EventEmitter } =require('node:events');const { notStrictEqual, strictEqual } =require('node:assert');const { executionAsyncId, triggerAsyncId } =require('node:async_hooks');// Async tracking tooling will identify this as 'Q'.const ee1 =newEventEmitterAsyncResource({name:'Q' });// 'foo' listeners will run in the EventEmitters async context.ee1.on('foo',() => {strictEqual(executionAsyncId(), ee1.asyncId);strictEqual(triggerAsyncId(), ee1.triggerAsyncId);});const ee2 =newEventEmitter();// 'foo' listeners on ordinary EventEmitters that do not track async// context, however, run in the same async context as the emit().ee2.on('foo',() => {notStrictEqual(executionAsyncId(), ee2.asyncId);notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);});Promise.resolve().then(() => {  ee1.emit('foo');  ee2.emit('foo');});copy

TheEventEmitterAsyncResource class has the same methods and takes thesame options asEventEmitter andAsyncResource themselves.

EventTarget andEvent API#

TheEventTarget andEvent objects are a Node.js-specific implementationof theEventTarget Web API that are exposed by some Node.js core APIs.

const target =newEventTarget();target.addEventListener('foo',(event) => {console.log('foo event happened!');});copy

functionhandler1(event) {console.log(event.type);// Prints 'foo'  event.a =1;}asyncfunctionhandler2(event) {console.log(event.type);// Prints 'foo'console.log(event.a);// Prints 1}const handler3 = {handleEvent(event) {console.log(event.type);// Prints 'foo'  },};const handler4 = {asynchandleEvent(event) {console.log(event.type);// Prints 'foo'  },};const target =newEventTarget();target.addEventListener('foo', handler1);target.addEventListener('foo', handler2);target.addEventListener('foo', handler3);target.addEventListener('foo', handler4, {once:true });copy

functionhandler(event) {}const target =newEventTarget();target.addEventListener('foo', handler, {capture:true });// firsttarget.addEventListener('foo', handler, {capture:false });// second// Removes the second instance of handlertarget.removeEventListener('foo', handler);// Removes the first instance of handlertarget.removeEventListener('foo', handler, {capture:true });copy