events: add EventEmitter.on to async iterate over events #27994

mcollina · 2019-05-31T13:47:54Z

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

benjamingr · 2019-05-31T14:19:57Z

lib/events.js

+    },
+
+    throw(err) {
+      // TODO should we validate that err exists?


No, I think we shouldn't since it is allowed to throw undefined. I really hope users don't actually do it.

test/parallel/test-event-on-async-iterator.js

doc/api/events.md

benjamingr · 2019-05-31T14:35:59Z

CC @davidmarkclements since you maintain the .on shim in case you want to make a shim for this on NPM. If you don't I don't mind making one.

zero1five · 2019-06-01T11:58:17Z

I like this!! 😆
I studied the this API for five or six hours, and there's something odd about it that I want to point out (if I stray from the subject, feel free to hide).

One test case seems to have a bug. I'm not sure what caused it Gist code

Specific steps for recurrence:

git pr 27994 upstream
./configure && make -j4
../Release/node ../index.js

It is clear that the async function exits directly after the for await of.

davidmarkclements · 2019-06-01T12:18:08Z

CC @davidmarkclements since you maintain the .on shim in case you want to make a shim for this on NPM. If you don't I don't mind making one.

thanks @benjamingr - I've had the events.on shim ready since releasing events.once 😆 - I'm just waiting for core to land in case I need to adapt

lib/events.js

vsemozhetbyt

Thank you!

vsemozhetbyt · 2019-06-01T15:05:16Z

doc/api/events.md

@@ -694,6 +694,37 @@ async function run() {
 run();
 ```

+## events.on(emitter, event)


Nit: needs to be placed before events.once() alphabetically?

doc/api/events.md

benjamingr · 2019-06-02T08:46:56Z

@zero1five thanks for the test case, definitely relevant I'll look into it when I'm in front of a computer

benjamingr · 2019-06-02T09:39:21Z

@zero1five hey, I ran your code example but I wasn't able to figure out what the confusing part was. Do you mean how that pending promises do not keep the event loop live if there is no scheduled I/O?

Raynos · 2019-06-07T10:06:48Z

Some events in node core emit a single value.

Would it be possible to add an option to this api to return the first value emitted instead of an array of all values emitted.

benjamingr · 2019-06-07T11:05:43Z

@Raynos hey, long time no see. Happy to see you around here :]

Node already shipped (recently) an EventEmitter.once static method that does just that. https://nodejs.org/api/events.html#events_events_once_emitter_name

Raynos · 2019-06-07T21:42:05Z

@Raynos hey, long time no see. Happy to see you around here :]

I was at the openjs summit in berlin, next time I see you i'll say hello properly.

Node already shipped (recently) an EventEmitter.once static method that does just that.

I meant an option to return the first value emitted, aka emitter.emit('foo', firstValue) instead of only listening to a single emission of the event like once.

The current implementation would require some destructuring in the common case

for await (const [message] of on(worker, 'message')) {
   ...
}

benjamingr · 2019-06-09T07:00:51Z

@Raynos lol, I had no idea we were in the same room for two days :) definitely say hi next time!

nodejs-github-bot · 2019-12-22T14:24:29Z

CI: https://ci.nodejs.org/job/node-test-pull-request/27868/

doc/api/events.md

Co-Authored-By: Benjamin Gruenbaum <inglor@gmail.com>

nodejs-github-bot · 2019-12-22T23:19:32Z

CI: https://ci.nodejs.org/job/node-test-pull-request/27880/

Trott · 2019-12-23T01:07:50Z

CI passed. I think this is ready to land?

Fixes: #27847 PR-URL: #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>

mcollina · 2019-12-23T08:29:45Z

Landed in 38a593b

Fixes: #27847 PR-URL: #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>

Notable changes: * assert: * Implement `assert.match()` and `assert.doesNotMatch()` (Ruben Bridgewater) #30929 * events: * Add `EventEmitter.on` to async iterate over events (Matteo Collina) #27994 * Allow monitoring error events (Gerhard Stoebich) #30932 * fs: * Allow overriding `fs` for streams (Robert Nagy) #29083 * perf_hooks: * Move `perf_hooks` out of experimental (legendecas) #31101 * repl: * Implement ZSH-like reverse-i-search (Ruben Bridgewater) #31006 * tls: * Add PSK (pre-shared key) support (Denys Otrishko) #23188 PR-URL: #31238

Fixes: #27847 PR-URL: #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>

jayflo · 2020-01-30T19:27:57Z

lib/events.js

+      }
+
+      // If the iterator is finished, resolve to done
+      if (finished) {


Stupid question: how does finished get set to true in the non-error case? From what I see here, after the final event is resolved, won't the for await of loop will be waiting on a promise from unconsumedPromises? It seems like some sort of "on finished" callback would be needed.

Fixes: #27847 PR-URL: #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>

Notable changes: New assert APIs The `assert` module now provides experimental `assert.match()` and `assert.doesNotMatch()` methods. They will validate that the first argument is a string and matches (or does not match) the provided regular expression This is an experimental feature. Ruben Bridgewater [#30929](#30929). Advanced serialization for IPC The `child_process` and `cluster` modules now support a `serialization` option to change the serialization mechanism used for IPC. The option can have one of two values: * `'json'` (default): `JSON.stringify()` and `JSON.parse()` are used. This is how message serialization was done before. * `'advanced'`: The serialization API of the `v8` module is used. It is based on the HTML structured clone algorithm. and is able to serialize more built-in JavaScript object types, such as `BigInt`, `Map`, `Set` etc. as well as circular data structures. Anna Henningsen [#30162](#30162). CLI flags The new `--trace-exit` CLI flag makes Node.js print a stack trace whenever the Node.js environment is exited proactively (i.e. by invoking the `process.exit()` function or pressing Ctrl+C). legendecas [#30516](#30516). ___ The new `--trace-uncaught` CLI flag makes Node.js print a stack trace at the time of throwing uncaught exceptions, rather than at the creation of the `Error` object, if there is any. This option is not enabled by default because it may affect garbage collection behavior negatively. Anna Henningsen [#30025](#30025). ___ The `--disallow-code-generation-from-strings` V8 CLI flag is now whitelisted in the `NODE_OPTIONS` environment variable. Shelley Vohr [#30094](#30094). New crypto APIs For DSA and ECDSA, a new signature encoding is now supported in addition to the existing one (DER). The `verify` and `sign` methods accept a `dsaEncoding` option, which can have one of two values: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. Tobias Nießen [#29292](#29292). ___ A new method was added to `Hash`: `Hash.prototype.copy`. It makes it possible to clone the internal state of a `Hash` object into a new `Hash` object, allowing to compute the digest between updates. Ben Noordhuis [#29910](#29910). Dependency updates libuv was updated to 1.34.0. This includes fixes to `uv_fs_copyfile()` and `uv_interface_addresses()` and adds two new functions: `uv_sleep()` and `uv_fs_mkstemp()`. Colin Ihrig [#30783](#30783). ___ V8 was updated to 7.8.279.23. This includes performance improvements to object destructuring, RegExp match failures and WebAssembly startup time. The official release notes are available at https://v8.dev/blog/v8-release-78. Michaël Zasso [#30109](#30109). New EventEmitter APIs The new `EventEmitter.on` static method allows to async iterate over events. Matteo Collina [#27994](#27994). ___ It is now possible to monitor `'error'` events on an `EventEmitter` without consuming the emitted error by installing a listener using the symbol `EventEmitter.errorMonitor`. Gerhard Stoebich [#30932](#30932). ___ Using `async` functions with event handlers is problematic, because it can lead to an unhandled rejection in case of a thrown exception. The experimental `captureRejections` option in the `EventEmitter` constructor or the global setting change this behavior, installing a `.then(undefined, handler)` handler on the `Promise`. This handler routes the exception asynchronously to the `Symbol.for('nodejs.rejection')` method if there is one, or to the `'error'` event handler if there is none. Setting `EventEmitter.captureRejections = true` will change the default for all new instances of `EventEmitter`. This is an experimental feature. Matteo Collina [#27867](#27867). Performance Hooks are no longer experimental The `perf_hooks` module is now considered a stable API. legendecas [#31101](#31101). Introduction of experimental WebAssembly System Interface (WASI) support A new core module, `wasi`, is introduced to provide an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives sandboxed WebAssembly applications access to the underlying operating system via a collection of POSIX-like functions. This is an experimental feature. Colin Ihrig [#30258](#30258). PR-URL: #31691

Port of nodejs/node#27994

mcollina requested review from jasnell, benjamingr, devsnek and BridgeAR May 31, 2019 13:47