diff options
author | James M Snell <jasnell@gmail.com> | 2020-07-06 22:51:46 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-07-09 17:25:08 +0300 |
commit | 949d1c1f0c65867f2cc79b860c83a2f76d4aee9d (patch) | |
tree | 5209660c02abd2acaff10751fad9dff299b37cca /doc/api/events.md | |
parent | a95fb930d0d2bcf8ba3c86f4525d1348e60a7507 (diff) |
doc: document behavior for once(ee, 'error')
Fixes: https://github.com/nodejs/node/issues/31244
PR-URL: https://github.com/nodejs/node/pull/34225
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/events.md')
-rw-r--r-- | doc/api/events.md | 21 |
1 files changed, 20 insertions, 1 deletions
diff --git a/doc/api/events.md b/doc/api/events.md index 39950b5c12f..2ffd9ce6664 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -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. @@ -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: |