events: add EventEmitter.on to async iterate over events

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>

Author: mcollina

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 () => {
+constee=newEventEmitter();
+
+// Emit later on
+process.nextTick(() => {
+ee.emit('foo', 'bar');
+ee.emit('foo', 42);
+ });
+
+forawait (consteventofon(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

lib/events.js

@@ -29,12 +29,16 @@ const {
  ObjectCreate,
  ObjectDefineProperty,
  ObjectGetPrototypeOf,
+ ObjectSetPrototypeOf,
  ObjectKeys,
  Promise,
+ PromiseReject,
+ PromiseResolve,
  ReflectApply,
  ReflectOwnKeys,
  Symbol,
  SymbolFor,
+ SymbolAsyncIterator
 }=primordials;
 constkRejection=SymbolFor('nodejs.rejection');
 
@@ -62,6 +66,7 @@ function EventEmitter(opts) {
 }
 module.exports=EventEmitter;
 module.exports.once=once;
+module.exports.on=on;
 
 // Backwards-compat with node 0.10.x
 EventEmitter.EventEmitter=EventEmitter;
@@ -657,3 +662,102 @@ function once(emitter, name) {
 emitter.once(name,eventListener);
 });
 }
+
+constAsyncIteratorPrototype=ObjectGetPrototypeOf(
+ObjectGetPrototypeOf(asyncfunction*(){}).prototype);
+
+functioncreateIterResult(value,done){
+return{ value, done };
+}
+
+functionon(emitter,event){
+constunconsumedEvents=[];
+constunconsumedPromises=[];
+leterror=null;
+letfinished=false;
+
+constiterator=ObjectSetPrototypeOf({
+next(){
+// First, we consume all unread events
+constvalue=unconsumedEvents.shift();
+if(value){
+returnPromiseResolve(createIterResult(value,false));
+}
+
+// Then we error, if an error happened
+// This happens one time if at all, because after 'error'
+// we stop listening
+if(error){
+constp=PromiseReject(error);
+// Only the first element errors
+error=null;
+returnp;
+}
+
+// If the iterator is finished, resolve to done
+if(finished){
+returnPromiseResolve(createIterResult(undefined,true));
+}
+
+// Wait until an event happens
+returnnewPromise(function(resolve,reject){
+unconsumedPromises.push({ resolve, reject });
+});
+},
+
+return(){
+emitter.removeListener(event,eventHandler);
+emitter.removeListener('error',errorHandler);
+finished=true;
+
+for(constpromiseofunconsumedPromises){
+promise.resolve(createIterResult(undefined,true));
+}
+
+returnPromiseResolve(createIterResult(undefined,true));
+},
+
+throw(err){
+if(!err||!(errinstanceofError)){
+thrownewERR_INVALID_ARG_TYPE('EventEmitter.AsyncIterator',
+'Error',err);
+}
+error=err;
+emitter.removeListener(event,eventHandler);
+emitter.removeListener('error',errorHandler);
+},
+
+[SymbolAsyncIterator](){
+returnthis;
+}
+},AsyncIteratorPrototype);
+
+emitter.on(event,eventHandler);
+emitter.on('error',errorHandler);
+
+returniterator;
+
+functioneventHandler(...args){
+constpromise=unconsumedPromises.shift();
+if(promise){
+promise.resolve(createIterResult(args,false));
+}else{
+unconsumedEvents.push(args);
+}
+}
+
+functionerrorHandler(err){
+finished=true;
+
+consttoError=unconsumedPromises.shift();
+
+if(toError){
+toError.reject(err);
+}else{
+// The next time we call next()
+error=err;
+}
+
+iterator.return();
+}
+}

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

@@ -0,0 +1,223 @@
+'use strict';
+
+constcommon=require('../common');
+constassert=require('assert');
+const{ on, EventEmitter }=require('events');
+
+asyncfunctionbasic(){
+constee=newEventEmitter();
+process.nextTick(()=>{
+ee.emit('foo','bar');
+// 'bar' is a spurious event, we are testing
+// that it does not show up in the iterable
+ee.emit('bar',24);
+ee.emit('foo',42);
+});
+
+constiterable=on(ee,'foo');
+
+constexpected=[['bar'],[42]];
+
+forawait(consteventofiterable){
+constcurrent=expected.shift();
+
+assert.deepStrictEqual(current,event);
+
+if(expected.length===0){
+break;
+}
+}
+assert.strictEqual(ee.listenerCount('foo'),0);
+assert.strictEqual(ee.listenerCount('error'),0);
+}
+
+asyncfunctionerror(){
+constee=newEventEmitter();
+const_err=newError('kaboom');
+process.nextTick(()=>{
+ee.emit('error',_err);
+});
+
+constiterable=on(ee,'foo');
+letlooped=false;
+letthrown=false;
+
+try{
+// eslint-disable-next-line no-unused-vars
+forawait(consteventofiterable){
+looped=true;
+}
+}catch(err){
+thrown=true;
+assert.strictEqual(err,_err);
+}
+assert.strictEqual(thrown,true);
+assert.strictEqual(looped,false);
+}
+
+asyncfunctionerrorDelayed(){
+constee=newEventEmitter();
+const_err=newError('kaboom');
+process.nextTick(()=>{
+ee.emit('foo',42);
+ee.emit('error',_err);
+});
+
+constiterable=on(ee,'foo');
+constexpected=[[42]];
+letthrown=false;
+
+try{
+forawait(consteventofiterable){
+constcurrent=expected.shift();
+assert.deepStrictEqual(current,event);
+}
+}catch(err){
+thrown=true;
+assert.strictEqual(err,_err);
+}
+assert.strictEqual(thrown,true);
+assert.strictEqual(ee.listenerCount('foo'),0);
+assert.strictEqual(ee.listenerCount('error'),0);
+}
+
+asyncfunctionthrowInLoop(){
+constee=newEventEmitter();
+const_err=newError('kaboom');
+
+process.nextTick(()=>{
+ee.emit('foo',42);
+});
+
+try{
+forawait(consteventofon(ee,'foo')){
+assert.deepStrictEqual(event,[42]);
+throw_err;
+}
+}catch(err){
+assert.strictEqual(err,_err);
+}
+
+assert.strictEqual(ee.listenerCount('foo'),0);
+assert.strictEqual(ee.listenerCount('error'),0);
+}
+
+asyncfunctionnext(){
+constee=newEventEmitter();
+constiterable=on(ee,'foo');
+
+process.nextTick(function(){
+ee.emit('foo','bar');
+ee.emit('foo',42);
+iterable.return();
+});
+
+constresults=awaitPromise.all([
+iterable.next(),
+iterable.next(),
+iterable.next()
+]);
+
+assert.deepStrictEqual(results,[{
+value: ['bar'],
+done: false
+},{
+value: [42],
+done: false
+},{
+value: undefined,
+done: true
+}]);
+
+assert.deepStrictEqual(awaititerable.next(),{
+value: undefined,
+done: true
+});
+}
+
+asyncfunctionnextError(){
+constee=newEventEmitter();
+constiterable=on(ee,'foo');
+const_err=newError('kaboom');
+process.nextTick(function(){
+ee.emit('error',_err);
+});
+constresults=awaitPromise.allSettled([
+iterable.next(),
+iterable.next(),
+iterable.next()
+]);
+assert.deepStrictEqual(results,[{
+status: 'rejected',
+reason: _err
+},{
+status: 'fulfilled',
+value: {
+value: undefined,
+done: true
+}
+},{
+status: 'fulfilled',
+value: {
+value: undefined,
+done: true
+}
+}]);
+assert.strictEqual(ee.listeners('error').length,0);
+}
+
+asyncfunctioniterableThrow(){
+constee=newEventEmitter();
+constiterable=on(ee,'foo');
+
+process.nextTick(()=>{
+ee.emit('foo','bar');
+ee.emit('foo',42);// lost in the queue
+iterable.throw(_err);
+});
+
+const_err=newError('kaboom');
+letthrown=false;
+
+assert.throws(()=>{
+// No argument
+iterable.throw();
+},{
+message: 'The "EventEmitter.AsyncIterator" property must be'+
+' an instance of Error. Received undefined',
+name: 'TypeError'
+});
+
+constexpected=[['bar'],[42]];
+
+try{
+forawait(consteventofiterable){
+assert.deepStrictEqual(event,expected.shift());
+}
+}catch(err){
+thrown=true;
+assert.strictEqual(err,_err);
+}
+assert.strictEqual(thrown,true);
+assert.strictEqual(expected.length,0);
+assert.strictEqual(ee.listenerCount('foo'),0);
+assert.strictEqual(ee.listenerCount('error'),0);
+}
+
+asyncfunctionrun(){
+constfuncs=[
+basic,
+error,
+errorDelayed,
+throwInLoop,
+next,
+nextError,
+iterableThrow
+];
+
+for(constfnoffuncs){
+awaitfn();
+}
+}
+
+run().then(common.mustCall());