Skip to content

Commit ffe6886

Browse files
jasnellMylesBorins
authored andcommitted
doc: document behavior for once(ee, 'error')
Fixes: #31244 PR-URL: #34225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>
1 parent a6a656a commit ffe6886

File tree

1 file changed

+20
-1
lines changed

1 file changed

+20
-1
lines changed

doc/api/events.md

+20-1
Original file line numberDiff line numberDiff line change
@@ -837,7 +837,7 @@ added:
837837
* Returns: {Promise}
838838

839839
Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given
840-
event or that is rejected when the `EventEmitter` emits `'error'`.
840+
event or that is rejected if the `EventEmitter` emits `'error'` while waiting.
841841
The `Promise` will resolve with an array of all the arguments emitted to the
842842
given event.
843843

@@ -873,6 +873,25 @@ async function run() {
873873
run();
874874
```
875875

876+
The special handling of the `'error'` event is only used when `events.once()`
877+
is used to wait for another event. If `events.once()` is used to wait for the
878+
'`error'` event itself, then it is treated as any other kind of event without
879+
special handling:
880+
881+
```js
882+
const { EventEmitter, once } = require('events');
883+
884+
const ee = new EventEmitter();
885+
886+
once(ee, 'error')
887+
.then(([err]) => console.log('ok', err.message))
888+
.catch((err) => console.log('error', err.message));
889+
890+
ee.emit('error', new Error('boom'));
891+
892+
// Prints: ok boom
893+
```
894+
876895
## `events.captureRejections`
877896
<!-- YAML
878897
added:

0 commit comments

Comments
 (0)