Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add added: information for events #7822

Closed
wants to merge 1 commit into from
Closed

doc: add added: information for events #7822

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions doc/api/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,9 @@ myEmitter.emit('error', new Error('whoops!'));
```

## Class: EventEmitter
<!-- YAML
added: v0.1.26
-->

The `EventEmitter` class is defined and exposed by the `events` module:

Expand All @@ -178,6 +181,9 @@ All EventEmitters emit the event `'newListener'` when new listeners are
added and `'removeListener'` when existing listeners are removed.

### Event: 'newListener'
<!-- YAML
added: v0.1.26
-->

* `eventName` {String|Symbol} The name of the event being listened for
* `listener` {Function} The event handler function
Expand Down Expand Up @@ -214,13 +220,20 @@ myEmitter.emit('event');
```

### Event: 'removeListener'
<!-- YAML
added: v0.9.3
-->

* `eventName` {String|Symbol} The event name
* `listener` {Function} The event handler function

The `'removeListener'` event is emitted *after* the `listener` is removed.

### EventEmitter.listenerCount(emitter, eventName)
<!-- YAML
added: v0.9.12
deprecated: v4.0.0
-->

Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.

Expand All @@ -236,6 +249,9 @@ console.log(EventEmitter.listenerCount(myEmitter, 'event'));
```

### EventEmitter.defaultMaxListeners
<!-- YAML
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
Expand Down Expand Up @@ -263,10 +279,16 @@ emitter.once('event', () => {
```

### emitter.addListener(eventName, listener)
<!-- YAML
added: v0.1.26
-->

Alias for `emitter.on(eventName, listener)`.

### emitter.emit(eventName[, arg1][, arg2][, ...])
<!-- YAML
added: v0.1.26
-->

Synchronously calls each of the listeners registered for the event named
`eventName`, in the order they were registered, passing the supplied arguments
Expand All @@ -275,6 +297,9 @@ to each.
Returns `true` if the event had listeners, `false` otherwise.

### emitter.eventNames()
<!-- YAML
added: v6.0.0
-->

Returns an array listing the events for which the emitter has registered
listeners. The values in the array will be strings or Symbols.
Expand All @@ -293,18 +318,27 @@ console.log(myEE.eventNames());
```

### emitter.getMaxListeners()
<!-- YAML
added: v1.0.0
-->

Returns the current max listener value for the `EventEmitter` which is either
set by [`emitter.setMaxListeners(n)`][] or defaults to
[`EventEmitter.defaultMaxListeners`][].

### emitter.listenerCount(eventName)
<!-- YAML
added: v3.2.0
-->

* `eventName` {String|Symbol} The name of the event being listened for

Returns the number of listeners listening to the event named `eventName`.

### emitter.listeners(eventName)
<!-- YAML
added: v0.1.26
-->

Returns a copy of the array of listeners for the event named `eventName`.

Expand All @@ -317,6 +351,9 @@ console.log(util.inspect(server.listeners('connection')));
```

### emitter.on(eventName, listener)
<!-- YAML
added: v0.1.101
-->

* `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function
Expand Down Expand Up @@ -350,6 +387,9 @@ myEE.emit('foo');
```

### emitter.once(eventName, listener)
<!-- YAML
added: v0.3.0
-->

* `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function
Expand Down Expand Up @@ -380,6 +420,9 @@ myEE.emit('foo');
```

### emitter.prependListener(eventName, listener)
<!-- YAML
added: v6.0.0
-->

* `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function
Expand All @@ -399,6 +442,9 @@ 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
-->

* `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function
Expand All @@ -416,6 +462,9 @@ server.prependOnceListener('connection', (stream) => {
Returns a reference to the `EventEmitter`, so that calls can be chained.

### emitter.removeAllListeners([eventName])
<!-- YAML
added: v0.1.26
-->

Removes all listeners, or those of the specified `eventName`.

Expand All @@ -426,6 +475,9 @@ 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
-->

Removes the specified `listener` from the listener array for the event named
`eventName`.
Expand Down Expand Up @@ -490,6 +542,9 @@ the `emitter.listeners()` method will need to be recreated.
Returns a reference to the `EventEmitter`, so that calls can be chained.

### emitter.setMaxListeners(n)
<!-- YAML
added: v0.3.5
-->

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
Expand Down