Creates a new SimpleTransformIterator
.
Sets or gets the default captureRejection value for all emitters.
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.
Gets whether the iterator has stopped generating new items.
Gets whether the iterator has been destroyed.
Gets whether the iterator will not emit anymore items, either due to being closed or due to being destroyed.
Gets whether the iterator has finished emitting items.
The maximum number of items to preload in the internal buffer.
A BufferedIterator
tries to fill its buffer as far as possible.
Set to Infinity
to fully drain the source.
The maximum number of items to preload in the internal buffer.
A BufferedIterator
tries to fill its buffer as far as possible.
Set to Infinity
to fully drain the source.
Gets or sets whether this iterator might have items available for read.
A value of false
means there are definitely no items available;
a value of true
means items might be available.
Gets or sets whether this iterator might have items available for read.
A value of false
means there are definitely no items available;
a value of true
means items might be available.
The source this iterator generates items from.
The source this iterator generates items from.
Writes beginning items and opens iterator resources.
Should never be called before {@link BufferedIterator#_init};
typically, _init
is responsible for calling _begin
.
Changes the iterator to the given state if possible and necessary, possibly emitting events to signal that change.
The ID of the new state
Whether the state was changed
Closes the iterator when pending items are transformed.
Stops the iterator from generating new items,
switching from CLOSING
state into CLOSED
state.
Called by {@link module:asynciterator.AsyncIterator#destroy}. Implementers can override this, but this should not be called directly.
Ends the iterator and cleans up.
Should never be called before {@link module:asynciterator.AsyncIterator#close};
typically, close
is responsible for calling _end
.
Asynchronously calls _end
.
Fills the internal buffer until this._maxBufferSize
items are present.
This method calls {@link BufferedIterator#_read} to fetch items.
Schedules _fillBuffer
asynchronously.
Writes terminating items and closes iterator resources.
Should never be called before {@link BufferedIterator#close};
typically, close
is responsible for calling _flush
.
Initializing the iterator by calling {@link BufferedIterator#_begin} and changing state from INIT to OPEN.
Whether reading of items should immediately start after OPEN.
Initializes a source that was set through a promise
Tries to transform the item; if the transformation yields no items, pushes the original item.
Adds an item to the internal buffer.
The item to add
Tries to read transformed items.
Reads a transforms an item
Generates details for a textual representation of the iterator.
Generates items based on the item from the source. Implementers should add items through {@link BufferedIterator#_push}. The default implementation pushes the source item as-is.
The last read item from the source
To be called when reading is complete
A callback to push zero or more transformation results.
Validates whether the given iterator can be used as a source.
The source to validate
Whether the source can already have a destination
Alias for emitter.on(eventName, listener)
.
Appends the items after those of the current iterator. After this operation, only read the returned iterator instead of the current one.
Items to insert after this iterator's (remaining) items
A new iterator that appends items to this iterator
Creates a copy of the current iterator, containing all items emitted from this point onward. Further copies can be created; they will all start from this same point. After this operation, only read the returned copies instead of the original iterator.
A new iterator that contains all future items of this iterator
Stops the iterator from generating new items after a possible pending read operation has finished. Already generated, pending, or terminating items can still be emitted. After this, the iterator will end asynchronously.
Copies the given properties from the source iterator.
The iterator to copy from
List of property names to copy
Destroy the iterator and stop it from generating new items. This will not do anything if the iterator was already ended or destroyed. All internal resources will be released an no new items will be emitted, even not already generated items. Implementors should not override this method, but instead implement {@link module:asynciterator.AsyncIterator#_destroy}.
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 Symbol
s.
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) ]
Return items from this iterator that match the filter. After this operation, only read the returned iterator instead of the current one.
A filter function to call on this iterator's (remaining) items
The this
pointer for the filter function
A new iterator that filters items from this iterator
Invokes the callback for each remaining item in the iterator. Switches the iterator to flow mode.
A function that will be called with each item
The this
pointer for the callback
Returns the current max listener value for the EventEmitter
which is either
set by emitter.setMaxListeners(n)
or defaults to defaultMaxListeners.
Retrieves all properties of the iterator.
An object with property names as keys.
Retrieves the property with the given name from the iterator.
If no callback is passed, it returns the value of the property
or undefined
if the property is not set.
If a callback is passed, it returns undefined
and calls the callback with the property the moment it is set.
The name of the property to retrieve
The value of the property (if set and no callback is given)
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] ]
Maps items from this iterator using the given function. After this operation, only read the returned iterator instead of the current one.
A mapping function to call on this iterator's (remaining) items
The this
pointer for the mapping function
A new iterator that maps the items from this iterator
Alias for emitter.removeListener()
.
Adds the listener
function to the end 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 eventName
and listener
will result in the listener
being added, and called, multiple
times.
server.on('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter
, so that calls can be chained.
By default, event listeners are invoked in the order they are added. Theemitter.prependListener()
method can be used as an alternative to add the
event listener to the beginning of the listeners array.
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The name of the event.
The callback function
Adds a one-timelistener
function for the event named eventName
. The
next time eventName
is triggered, this listener is removed and then invoked.
server.once('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter
, so that calls can be chained.
By default, event listeners are invoked in the order they are added. Theemitter.prependOnceListener()
method can be used as an alternative to add the
event listener to the beginning of the listeners array.
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The name of the event.
The callback function
Prepends the items after those of the current iterator. After this operation, only read the returned iterator instead of the current one.
Items to insert before this iterator's (remaining) items
A new iterator that prepends items to this iterator
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 eventName
and 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
Limits the current iterator to the given range. The current iterator may not be read anymore until the returned iterator ends.
Index of the first item to return
Index of the last item to return
A new iterator with items in the given range
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');
Tries to read the next item from the iterator. If the buffer is empty, this method calls {@link BufferedIterator#_read} to fetch items.
The next item, or null
if none is available
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 EventEmitter
s 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.
Sets all of the given properties.
Key/value pairs of properties to set
Sets the property with the given name to the value.
The name of the property to set
The new value of the property
Skips the given number of items from the current iterator. The current iterator may not be read anymore until the returned iterator ends.
The number of items to skip
A new iterator that skips the given number of items
Surrounds items of the current iterator with the given items. After this operation, only read the returned iterator instead of the current one.
Items to insert before this iterator's (remaining) items
Items to insert after this iterator's (remaining) items
A new iterator that appends and prepends items to this iterator
Limits the current iterator to the given number of items. The current iterator may not be read anymore until the returned iterator ends.
The maximum number of items
A new iterator with at most the given number of items
Consume all remaining items of the iterator into an array that will be returned asynchronously.
Transforms items from this iterator. After this operation, only read the returned iterator instead of the current one.
A new iterator that maps the items from this iterator
Returns a new iterator containing all of the unique items in the original iterator.
The derived value by which to determine uniqueness (e.g., stringification). Defaults to the identity function.
An iterator with duplicates filtered out.
Returns a copy of the array of listeners for the event named eventName
.
For EventEmitter
s this behaves exactly the same as calling .listeners
on
the emitter.
For EventTarget
s 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 eventName
registered 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.
Generated using TypeDoc
An iterator that generates items based on a source iterator and simple transformation steps passed as arguments.