diff options
Diffstat (limited to 'doc/api/events.md')
| -rw-r--r-- | doc/api/events.md | 116 |
1 files changed, 93 insertions, 23 deletions
diff --git a/doc/api/events.md b/doc/api/events.md index 5d34a311cf..f3ef831a48 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -113,7 +113,7 @@ myEmitter.emit('event'); Using the `eventEmitter.once()` method, it is possible to register a listener that is called at most once for a particular event. Once the event is emitted, -the listener is unregistered and *then* called. +the listener is unregistered and _then_ called. ```js const myEmitter = new MyEmitter(); @@ -226,6 +226,7 @@ do not have a catch handler to avoid infinite error loops: the recommendation is to **not use `async` functions as `'error'` event handlers**. ## Class: `EventEmitter` + <!-- YAML added: v0.1.26 changes: @@ -252,6 +253,7 @@ It supports the following option: **Default:** `false`. ### Event: `'newListener'` + <!-- YAML added: v0.1.26 --> @@ -259,15 +261,15 @@ added: v0.1.26 * `eventName` {string|symbol} The name of the event being listened for * `listener` {Function} The event handler function -The `EventEmitter` instance will emit its own `'newListener'` event *before* +The `EventEmitter` instance will emit its own `'newListener'` event _before_ a listener is added to its internal array of listeners. Listeners registered for the `'newListener'` event are passed the event name and a reference to the listener being added. The fact that the event is triggered before adding the listener has a subtle -but important side effect: any *additional* listeners registered to the same -`name` *within* the `'newListener'` callback are inserted *before* the +but important side effect: any _additional_ listeners registered to the same +`name` _within_ the `'newListener'` callback are inserted _before_ the listener that is in the process of being added. ```js @@ -293,6 +295,7 @@ myEmitter.emit('event'); ``` ### Event: `'removeListener'` + <!-- YAML added: v0.9.3 changes: @@ -307,9 +310,10 @@ changes: * `eventName` {string|symbol} The event name * `listener` {Function} The event handler function -The `'removeListener'` event is emitted *after* the `listener` is removed. +The `'removeListener'` event is emitted _after_ the `listener` is removed. ### `emitter.addListener(eventName, listener)` + <!-- YAML added: v0.1.26 --> @@ -320,6 +324,7 @@ added: v0.1.26 Alias for `emitter.on(eventName, listener)`. ### `emitter.emit(eventName[, ...args])` + <!-- YAML added: v0.1.26 --> @@ -368,6 +373,7 @@ myEmitter.emit('event', 1, 2, 3, 4, 5); ``` ### `emitter.eventNames()` + <!-- YAML added: v6.0.0 --> @@ -391,6 +397,7 @@ console.log(myEE.eventNames()); ``` ### `emitter.getMaxListeners()` + <!-- YAML added: v1.0.0 --> @@ -402,6 +409,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to [`events.defaultMaxListeners`][]. ### `emitter.listenerCount(eventName)` + <!-- YAML added: v3.2.0 --> @@ -412,6 +420,7 @@ added: v3.2.0 Returns the number of listeners listening to the event named `eventName`. ### `emitter.listeners(eventName)` + <!-- YAML added: v0.1.26 changes: @@ -422,7 +431,7 @@ changes: --> * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`. @@ -435,6 +444,7 @@ console.log(util.inspect(server.listeners('connection'))); ``` ### `emitter.off(eventName, listener)` + <!-- YAML added: v10.0.0 --> @@ -446,6 +456,7 @@ added: v10.0.0 Alias for [`emitter.removeListener()`][]. ### `emitter.on(eventName, listener)` + <!-- YAML added: v0.1.101 --> @@ -483,6 +494,7 @@ myEE.emit('foo'); ``` ### `emitter.once(eventName, listener)` + <!-- YAML added: v0.3.0 --> @@ -517,6 +529,7 @@ myEE.emit('foo'); ``` ### `emitter.prependListener(eventName, listener)` + <!-- YAML added: v6.0.0 --> @@ -525,7 +538,7 @@ added: v6.0.0 * `listener` {Function} The callback function * Returns: {EventEmitter} -Adds the `listener` function to the *beginning* of the listeners array for the +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 @@ -540,6 +553,7 @@ server.prependListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.prependOnceListener(eventName, listener)` + <!-- YAML added: v6.0.0 --> @@ -549,7 +563,7 @@ added: v6.0.0 * Returns: {EventEmitter} Adds a **one-time** `listener` function for the event named `eventName` to the -*beginning* of the listeners array. The next time `eventName` is triggered, this +_beginning_ of the listeners array. The next time `eventName` is triggered, this listener is removed, and then invoked. ```js @@ -561,6 +575,7 @@ server.prependOnceListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.removeAllListeners([eventName])` + <!-- YAML added: v0.1.26 --> @@ -577,6 +592,7 @@ component or module (e.g. sockets or file streams). Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.removeListener(eventName, listener)` + <!-- YAML added: v0.1.26 --> @@ -604,8 +620,8 @@ 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 from +`removeListener()` or `removeAllListeners()` calls _after_ emitting and +_before_ the last listener finishes execution will not remove them from `emit()` in progress. Subsequent events behave as expected. ```js @@ -639,7 +655,7 @@ myEmitter.emit('event'); ``` Because listeners are managed using an internal array, calling this will -change the position indices of any listener registered *after* the listener +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. @@ -667,6 +683,7 @@ ee.emit('ping'); Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.setMaxListeners(n)` + <!-- YAML added: v0.3.5 --> @@ -683,12 +700,13 @@ modified for this specific `EventEmitter` instance. The value can be set to Returns a reference to the `EventEmitter`, so that calls can be chained. ### `emitter.rawListeners(eventName)` + <!-- YAML added: v9.4.0 --> * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`, including any wrappers (such as those created by `.once()`). @@ -718,6 +736,7 @@ emitter.emit('log'); ``` ### `emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])` + <!-- YAML added: - v13.4.0 @@ -756,6 +775,7 @@ class MyClass extends EventEmitter { ``` ## `events.defaultMaxListeners` + <!-- YAML added: v0.11.2 --> @@ -763,12 +783,12 @@ added: v0.11.2 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 *all* `EventEmitter` instances, the `events.defaultMaxListeners` +for _all_ `EventEmitter` 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 +change affects _all_ `EventEmitter` instances, including those created before the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has precedence over `events.defaultMaxListeners`. @@ -796,6 +816,7 @@ listeners, respectively. Its `name` property is set to `'MaxListenersExceededWarning'`. ## `events.errorMonitor` + <!-- YAML added: - v13.6.0 @@ -811,14 +832,16 @@ Installing a listener using this symbol does not change the behavior once an regular `'error'` listener is installed. ## `events.getEventListeners(emitterOrTarget, eventName)` + <!-- YAML added: - v15.2.0 - v14.17.0 --> + * `emitterOrTarget` {EventEmitter|EventTarget} * `eventName` {string|symbol} -* Returns: {Function[]} +* Returns: {Function\[]} Returns a copy of the array of listeners for the event named `eventName`. @@ -846,6 +869,7 @@ const { getEventListeners, EventEmitter } = require('events'); ``` ## `events.once(emitter, name[, options])` + <!-- YAML added: - v11.13.0 @@ -976,7 +1000,7 @@ process.nextTick(() => { foo().then(() => console.log('done')); ``` -To catch both events, create each of the Promises *before* awaiting either +To catch both events, create each of the Promises _before_ awaiting either of them, then it becomes possible to use `Promise.all()`, `Promise.race()`, or `Promise.allSettled()`: @@ -999,6 +1023,7 @@ foo().then(() => console.log('done')); ``` ## `events.captureRejections` + <!-- YAML added: - v13.4.0 @@ -1012,6 +1037,7 @@ Value: {boolean} Change the default `captureRejections` option on all new `EventEmitter` objects. ## `events.captureRejectionSymbol` + <!-- YAML added: - v13.4.0 @@ -1025,6 +1051,7 @@ Value: `Symbol.for('nodejs.rejection')` See how to write a custom [rejection handler][rejection]. ## `events.listenerCount(emitter, eventName)` + <!-- YAML added: v0.9.12 deprecated: v3.2.0 @@ -1048,6 +1075,7 @@ console.log(listenerCount(myEmitter, 'event')); ``` ## `events.on(emitter, eventName[, options])` + <!-- YAML added: - v13.6.0 @@ -1115,13 +1143,14 @@ process.nextTick(() => ac.abort()); ``` ## `events.setMaxListeners(n[, ...eventTargets])` + <!-- YAML added: v15.4.0 --> * `n` {number} A non-negative number. The maximum number of listeners per `EventTarget` event. -* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget} +* `...eventsTargets` {EventTarget\[]|EventEmitter\[]} 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. @@ -1138,7 +1167,9 @@ setMaxListeners(5, target, emitter); ``` <a id="event-target-and-event-api"></a> + ## `EventTarget` and `Event` API + <!-- YAML added: v14.5.0 changes: @@ -1170,7 +1201,7 @@ target.addEventListener('foo', (event) => { There are two key differences between the Node.js `EventTarget` and the [`EventTarget` Web API][]: -1. Whereas DOM `EventTarget` instances *may* be hierarchical, there is no +1. Whereas DOM `EventTarget` instances _may_ be hierarchical, there is no concept of hierarchy and event propagation in Node.js. That is, an event dispatched to an `EventTarget` does not propagate through a hierarchy of nested target objects that may each have their own set of handlers for the @@ -1183,8 +1214,8 @@ There are two key differences between the Node.js `EventTarget` and the ### `NodeEventTarget` vs. `EventEmitter` The `NodeEventTarget` object implements a modified subset of the -`EventEmitter` API that allows it to closely *emulate* an `EventEmitter` in -certain situations. A `NodeEventTarget` is *not* an instance of `EventEmitter` +`EventEmitter` API that allows it to closely _emulate_ an `EventEmitter` in +certain situations. A `NodeEventTarget` is _not_ an instance of `EventEmitter` and cannot be used in place of an `EventEmitter` in most cases. 1. Unlike `EventEmitter`, any given `listener` can be registered at most once @@ -1197,7 +1228,7 @@ and cannot be used in place of an `EventEmitter` in most cases. `'removeListener'` events will also not be emitted. 3. The `NodeEventTarget` does not implement any special default behavior for events with type `'error'`. -3. The `NodeEventTarget` supports `EventListener` objects as well as +4. The `NodeEventTarget` supports `EventListener` objects as well as functions as handlers for all event types. ### Event listener @@ -1259,7 +1290,7 @@ by default the error is treated as an uncaught exception on `process.nextTick()`. This means uncaught exceptions in `EventTarget`s will terminate the Node.js process by default. -Throwing within an event listener will *not* stop the other registered handlers +Throwing within an event listener will _not_ stop the other registered handlers from being invoked. The `EventTarget` does not implement any special default handling for `'error'` @@ -1272,6 +1303,7 @@ other Node.js APIs. Any code relying on the `process.on('error')` event should be aligned with the new behavior. ### Class: `Event` + <!-- YAML added: v14.5.0 changes: @@ -1284,6 +1316,7 @@ The `Event` object is an adaptation of the [`Event` Web API][]. Instances are created internally by Node.js. #### `event.bubbles` + <!-- YAML added: v14.5.0 --> @@ -1293,6 +1326,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.cancelBubble()` + <!-- YAML added: v14.5.0 --> @@ -1301,6 +1335,7 @@ Alias for `event.stopPropagation()`. This is not used in Node.js and is provided purely for completeness. #### `event.cancelable` + <!-- YAML added: v14.5.0 --> @@ -1308,6 +1343,7 @@ added: v14.5.0 * Type: {boolean} True if the event was created with the `cancelable` option. #### `event.composed` + <!-- YAML added: v14.5.0 --> @@ -1317,6 +1353,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.composedPath()` + <!-- YAML added: v14.5.0 --> @@ -1326,6 +1363,7 @@ empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. #### `event.currentTarget` + <!-- YAML added: v14.5.0 --> @@ -1335,6 +1373,7 @@ added: v14.5.0 Alias for `event.target`. #### `event.defaultPrevented` + <!-- YAML added: v14.5.0 --> @@ -1345,6 +1384,7 @@ Is `true` if `cancelable` is `true` and `event.preventDefault()` has been called. #### `event.eventPhase` + <!-- YAML added: v14.5.0 --> @@ -1355,6 +1395,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.isTrusted` + <!-- YAML added: v14.5.0 --> @@ -1365,6 +1406,7 @@ The {AbortSignal} `"abort"` event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. #### `event.preventDefault()` + <!-- YAML added: v14.5.0 --> @@ -1372,6 +1414,7 @@ added: v14.5.0 Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. #### `event.returnValue` + <!-- YAML added: v14.5.0 --> @@ -1381,6 +1424,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.srcElement` + <!-- YAML added: v14.5.0 --> @@ -1390,6 +1434,7 @@ added: v14.5.0 Alias for `event.target`. #### `event.stopImmediatePropagation()` + <!-- YAML added: v14.5.0 --> @@ -1397,6 +1442,7 @@ added: v14.5.0 Stops the invocation of event listeners after the current one completes. #### `event.stopPropagation()` + <!-- YAML added: v14.5.0 --> @@ -1404,6 +1450,7 @@ added: v14.5.0 This is not used in Node.js and is provided purely for completeness. #### `event.target` + <!-- YAML added: v14.5.0 --> @@ -1411,6 +1458,7 @@ added: v14.5.0 * Type: {EventTarget} The `EventTarget` dispatching the event. #### `event.timeStamp` + <!-- YAML added: v14.5.0 --> @@ -1420,6 +1468,7 @@ added: v14.5.0 The millisecond timestamp when the `Event` object was created. #### `event.type` + <!-- YAML added: v14.5.0 --> @@ -1429,6 +1478,7 @@ added: v14.5.0 The event type identifier. ### Class: `EventTarget` + <!-- YAML added: v14.5.0 changes: @@ -1439,6 +1489,7 @@ changes: --> #### `eventTarget.addEventListener(type, listener[, options])` + <!-- YAML added: v14.5.0 --> @@ -1481,6 +1532,7 @@ target.removeEventListener('foo', handler, { capture: true }); ``` #### `eventTarget.dispatchEvent(event)` + <!-- YAML added: v14.5.0 --> @@ -1495,6 +1547,7 @@ The registered event listeners is synchronously invoked in the order they were registered. #### `eventTarget.removeEventListener(type, listener)` + <!-- YAML added: v14.5.0 --> @@ -1507,6 +1560,7 @@ added: v14.5.0 Removes the `listener` from the list of handlers for event `type`. ### Class: `NodeEventTarget` + <!-- YAML added: v14.5.0 --> @@ -1517,12 +1571,15 @@ The `NodeEventTarget` is a Node.js-specific extension to `EventTarget` that emulates a subset of the `EventEmitter` API. #### `nodeEventTarget.addListener(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * `once` {boolean} @@ -1534,16 +1591,18 @@ equivalent `EventEmitter` API. The only difference between `addListener()` and `EventTarget`. #### `nodeEventTarget.eventNames()` + <!-- YAML added: v14.5.0 --> -* Returns: {string[]} +* Returns: {string\[]} Node.js-specific extension to the `EventTarget` class that returns an array of event `type` names for which event listeners are registered. #### `nodeEventTarget.listenerCount(type)` + <!-- YAML added: v14.5.0 --> @@ -1556,11 +1615,13 @@ Node.js-specific extension to the `EventTarget` class that returns the number of event listeners registered for the `type`. #### `nodeEventTarget.off(type, listener)` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} * Returns: {EventTarget} this @@ -1568,12 +1629,15 @@ added: v14.5.0 Node.js-specific alias for `eventTarget.removeListener()`. #### `nodeEventTarget.on(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * `once` {boolean} @@ -1582,12 +1646,15 @@ added: v14.5.0 Node.js-specific alias for `eventTarget.addListener()`. #### `nodeEventTarget.once(type, listener[, options])` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} + * `options` {Object} * Returns: {EventTarget} this @@ -1597,6 +1664,7 @@ listener for the given event `type`. This is equivalent to calling `on` with the `once` option set to `true`. #### `nodeEventTarget.removeAllListeners([type])` + <!-- YAML added: v14.5.0 --> @@ -1610,11 +1678,13 @@ removes all registered listeners for `type`, otherwise removes all registered listeners. #### `nodeEventTarget.removeListener(type, listener)` + <!-- YAML added: v14.5.0 --> * `type` {string} + * `listener` {Function|EventListener} * Returns: {EventTarget} this |