diff options
author | Matteo Collina <hello@matteocollina.com> | 2019-05-30 18:58:55 +0300 |
---|---|---|
committer | Ruben Bridgewater <ruben@bridgewater.de> | 2020-01-03 18:12:11 +0300 |
commit | afecc973d5a7f216bdc180b06a7b26e6628f9e73 (patch) | |
tree | 2be19ee74f671a776c1f3748d8f60a7bca43c027 /doc/api | |
parent | 07e82db764b886de258cfddf92254bda309117dd (diff) |
events: add EventEmitter.on to async iterate over events
Fixes: https://github.com/nodejs/node/issues/27847
PR-URL: https://github.com/nodejs/node/pull/27994
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/events.md | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/doc/api/events.md b/doc/api/events.md index 69f309a73bc..1e2a7660cb9 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -886,6 +886,41 @@ Value: `Symbol.for('nodejs.rejection')` See how to write a custom [rejection handler][rejection]. +## events.on(emitter, eventName) +<!-- YAML +added: REPLACEME +--> + +* `emitter` {EventEmitter} +* `eventName` {string|symbol} The name of the event being listened for +* Returns: {AsyncIterator} that iterates `eventName` events emitted by the `emitter` + +```js +const { on, EventEmitter } = require('events'); + +(async () => { + const ee = new EventEmitter(); + + // Emit later on + process.nextTick(() => { + ee.emit('foo', 'bar'); + ee.emit('foo', 42); + }); + + for await (const event of on(ee, 'foo')) { + // The execution of this inner block is synchronous and it + // processes one event at a time (even with await). Do not use + // if concurrent execution is required. + console.log(event); // prints ['bar'] [42] + } +})(); +``` + +Returns an `AsyncIterator` that iterates `eventName` events. It will throw +if the `EventEmitter` emits `'error'`. It removes all listeners when +exiting the loop. The `value` returned by each iteration is an array +composed of the emitted event arguments. + [WHATWG-EventTarget]: https://dom.spec.whatwg.org/#interface-eventtarget [`--trace-warnings`]: cli.html#cli_trace_warnings [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners |