StaticcaptureValue: boolean
Change the default captureRejections option on
all new EventEmitter objects.
Static
ReadonlycaptureValue: Symbol.for('nodejs.rejection')
See how to write a custom rejection handler.
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.
Private WebSocket
Public WebSocket
Optional[captureAuthenticate to the private websocket.
Connect to the private websocket.
Connect to the public websocket.
Disconnect from the private websocket.
Disconnect from the public websocket.
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 the current max listener value for the
EventEmitter which is either set by
emitter.setMaxListeners(n) or defaults to
EventEmitter.defaultMaxListeners.
Get the list of current private subscriptions.
Get the list of current public subscriptions.
Returns the number of listeners listening for the event
named eventName. If
listener is provided, it will return how
many times the listener is found in the list of the
listeners of the event.
The name of the event being listened for
Optionallistener:
Function
The event handler function
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] ]
Send a ping message to the private server.
Send a ping message to the public server.
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');
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.
OptionaleventName:
string
|
symbol
Removes the specified listener from the
listener array for the event named
eventName.
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 any removeListener() or
removeAllListeners() 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 the
once('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.
Send a message to the WebSocket server
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
to Infinity (or 0) to indicate
an unlimited number of listeners.
Returns a reference to the EventEmitter, so
that calls can be chained.
Subscribe to the balances channel.
Subscribe to the book channel.
Subscribe to the channel (candles).
Subscribe to the book_lv2 channel.
Subscribe to the orders channel.
Subscribe to the ticker channel.
Subscribe to the trades channel.
Unsubscribe from the balances channel.
Unsubscribe from the book channel.
Unsubscribe from the channel (candles).
Unsubscribe from the book_lv2 channel.
Unsubscribe from the orders channel.
Unsubscribe from all public channels.
Unsubscribe from all public channels.
Unsubscribe from the ticker channel.
Unsubscribe from the trades channel.
StaticaddExperimental
Listens once to the abort event on the
provided signal.
Listening to the abort event on abort
signals is unsafe and may lead to resource leaks since
another third party with the signal can call
e.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 that
stopImmediatePropagation does 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]();
}
}
Disposable that removes the abort listener.
Staticget
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.
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] ]
}
StaticgetReturns the currently set max amount of listeners.
For EventEmitters this behaves exactly the
same as calling .getMaxListeners on 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
}
Staticlistener
A class method that returns the number of listeners for
the given eventName registered on the given
emitter.
import { EventEmitter, listenerCount } from 'node: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
Staticon
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 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:
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 close option 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'
Optionaloptions:
StaticEventEmitterIteratorOptions
An AsyncIterator that iterates
eventName events emitted by the
emitter
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 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:
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 close option 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'
Optionaloptions:
StaticEventEmitterIteratorOptions
An AsyncIterator that iterates
eventName events emitted by the
emitter
Staticonce
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.
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 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:
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 AbortSignal can 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!
Optionaloptions:
StaticEventEmitterOptions
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.
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 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:
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 AbortSignal can 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!
Optionaloptions:
StaticEventEmitterOptions
Staticsetimport { setMaxListeners, EventEmitter } from 'node:events';
const target = new EventTarget();
const emitter = new EventEmitter();
setMaxListeners(5, target, emitter);
Optionaln:
number
A non-negative number. The maximum number of
listeners per EventTarget event.
Zero or more {EventTarget} or {EventEmitter}
instances. If none are specified,
n is set as the default max for all
newly created {EventTarget} and {EventEmitter}
objects.
Create WebSocketClient.