Skip to content

Commit

Permalink
doc: document behavior for once(ee, 'error')
Browse files Browse the repository at this point in the history
Fixes: #31244

PR-URL: #34225
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
  • Loading branch information
jasnell authored and addaleax committed Sep 28, 2020
1 parent ed055c0 commit a9f0fc9
Showing 1 changed file with 21 additions and 2 deletions.
23 changes: 21 additions & 2 deletions doc/api/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -829,7 +829,7 @@ added: v11.13.0
* Returns: {Promise}

Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given
event or that is rejected when the `EventEmitter` emits `'error'`.
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.

Expand Down Expand Up @@ -865,7 +865,26 @@ async function run() {
run();
```

## events.captureRejections
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:

```js
const { EventEmitter, once } = require('events');

const ee = new EventEmitter();

once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.log('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom
```

## `events.captureRejections`
<!-- YAML
added: v12.16.0
-->
Expand Down

0 comments on commit a9f0fc9

Please sign in to comment.