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 no
regular 'error' listener is installed.
Alias for emitter.on(eventName, listener).
Synchronously calls each of the listeners registered for
the event namedeventName, in the order they
were registered, passing the supplied arguments to each.
Returns true if the event had listeners,
false otherwise.
const EventEmitter = require('events');
const myEmitter = new EventEmitter();
// First listener
myEmitter.on('event', function firstListener() {
console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...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 listener
Returns an array listing the events for which the
emitter has registered listeners. The values in the
array are strings or Symbols.
const EventEmitter = require('events');
const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});
const sym = Symbol('symbol');
myEE.on(sym, () => {});
console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
Returns the current max listener value for the
EventEmitter which is either set by
emitter.setMaxListeners(n) or defaults to
defaultMaxListeners.
Returns the number of listeners listening to the event
named eventName.
The name of the event being listened for
Returns a copy of the array of listeners for the event
named eventName.
server.on('connection', (stream) => {
console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
Alias for emitter.removeListener().
Adds the listener function to the
beginning of the listeners array for the event
named eventName. No checks are made to see
if the listener has already been added.
Multiple calls passing the same combination of
eventNameand listener will
result in the listener being added, and
called, multiple times.
server.prependListener('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
The name of the event.
The callback function
Adds a one-timelistener function for the event named
eventName to the_beginning_ of the
listeners array. The next time eventName is
triggered, this listener is removed, and then invoked.
server.prependOnceListener('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
The name of the event.
The callback function
Returns a copy of the array of listeners for the event
named eventName, including any wrappers
(such as those created by .once()).
const emitter = new EventEmitter();
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 above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];
// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();
// Logs "log once" to the console and removes the listener
logFnWrapper();
emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');
// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
Removes all listeners, or those of the specified
eventName.
It is bad practice to remove listeners added elsewhere
in the code, particularly when the
EventEmitter instance was created by some
other component or module (e.g. sockets or file
streams).
Returns a reference to the EventEmitter, so
that calls can be chained.
Removes the specified listener from the
listener array for the event
namedeventName.
const callback = (stream) => {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);
removeListener() will remove, at most, one
instance of a listener from the listener array. If any
single listener has been added multiple times to the
listener array for the specified eventName,
then removeListener() must be called
multiple times to remove each instance.
Once an event is emitted, all listeners attached to it
at the time of emitting are called in order. This
implies that anyremoveListener() or
removeAllListeners() calls
after emitting and_before_ the last listener
finishes execution will not remove them fromemit()
in progress. Subsequent events behave as expected.
const myEmitter = new MyEmitter();
const callbackA = () => {
console.log('A');
myEmitter.removeListener('event', callbackB);
};
const callbackB = () => {
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:
// A
Because listeners are managed using an internal array,
calling this will change the position indices of any
listener registered after the listener being
removed. This will not impact the order in which
listeners are called, but it means that any copies of
the listener array as returned by the
emitter.listeners() method will need to be
recreated.
When a single function has been added as a handler
multiple times for a single event (as in the example
below), removeListener() will remove the
most recently added instance. In the example the
once('ping')listener is removed:
const ee = new EventEmitter();
function pong() {
console.log('pong');
}
ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);
ee.emit('ping');
ee.emit('ping');
Returns a reference to the EventEmitter, so
that calls can be chained.
By default EventEmitters will print a
warning if more than 10 listeners are added
for a particular event. This is a useful default that
helps finding memory leaks. The
emitter.setMaxListeners() method allows the
limit to be modified for this specific
EventEmitter instance. The value can be set
toInfinity (or 0) to indicate
an unlimited number of listeners.
Returns a reference to the EventEmitter, so
that calls can be chained.
Returns a copy of the array of listeners for the event
named eventName.
For EventEmitters this behaves exactly the
same as calling .listeners on the emitter.
For EventTargets this is the only way to
get the event listeners for the event target. This is
useful for debugging and diagnostic purposes.
const { getEventListeners, EventEmitter } = require('events');
{
const ee = new EventEmitter();
const listener = () => console.log('Events are fun');
ee.on('foo', listener);
getEventListeners(ee, 'foo'); // [listener]
}
{
const et = new EventTarget();
const listener = () => console.log('Events are fun');
et.addEventListener('foo', listener);
getEventListeners(et, 'foo'); // [listener]
}
A class method that returns the number of listeners for
the given eventNameregistered on the given
emitter.
const { EventEmitter, listenerCount } = require('events');
const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2
The emitter to query
The event name
```js const { on, EventEmitter } = require('events');
(async () => { const ee = new EventEmitter();
// Emit later on process.nextTick(() => { ee.emit('foo', 'bar'); ee.emit('foo', 42); });
for await (const event of on(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 })();
Returns an `AsyncIterator` that iterates `eventName` events. It will throw
if the `EventEmitter` emits `'error'`. It removes all listeners when
exiting the loop. The `value` returned by each iteration is an array
composed of the emitted event arguments.
An `AbortSignal` can be used to cancel waiting on events:
```js
const { on, EventEmitter } = require('events');
const ac = new AbortController();
(async () => {
const ee = new EventEmitter();
// Emit later on
process.nextTick(() => {
ee.emit('foo', 'bar');
ee.emit('foo', 42);
});
for await (const event of on(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());
The name of the event being listened for
that iterates eventName events emitted by the
emitter
Creates a Promise that is fulfilled when
the EventEmitter emits the given event or
that is rejected if the EventEmitter emits
'error' while waiting. The
Promise will resolve with an array of all
the arguments emitted to the given event.
This method is intentionally generic and works with the
web platform
EventTarget
interface, which has no special'error'
event semantics and does not listen to the
'error' event.
const { once, EventEmitter } = require('events');
async function run() {
const ee = new EventEmitter();
process.nextTick(() => {
ee.emit('myevent', 42);
});
const [value] = await once(ee, 'myevent');
console.log(value);
const err = new Error('kaboom');
process.nextTick(() => {
ee.emit('error', err);
});
try {
await once(ee, 'myevent');
} catch (err) {
console.log('error happened', err);
}
}
run();
The special handling of the
'error' event is only used when
events.once()is used to wait for another
event. If events.once() is used to wait for
the 'error' event itself, then it
is treated as any other kind of event without special
handling:
const { EventEmitter, once } = require('events');
const ee = new EventEmitter();
once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.log('error', err.message));
ee.emit('error', new Error('boom'));
// Prints: ok boom
An AbortSignal can be used to cancel
waiting for the event:
const { EventEmitter, once } = require('events');
const ee = new EventEmitter();
const ac = new AbortController();
async function foo(emitter, event, signal) {
try {
await once(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(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
```js const { setMaxListeners, EventEmitter } = require('events');
const target = new EventTarget(); const emitter = new EventEmitter();
setMaxListeners(5, target, emitter); ```
A non-negative number. The maximum number of
listeners per EventTarget event.
Sets or gets the default captureRejection value for all emitters.