+ 
404: Page not found
- - - - - - - + + + + + + +Class AbstractCursor<TSchema, CursorEvents>Abstract
Type Parameters
- TSchema = any
- CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
Hierarchy (view full)
Implements
Index
Properties
Accessors
Methods
Properties
[async
Protectedsignal
Staticcapture
Value: boolean
+Change the default captureRejections option on all new EventEmitter objects.
Static Readonlycapture
Value: Symbol.for('nodejs.rejection')
See how to write a custom rejection handler.
Static ReadonlyCLOSE
Staticdefault
By default, a maximum of 10 listeners can be registered for any single
+event. This limit can be changed for individual EventEmitter instances
+using the emitter.setMaxListeners(n) method. To change the default
+for allEventEmitter instances, the events.defaultMaxListeners property
+can be used. If this value is not a positive number, a RangeError is thrown.
Take caution when setting the events.defaultMaxListeners because the
+change affects all EventEmitter instances, including those created before
+the change is made. However, calling emitter.setMaxListeners(n) still has
+precedence over events.defaultMaxListeners.
This is not a hard limit. The EventEmitter instance will allow
+more listeners to be added but will output a trace warning to stderr indicating
+that a "possible EventEmitter memory leak" has been detected. For any single
+EventEmitter, the emitter.getMaxListeners() and emitter.setMaxListeners() methods can be used to
+temporarily avoid this warning:
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
// do stuff
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});
+The --trace-warnings command-line flag can be used to display the
+stack trace for such warnings.
The emitted warning can be inspected with process.on('warning') and will
+have the additional emitter, type, and count properties, referring to
+the event emitter instance, the event's name and the number of attached
+listeners, respectively.
+Its name property is set to 'MaxListenersExceededWarning'.
Static Readonlyerror
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.
Accessors
closed
- get closed(): boolean
The cursor is closed and all remaining locally buffered documents have been iterated.
+Returns boolean
id
killed
- get killed(): boolean
A
+killCursorscommand was attempted on this cursor. +This is performed if the cursor id is non zero.Returns boolean
load
- get loadBalanced(): boolean
Returns boolean
namespace
- get namespace(): MongoDBNamespace
Returns MongoDBNamespace
read
- get readConcern(): undefined | ReadConcern
Returns undefined | ReadConcern
read
- get readPreference(): ReadPreference
Returns ReadPreference
session
- set session(clientSession): void
Parameters
- clientSession: ClientSession
Returns void
Methods
[async
Optional[capture
- [capture
Rejection Symbol]<K>(error, event, ...args): void Type Parameters
Parameters
- error: Error
- event: string | symbol
Rest...args: AnyRest
Returns void
add
- add
Cursor Flag(flag, value): this Add a cursor flag to the cursor
+Parameters
- flag:
| "tailable"
| "oplogReplay"
| "noCursorTimeout"
| "awaitData"
| "exhaust"
| "partial"The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial' -.
+ - value: boolean
The flag boolean value.
+
Returns this
- flag:
add
- add
Listener<EventKey>(event, listener): this Alias for
+emitter.on(eventName, listener).Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
Returns this
- add
Listener(event, listener): this Alias for
+emitter.on(eventName, listener).Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- add
Listener(event, listener): this Alias for
+emitter.on(eventName, listener).Parameters
- event: string | symbol
- listener: GenericListener
Returns this
batch
- batch
Size(value): this Set the batch size for the cursor.
+Parameters
- value: number
The number of documents to return per batch. See command documentation.
+
Returns this
- value: number
buffered
Abstractclone
- clone(): AbstractCursor<TSchema, AbstractCursorEvents>
Returns a new uninitialized copy of this cursor, with options matching those that have been set on the current instance
+Returns AbstractCursor<TSchema, AbstractCursorEvents>
close
emit
- emit<EventKey>(event, ...args): boolean
Synchronously calls each of the listeners registered for the event named
+eventName, in the order they were registered, passing the supplied arguments +to each.Returns
+trueif the event had listeners,falseotherwise.
+ +import { EventEmitter } from 'node: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 +Type Parameters
Parameters
- event: symbol | EventKey
Rest...args: Parameters<CursorEvents[EventKey]>
Returns boolean
event
- event
Names(): string[] Returns an array listing the events for which the emitter has registered +listeners. The values in the array are strings or
+Symbols.
+ +import { EventEmitter } from 'node: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 string[]
for
get
- get
Max Listeners(): number Returns the current max listener value for the
+EventEmitterwhich is either +set byemitter.setMaxListeners(n)or defaults to EventEmitter.defaultMaxListeners.Returns number
has
listener
- listener
Count<EventKey>(type): number Returns the number of listeners listening for the event named
+eventName. +Iflisteneris provided, it will return how many times the listener is found +in the list of the listeners of the event.Type Parameters
Parameters
- type: string | symbol | EventKey
Returns number
listeners
- listeners<EventKey>(event): CursorEvents[EventKey][]
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] ] +Type Parameters
Parameters
- event: string | symbol | EventKey
Returns CursorEvents[EventKey][]
map
- map<T>(transform): AbstractCursor<T, AbstractCursorEvents>
Map all documents using the provided function +If there is a transform set on the cursor, that will be called first and the result passed to +this function's transform.
+Type Parameters
Parameters
Returns AbstractCursor<T, AbstractCursorEvents>
Remarks
Note Cursors use
+nullinternally to indicate that there are no more documents in the cursor. Providing a mapping +function that maps values tonullwill result in the cursor closing itself before it has finished iterating +all documents. This will not result in a memory leak, just surprising behavior. For example:
+ +const cursor = collection.find({});
cursor.map(() => null);
const documents = await cursor.toArray();
// documents is always [], regardless of how many documents are in the collection. +Other falsey values are allowed:
+
+ +const cursor = collection.find({});
cursor.map(() => '');
const documents = await cursor.toArray();
// documents is now an array of empty strings +Note for Typescript Users: adding a transform changes the return type of the iteration of this cursor, +it does not return a new instance of a cursor. This means when calling map, +you should always assign the result to a new variable in order to get a correctly typed cursor variable. +Take note of the following example:
+Example
+ +const cursor: FindCursor<Document> = coll.find();
const mappedCursor: FindCursor<number> = cursor.map(doc => Object.keys(doc).length);
const keyCounts: number[] = await mappedCursor.toArray(); // cursor.toArray() still returns Document[] +
max
next
off
- off<EventKey>(event, listener): this
Alias for
+emitter.removeListener().Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
Returns this
- off(event, listener): this
Alias for
+emitter.removeListener().Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- off(event, listener): this
Alias for
+emitter.removeListener().Parameters
- event: string | symbol
- listener: GenericListener
Returns this
on
- on<EventKey>(event, listener): this
Adds the
+listenerfunction to the end of the listeners array for the event +namedeventName. No checks are made to see if thelistenerhas already +been added. Multiple calls passing the same combination ofeventNameand +listenerwill result in thelistenerbeing 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. The
+emitter.prependListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
The callback function
+
Returns this
- on(event, listener): this
Adds the
+listenerfunction to the end of the listeners array for the event +namedeventName. No checks are made to see if thelistenerhas already +been added. Multiple calls passing the same combination ofeventNameand +listenerwill result in thelistenerbeing 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. The
+emitter.prependListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
The callback function
+- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- on(event, listener): this
Adds the
+listenerfunction to the end of the listeners array for the event +namedeventName. No checks are made to see if thelistenerhas already +been added. Multiple calls passing the same combination ofeventNameand +listenerwill result in thelistenerbeing 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. The
+emitter.prependListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Parameters
- event: string | symbol
- listener: GenericListener
The callback function
+
Returns this
once
- once<EventKey>(event, listener): this
Adds a one-time
+listenerfunction for the event namedeventName. The +next timeeventNameis 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. The
+emitter.prependOnceListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
The callback function
+
Returns this
- once(event, listener): this
Adds a one-time
+listenerfunction for the event namedeventName. The +next timeeventNameis 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. The
+emitter.prependOnceListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
The callback function
+- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- once(event, listener): this
Adds a one-time
+listenerfunction for the event namedeventName. The +next timeeventNameis 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. The
+emitter.prependOnceListener()method can be used as an alternative to add the +event listener to the beginning of the listeners array.
+ +import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a +Parameters
- event: string | symbol
- listener: GenericListener
The callback function
+
Returns this
prepend
- prepend
Listener<EventKey>(event, listener): this Adds the
+listenerfunction to the beginning of the listeners array for the +event namedeventName. No checks are made to see if thelistenerhas +already been added. Multiple calls passing the same combination ofeventName+andlistenerwill result in thelistenerbeing 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.Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
The callback function
+
Returns this
- prepend
Listener(event, listener): this Adds the
+listenerfunction to the beginning of the listeners array for the +event namedeventName. No checks are made to see if thelistenerhas +already been added. Multiple calls passing the same combination ofeventName+andlistenerwill result in thelistenerbeing 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.Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
The callback function
+- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- prepend
Listener(event, listener): this Adds the
+listenerfunction to the beginning of the listeners array for the +event namedeventName. No checks are made to see if thelistenerhas +already been added. Multiple calls passing the same combination ofeventName+andlistenerwill result in thelistenerbeing 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.Parameters
- event: string | symbol
- listener: GenericListener
The callback function
+
Returns this
prepend
- prepend
Once Listener<EventKey>(event, listener): this Adds a one-time
+listenerfunction for the event namedeventNameto the beginning of the listeners array. The next timeeventNameis 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.Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
The callback function
+
Returns this
- prepend
Once Listener(event, listener): this Adds a one-time
+listenerfunction for the event namedeventNameto the beginning of the listeners array. The next timeeventNameis 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.Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
The callback function
+- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- prepend
Once Listener(event, listener): this Adds a one-time
+listenerfunction for the event namedeventNameto the beginning of the listeners array. The next timeeventNameis 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.Parameters
- event: string | symbol
- listener: GenericListener
The callback function
+
Returns this
raw
- raw
Listeners<EventKey>(event): CursorEvents[EventKey][] Returns a copy of the array of listeners for the event named
+eventName, +including any wrappers (such as those created by.once()).
+ +import { EventEmitter } from 'node:events';
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'); +Type Parameters
Parameters
- event: string | symbol | EventKey
Returns CursorEvents[EventKey][]
read
remove
- remove
All Listeners<EventKey>(event?): this Removes all listeners, or those of the specified
+eventName.It is bad practice to remove listeners added elsewhere in the code, +particularly when the
+EventEmitterinstance 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.Type Parameters
Parameters
Optionalevent: string | symbol | EventKey
Returns this
remove
- remove
Listener<EventKey>(event, listener): this Removes the specified
+listenerfrom 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 specifiedeventName, thenremoveListener()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 any
+removeListener()orremoveAllListeners()calls after emitting and before the last listener finishes execution +will not remove them fromemit()in progress. Subsequent events behave as expected.
+ +import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
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 theonce('ping')listener is removed:
+ +import { EventEmitter } from 'node:events';
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.Type Parameters
Parameters
- event: EventKey
- listener: CursorEvents[EventKey]
Returns this
- remove
Listener(event, listener): this Removes the specified
+listenerfrom 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 specifiedeventName, thenremoveListener()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 any
+removeListener()orremoveAllListeners()calls after emitting and before the last listener finishes execution +will not remove them fromemit()in progress. Subsequent events behave as expected.
+ +import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
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 theonce('ping')listener is removed:
+ +import { EventEmitter } from 'node:events';
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.Parameters
- event: CommonEvents
- listener: ((eventName: string | symbol, listener: GenericListener) => void)
- (eventName, listener): void
Parameters
- eventName: string | symbol
- listener: GenericListener
Returns void
Returns this
- remove
Listener(event, listener): this Removes the specified
+listenerfrom 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 specifiedeventName, thenremoveListener()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 any
+removeListener()orremoveAllListeners()calls after emitting and before the last listener finishes execution +will not remove them fromemit()in progress. Subsequent events behave as expected.
+ +import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
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 theonce('ping')listener is removed:
+ +import { EventEmitter } from 'node:events';
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.Parameters
- event: string | symbol
- listener: GenericListener
Returns this
rewind
set
- set
Max Listeners(n): this By default
+EventEmitters will print a warning if more than10listeners are +added for a particular event. This is a useful default that helps finding +memory leaks. Theemitter.setMaxListeners()method allows the limit to be +modified for this specificEventEmitterinstance. The value can be set toInfinity(or0) to indicate an unlimited number of listeners.Returns a reference to the
+EventEmitter, so that calls can be chained.Parameters
- n: number
Returns this
stream
- stream(options?): Readable & AsyncIterable<TSchema>
Parameters
Optionaloptions: CursorStreamOptions
Returns Readable & AsyncIterable<TSchema>
to
- to
Array(): Promise<TSchema[]> Returns an array of documents. The caller is responsible for making sure that there +is enough memory to store the results. Note that the array only contains partial +results when this cursor had been previously accessed. In that case, +cursor.rewind() can be used to reset the cursor.
+Returns Promise<TSchema[]>
try
with
- with
Read Concern(readConcern): this Set the ReadPreference for the cursor.
+Parameters
- readConcern: ReadConcernLike
Returns this
with
- with
Read Preference(readPreference): this Set the ReadPreference for the cursor.
+Parameters
- readPreference: ReadPreferenceLike
The new read preference for the cursor.
+
Returns this
- readPreference: ReadPreferenceLike
Staticadd
- add
Abort Listener(signal, resource): Disposable ExperimentalListens once to the
+abortevent on the providedsignal.Listening to the
+abortevent on abort signals is unsafe and may +lead to resource leaks since another third party with the signal can +calle.stopImmediatePropagation(). Unfortunately Node.js cannot change +this since it would violate the web standard. Additionally, the original +API makes it easy to forget to remove listeners.This API allows safely using
+AbortSignals in Node.js APIs by solving these +two issues by listening to the event such thatstopImmediatePropagationdoes +not prevent the listener from running.Returns a disposable so that it may be unsubscribed from more easily.
+
+ +import { addAbortListener } from 'node:events';
function example(signal) {
let disposable;
try {
signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
disposable = addAbortListener(signal, (e) => {
// Do something when signal is aborted.
});
} finally {
disposable?.[Symbol.dispose]();
}
} +Parameters
- signal: AbortSignal
- resource: ((event: Event) => void)
- (event): void
Parameters
- event: Event
Returns void
Returns Disposable
Disposable that removes the
+abortlistener.
Staticget
- get
Event Listeners(emitter, name): Function[] Returns a copy of the array of listeners for the event named
+eventName.For
+EventEmitters this behaves exactly the same as calling.listenerson +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.
+ +import { getEventListeners, EventEmitter } from 'node:events';
{
const ee = new EventEmitter();
const listener = () => console.log('Events are fun');
ee.on('foo', listener);
console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
const et = new EventTarget();
const listener = () => console.log('Events are fun');
et.addEventListener('foo', listener);
console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
} +Parameters
- emitter: EventEmitter<DefaultEventMap> | EventTarget
- name: string | symbol
Returns Function[]
Staticget
- get
Max Listeners(emitter): number Returns the currently set max amount of listeners.
+For
+EventEmitters this behaves exactly the same as calling.getMaxListenerson +the emitter.For
+EventTargets this is the only way to get the max event listeners for the +event target. If the number of event handlers on a single EventTarget exceeds +the max set, the EventTarget will print a warning.
+ +import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';
{
const ee = new EventEmitter();
console.log(getMaxListeners(ee)); // 10
setMaxListeners(11, ee);
console.log(getMaxListeners(ee)); // 11
}
{
const et = new EventTarget();
console.log(getMaxListeners(et)); // 10
setMaxListeners(11, et);
console.log(getMaxListeners(et)); // 11
} +Parameters
- emitter: EventEmitter<DefaultEventMap> | EventTarget
Returns number
Staticlistener
- listener
Count(emitter, eventName): number A class method that returns the number of listeners for the given
+eventNameregistered on the givenemitter.
+ +import { EventEmitter, listenerCount } from 'node:events';
const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2 +Parameters
- emitter: EventEmitter<DefaultEventMap>
The emitter to query
+ - eventName: string | symbol
The event name
+
Returns number
- emitter: EventEmitter<DefaultEventMap>
Staticon
- on(emitter, eventName, options?): AsyncIterator<any[], any, any>
+ +import { on, EventEmitter } from 'node:events';
import process from 'node:process';
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
+AsyncIteratorthat iterateseventNameevents. It will throw +if theEventEmitteremits'error'. It removes all listeners when +exiting the loop. Thevaluereturned by each iteration is an array +composed of the emitted event arguments.An
+AbortSignalcan be used to cancel waiting on events:
+ +import { on, EventEmitter } from 'node:events';
import process from 'node:process';
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()); +Use the
+closeoption to specify an array of event names that will end the iteration:
+ +import { on, EventEmitter } from 'node:events';
import process from 'node:process';
const ee = new EventEmitter();
// Emit later on
process.nextTick(() => {
ee.emit('foo', 'bar');
ee.emit('foo', 42);
ee.emit('close');
});
for await (const event of on(ee, 'foo', { close: ['close'] })) {
console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done' +Parameters
- emitter: EventEmitter<DefaultEventMap>
- eventName: string | symbol
Optionaloptions: StaticEventEmitterIteratorOptions
Returns AsyncIterator<any[], any, any>
An
+AsyncIteratorthat iterateseventNameevents emitted by theemitter- on(emitter, eventName, options?): AsyncIterator<any[], any, any>
Parameters
- emitter: EventTarget
- eventName: string
Optionaloptions: StaticEventEmitterIteratorOptions
Returns AsyncIterator<any[], any, any>
Staticonce
- once(emitter, eventName, options?): Promise<any[]>
Creates a
+Promisethat is fulfilled when theEventEmitteremits the given +event or that is rejected if theEventEmitteremits'error'while waiting. +ThePromisewill 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.
+ +import { once, EventEmitter } from 'node:events';
import process from 'node:process';
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.error('error happened', err);
} +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 without +special handling:
+ +import { EventEmitter, once } from 'node:events';
const ee = new EventEmitter();
once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.error('error', err.message));
ee.emit('error', new Error('boom'));
// Prints: ok boom +An
+AbortSignalcan be used to cancel waiting for the event:
+ +import { EventEmitter, once } from 'node: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! +Parameters
- emitter: EventEmitter<DefaultEventMap>
- eventName: string | symbol
Optionaloptions: StaticEventEmitterOptions
Returns Promise<any[]>
- once(emitter, eventName, options?): Promise<any[]>
Parameters
- emitter: EventTarget
- eventName: string
Optionaloptions: StaticEventEmitterOptions
Returns Promise<any[]>
Staticset
- set
Max Listeners(n?, ...eventTargets): void
+ +import { setMaxListeners, EventEmitter } from 'node:events';
const target = new EventTarget();
const emitter = new EventEmitter();
setMaxListeners(5, target, emitter); +Parameters
Optionaln: numberA non-negative number. The maximum number of listeners per
+EventTargetevent.Rest...eventTargets: (EventEmitter<DefaultEventMap> | EventTarget)[]Zero or more {EventTarget} or {EventEmitter} instances. If none are specified,
+nis set as the default max for all newly created {EventTarget} and {EventEmitter} +objects.
Returns void
An alias for AbstractCursor.close|AbstractCursor.close().
+