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 MylesBorins committed Jul 16, 2020
1 parent a6a656a commit ffe6886
Showing 1 changed file with 20 additions and 1 deletion.
21 changes: 20 additions & 1 deletion doc/api/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -837,7 +837,7 @@ added:
* 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 @@ -873,6 +873,25 @@ async function run() {
run();
```

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

0 comments on commit ffe6886

Please sign in to comment.