From ffe6886de9cc8a25b67efc91653310f5ae184421 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 6 Jul 2020 12:51:46 -0700 Subject: [PATCH] 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 Reviewed-By: Anna Henningsen --- doc/api/events.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/api/events.md b/doc/api/events.md index d6aab8feab1d9b..84f2fe199684a9 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`