Classes
Members
-
<static> ANY_EVENT :Symbol
-
Description
Identifier to use when adding or removing a listener that should be triggered when any events occur.
Details
-
<readonly> eventCount :number
-
Description
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.Details
-
<readonly> eventMap :Object
-
Description
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.Details
-
<readonly> eventNames :Array.<string>
-
Description
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.Details
-
eventsSuspended :boolean
-
Description
Whether or not the execution of callbacks is currently suspended for this emitter.
Details
Methods
-
addListener( event, callback [, options ] ) → {Listener}
-
Description
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
Name Type Attributes Default Description event
string | Symbol The event to listen to.
callback
EventEmitter~callback The callback function to execute when the event occurs.
options
Object <optional> {} Name Type Attributes Default Description context
Object <optional> this The value of
this
in the callback function.prepend
boolean <optional> false Whether the listener should be added at the beginning of the listeners array and thus executed first.
duration
number <optional> Infinity The number of milliseconds before the listener automatically expires.
remaining
number <optional> Infinity The number of times after which the callback should automatically be removed.
arguments
array <optional> An array of arguments which will be passed separately to the callback function. This array is stored in the
arguments
property of theListener
object and can be retrieved or modified as desired.Returns
Throws
Details
-
addOneTimeListener( event, callback [, options ] ) → {Listener}
-
Description
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
Name Type Attributes Default Description event
string | Symbol The event to listen to
callback
EventEmitter~callback The callback function to execute when the event occurs
options
Object <optional> {} Name Type Attributes Default Description context
Object <optional> this The context to invoke the callback function in.
prepend
boolean <optional> false Whether the listener should be added at the beginning of the listeners array and thus executed first.
duration
number <optional> Infinity The number of milliseconds before the listener automatically expires.
arguments
array <optional> An array of arguments which will be passed separately to the callback function. This array is stored in the
arguments
property of theListener
object and can be retrieved or modified as desired.Returns
Throws
Details
-
emit( event, ...args ) → {Array}
-
Description
Executes the callback function of all the
Listener
objects registered for a given event. The callback functions are passed the additional arguments passed toemit()
(if any) followed by the arguments present in thearguments
property of theListener
object (if any).If the
eventsSuspended
property istrue
or theListener.suspended
property istrue
, 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
Name Type Attributes Description event
string The event
args
* <repeatable> Arbitrary number of arguments to pass along to the callback functions
Returns
Throws
Details
-
getListenerCount( event ) → {number}
-
Description
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 useEventEmitter.ANY_EVENT
as the parameter.Parameters
Name Type Description event
string | Symbol The event which is usually a string but can also be the special
EventEmitter.ANY_EVENT
symbol.Returns
Details
-
getListeners( event ) → {Array.<Listener>}
-
Description
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 useEventEmitter.ANY_EVENT
as the parameter.Parameters
Name Type Description event
string | Symbol The event to get listeners for.
Returns
Details
-
hasListener( [ event [, callback ] ] ) → {boolean}
-
Description
Returns
true
if the specified event has at least one registered listener. If no event is specified, the method returnstrue
if any event has at least one listener registered (this includes global listeners registered toEventEmitter.ANY_EVENT
).Note: to specifically check for global listeners added with
EventEmitter.ANY_EVENT
, useEventEmitter.ANY_EVENT
as the parameter.Parameters
Name Type Attributes Default Description event
string | Symbol <optional> (any event) The event to check
callback
function | Listener <optional> (any callback) The actual function that was added to the event or the Listener object returned by
addListener()
.Returns
Details
-
removeListener( [ event [, callback [, options ] ] ] )
-
Description
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 usingEventEmitter.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
Name Type Attributes Description event
string <optional> The event name.
callback
EventEmitter~callback <optional> Only remove the listeners that match this exact callback function.
options
Object <optional> Name Type Attributes Description context
* <optional> Only remove the listeners that have this exact context.
remaining
number <optional> Only remove the listener if it has exactly that many remaining times to be executed.
Details
-
suspendEvent( event )
-
Description
Suspends execution of all callbacks functions registered for the specified event type.
You can suspend execution of callbacks registered with
EventEmitter.ANY_EVENT
by passingEventEmitter.ANY_EVENT
tosuspendEvent()
. Beware that this will not suspend all callbacks but only those registered withEventEmitter.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 specificEventEmitter
, simply set itseventsSuspended
property totrue
.Parameters
Name Type Description event
string | Symbol The event name (or
EventEmitter.ANY_EVENT
) for which to suspend execution of all callback functions.Details
-
unsuspendEvent( event )
-
Description
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 passingEventEmitter.ANY_EVENT
tounsuspendEvent()
. Beware that this will not resume all callbacks but only those registered withEventEmitter.ANY_EVENT
. While this may seem counter-intuitive, it allows the selective unsuspension of global listeners while leaving other callbacks alone.Parameters
Name Type Description event
string | Symbol The event name (or
EventEmitter.ANY_EVENT
) for which to resume execution of all callback functions.Details
-
<async> waitFor( event [, options ] )
-
Description
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 orEventEmitter.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
Name Type Attributes Default Description event
string | Symbol The event to wait for
options
Object <optional> {} Name Type Attributes Default Description duration
number <optional> Infinity The number of milliseconds to wait before the promise is automatically rejected.
Details
Type Definitions
-
callback( [ ...args ] )
-
Description
The callback function is executed when the associated event is triggered via
emit()
. Theemit()
method relays all additional arguments it received to the callback functions. Sinceemit()
can be passed a variable number of arguments, it is up to the developer to make sure the arguments match those of the associated callback. In addition, the callback also separately receives all the arguments present in the listener'sarguments
property. This makes it easy to pass data from where the listener is added to where the listener is executed.Parameters
Name Type Attributes Description args
* <optional>
<repeatable>A variable number of arguments matching the ones (if any) that were passed to the
emit()
method (except, the first one) followed by the arguments found in the listener'sarguments
array.Details