Skip to main content

EventEmitter

The EventEmitter class provides methods to implement the observable design pattern. This pattern allows one to register a function to execute when a specific event is emitted by the emitter.

It is intended to be an abstract class meant to be extended by (or mixed into) other objects.

Constructor

Creates a new EventEmitterobject.

Parameters

new EventEmitter([eventsSuspended])

ParameterTypeDefaultDescription
[eventsSuspended]boolean
falseWhether the EventEmitter is initially in a suspended state (i.e. not executing callbacks).

Properties

.ANY_EVENT

Type: Symbol

Identifier to use when adding or removing a listener that should be triggered when any events occur.

.eventCount

Type: number
Attributes: read-only

The number of unique events that have registered listeners.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventMap

Type: Object
Attributes: read-only

An object containing a property for each event with at least one registered listener. Each event property contains an array of all the Listener objects registered for the event.

.eventNames

Type: Array.<string>
Attributes: read-only

An array of all the unique event names for which the emitter has at least one registered listener.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventsSuspended

Type: boolean

Whether or not the execution of callbacks is currently suspended for this emitter.


Methods

.addListener(...)

Adds a listener for the specified event. It returns the Listener object that was created and attached to the event.

To attach a global listener that will be triggered for any events, use EventEmitter.ANY_EVENT as the first parameter. Note that a global listener will also be triggered by non-registered events.

Parameters

Signature: addListener(event, callback, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to listen to.
callbackEventEmitter~callback
The callback function to execute when the event occurs.
[options]Object
{}
[options.context]Object
thisThe value of this in the callback function.
[options.prepend]boolean
falseWhether the listener should be added at the beginning of the listeners array and thus executed first.
[options.duration]number
InfinityThe number of milliseconds before the listener automatically expires.
[options.remaining]number
InfinityThe number of times after which the callback should automatically be removed.
[options.arguments]array
An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

Return Value

Returns: Listener

The newly created Listener object.

Throws:

  • TypeError : The event parameter must be a string or EventEmitter.ANY_EVENT.
  • TypeError : The callback parameter must be a function.

.addOneTimeListener(...)

Adds a one-time listener for the specified event. The listener will be executed once and then destroyed. It returns the Listener object that was created and attached to the event.

To attach a global listener that will be triggered for any events, use EventEmitter.ANY_EVENT as the first parameter. Note that a global listener will also be triggered by non-registered events.

Parameters

Signature: addOneTimeListener(event, callback, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to listen to
callbackEventEmitter~callback
The callback function to execute when the event occurs
[options]Object
{}
[options.context]Object
thisThe context to invoke the callback function in.
[options.prepend]boolean
falseWhether the listener should be added at the beginning of the listeners array and thus executed first.
[options.duration]number
InfinityThe number of milliseconds before the listener automatically expires.
[options.arguments]array
An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

Return Value

Returns: Listener

The newly created Listener object.

Throws:

  • TypeError : The event parameter must be a string or EventEmitter.ANY_EVENT.
  • TypeError : The callback parameter must be a function.

.emit(...)

Executes the callback function of all the Listener objects registered for a given event. The callback functions are passed the additional arguments passed to emit() (if any) followed by the arguments present in the arguments property of the Listener object (if any).

If the eventsSuspended property is true or the Listener.suspended property is true, the callback functions will not be executed.

This function returns an array containing the return values of each of the callbacks.

It should be noted that the regular listeners are triggered first followed by the global listeners (those added with EventEmitter.ANY_EVENT).

Parameters

Signature: emit(event, ...args)

ParameterType(s)DefaultDescription
eventstring
The event
args*
Arbitrary number of arguments to pass along to the callback functions

Return Value

Returns: Array

An array containing the return value of each of the executed listener functions.

Throws:

  • TypeError : The event parameter must be a string.

.getListenerCount(...)

Returns the number of listeners registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) do not count towards the remaining number for a "regular" event. To get the number of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListenerCount(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event which is usually a string but can also be the special EventEmitter.ANY_EVENT symbol.

Return Value

Returns: number

An integer representing the number of listeners registered for the specified event.

.getListeners(...)

Returns an array of all the Listener objects that have been registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) are not returned for "regular" events. To get the list of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListeners(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to get listeners for.

Return Value

Returns: Array.<Listener>

An array of Listener objects.

.hasListener(...)

Returns true if the specified event has at least one registered listener. If no event is specified, the method returns true if any event has at least one listener registered (this includes global listeners registered to EventEmitter.ANY_EVENT).

Note: to specifically check for global listeners added with EventEmitter.ANY_EVENT, use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: hasListener([event], [callback])

ParameterType(s)DefaultDescription
[event]string
Symbol
(any event)The event to check
[callback]function
Listener
(any callback)The actual function that was added to the event or the Listener object returned by addListener().

Return Value

Returns: boolean

.removeListener(...)

Removes all the listeners that were added to the object upon which the method is called and that match the specified criterias. If no parameters are passed, all listeners added to this object will be removed. If only the event parameter is passed, all listeners for that event will be removed from that object. You can remove global listeners by using EventEmitter.ANY_EVENT as the first parameter.

To use more granular options, you must at least define the event. Then, you can specify the callback to match or one or more of the additional options.

Parameters

Signature: removeListener([event], [callback], [options])

ParameterType(s)DefaultDescription
[event]string
The event name.
[callback]EventEmitter~callback
Only remove the listeners that match this exact callback function.
[options]Object
[options.context]*
Only remove the listeners that have this exact context.
[options.remaining]number
Only remove the listener if it has exactly that many remaining times to be executed.

.suspendEvent(...)

Suspends execution of all callbacks functions registered for the specified event type.

You can suspend execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to suspendEvent(). Beware that this will not suspend all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive at first glance, it allows the selective suspension of global listeners while leaving other listeners alone. If you truly want to suspends all callbacks for a specific EventEmitter, simply set its eventsSuspended property to true.

Parameters

Signature: suspendEvent(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event name (or EventEmitter.ANY_EVENT) for which to suspend execution of all callback functions.

.unsuspendEvent(...)

Resumes execution of all suspended callback functions registered for the specified event type.

You can resume execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to unsuspendEvent(). Beware that this will not resume all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive, it allows the selective unsuspension of global listeners while leaving other callbacks alone.

Parameters

Signature: unsuspendEvent(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event name (or EventEmitter.ANY_EVENT) for which to resume execution of all callback functions.

.waitFor(...)

Attributes: async

The waitFor() method is an async function which returns a promise. The promise is fulfilled when the specified event occurs. The event can be a regular event or EventEmitter.ANY_EVENT (if you want to resolve as soon as any event is emitted).

If the duration option is set, the promise will only be fulfilled if the event is emitted within the specified duration. If the event has not been fulfilled after the specified duration, the promise is rejected. This makes it super easy to wait for an event and timeout after a certain time if the event is not triggered.

Parameters

Signature: waitFor(event, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to wait for
[options]Object
{}
[options.duration]number
InfinityThe number of milliseconds to wait before the promise is automatically rejected.