events: add async emitter.when

doc/api/errors.md

@@ -614,6 +614,23 @@ Used when the native call from `process.cpuUsage` cannot be processed properly.
 
 Used when `c-ares` failed to set the DNS server.
 
+<a id="ERR_EVENTS_WHEN_CANCELED"></a>
+### ERR_EVENTS_WHEN_CANCELED
+
+Used when a `Promise` created using `emitter.when()` has been rejected because
+the listener has been removed.
+
+```js
+const EventEmitter = require('events');
+
+const ee = new EventEmitter();
+ee.when('foo').then(() => { /* ... */ }).catch((reason) => {
+  console.log(reason.code); // ERR_EVENTS_WHEN_CANCELED
+});
+
+ee.removeAllListeners('foo');
+```
+
 <a id="ERR_FALSY_VALUE_REJECTION"></a>
 ### ERR_FALSY_VALUE_REJECTION
 

doc/api/events.md

@@ -586,6 +586,54 @@ to indicate an unlimited number of listeners.
 
 Returns a reference to the `EventEmitter`, so that calls can be chained.
 
+### async emitter.when(eventName[, options])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `eventName` {any} The name of the event.
+* `options` {Object}
+  * `prepend` {boolean} True to prepend the handler used to resolve the
+    `Promise` to the handler queue.
+* Returns: {Promise}
+
+Creates and returns a `Promise` that is resolved with a one-time event handler.
+
+```js
+const myEmitter = new EventEmitter();
+
+const p = myEmitter.when('foo')
+                   .then((context) => {
+                     console.log(context.args);
+                   });
+
+myEmitter.emit('foo', 1, 2, 3);
+```
+
+The `Promise` is resolved with a `context` object that contains two properties:
+
+* `emitter` {EventEmitter} A reference to the `EventEmitter` instance.
+* `args` {Array} An array containing the additional arguments passed to the
+  `emitter.emit()` function.
+
+When a `Promise` is created, a corresponding `removeListener` event handler is
+registered that will reject the `Promise` if it has not already been resolved.
+When rejected in this manner, the rejection `reason` shall be a simple string
+equal to `'canceled'`.
+
+```js
+const myEmitter = new EventEmitter();
+
+const p = myEmitter.when('foo')
+                   .catch((reason) => {
+                     if (reason === 'canceled') {
+                       // The promise was canceled using removeListener
+                     }
+                   });
+
+myEmitter.removeAllListeners();
+```
+
 [`--trace-warnings`]: cli.html#cli_trace_warnings
 [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
 [`domain`]: domain.html

lib/events.js

@@ -41,6 +41,27 @@ EventEmitter.prototype._maxListeners = undefined;
 // added to it. This is a useful default which helps finding memory leaks.
 var defaultMaxListeners = 10;
 
+var errors;
+function lazyErrors() {
+  if (!errors) {
+    errors = require('internal/errors');
+  }
+  return errors;
+}
+
+var createPromise;
+var promiseReject;
+var promiseResolve;
+
+function lazyPromiseBinding() {
+  if (!createPromise) {
+    const util = process.binding('util');
+    createPromise = util.createPromise;
+    promiseReject = util.promiseReject;
+    promiseResolve = util.promiseResolve;
+  }
+}
+
 Object.defineProperty(EventEmitter, 'defaultMaxListeners', {
   enumerable: true,
   get: function() {
@@ -351,6 +372,51 @@ EventEmitter.prototype.prependOnceListener =
       return this;
     };
 
+// An awaitable one-time event listener. Registers a once handler and
+// returns an associated promise.
+EventEmitter.prototype.when =
+    function when(type, options = { prepend: false }) {
+      if (options == null || typeof options !== 'object') {
+        // This must be lazy evaluated
+        const errors = lazyErrors();
+        throw new errors.TypeError('ERR_INVALID_ARG_TYPE',
+                                   'options', 'object');
+      }
+      lazyPromiseBinding();
+      const promise = createPromise();
+      let resolved = false;
+      const listener = (...args) => {
+        resolved = true;
+        this.removeListener(type, listener);
+        promiseResolve(promise, { emitter: this, args });
+      };
+      Object.defineProperties(listener, {
+        name: { value: `promise for '${type}'` },
+        promise: { value: promise }
+      });
+      // When a listener is removed, and the promise has not yet been
+      // resolved, reject it with a simple reason.
+      const cancel = (eventName, removedListener) => {
+        const errors = lazyErrors();
+        if (!resolved && eventName === type && removedListener === listener) {
+          this.removeListener('removeListener', cancel);
+          promiseReject(promise,
+                        new errors.Error('ERR_EVENTS_WHEN_CANCELED', type));
+        }
+      };
+      // Do not use once because it will trigger a removeListener *before*
+      // the promise is resolved, which throws off the cancel logic when
+      // removeListener is called.
+      if (options.prepend) {
+        this.prependListener(type, listener);
+        this.prependListener('removeListener', cancel);
+      } else {
+        this.on(type, listener);
+        this.on('removeListener', cancel);
+      }
+      return promise;
+    };
+
 // Emits a 'removeListener' event if and only if the listener was removed.
 EventEmitter.prototype.removeListener =
     function removeListener(type, listener) {

lib/internal/errors.js

@@ -116,6 +116,8 @@ E('ERR_ENCODING_INVALID_ENCODED_DATA',
   (enc) => `The encoded data was not valid for encoding ${enc}`);
 E('ERR_ENCODING_NOT_SUPPORTED',
   (enc) => `The "${enc}" encoding is not supported`);
+E('ERR_EVENTS_WHEN_CANCELED',
+  (type) => `The when '${type}' promise was canceled`);
 E('ERR_FALSY_VALUE_REJECTION', 'Promise was rejected with falsy value');
 E('ERR_HTTP_HEADERS_SENT',
   'Cannot %s headers after they are sent to the client');

test/parallel/test-event-emitter-when.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const EventEmitter = require('events');
+
+const ee = new EventEmitter();
+
+{
+  ee.when('foo')
+    .then(common.mustCall((context) => {
+      assert.strictEqual(context.emitter, ee);
+      assert.deepStrictEqual(context.args, [1, 2, 3]);
+    }))
+    .catch(common.mustNotCall());
+  assert.strictEqual(ee.listenerCount('foo'), 1);
+  ee.emit('foo', 1, 2, 3);
+  assert.strictEqual(ee.listenerCount('foo'), 0);
+}
+
+{
+  let a = 1;
+  ee.when('foo')
+    .then(common.mustCall(() => {
+      assert.strictEqual(a, 2);
+    }))
+    .catch(common.mustNotCall());
+
+  ee.when('foo', { prepend: true })
+    .then(common.mustCall(() => {
+      assert.strictEqual(a++, 1);
+    }))
+    .catch(common.mustNotCall());
+
+  ee.emit('foo');
+}
+
+{
+  ee.when('foo')
+    .then(common.mustCall(() => {
+      throw new Error('foo');
+    }))
+    .catch(common.mustCall((err) => {
+      assert.strictEqual(err.message, 'foo');
+    }));
+  assert.strictEqual(ee.listenerCount('foo'), 1);
+  ee.emit('foo');
+  assert.strictEqual(ee.listenerCount('foo'), 0);
+}
+
+{
+  ee.removeAllListeners();
+  ee.when('foo')
+    .then(common.mustNotCall())
+    .catch(common.expectsError({
+      code: 'ERR_EVENTS_WHEN_CANCELED',
+      type: Error,
+      message: 'The when \'foo\' promise was canceled'
+    }));
+  ee.removeAllListeners();
+}
+
+{
+  ee.removeAllListeners();
+  assert.strictEqual(ee.listenerCount(0), 0);
+  const promise = ee.when('foo');
+  promise.then(common.mustNotCall())
+          .catch(common.expectsError({
+            code: 'ERR_EVENTS_WHEN_CANCELED',
+            type: Error,
+            message: 'The when \'foo\' promise was canceled'
+          }));
+  const fn = ee.listeners('foo')[0];
+  assert.strictEqual(fn.name, 'promise for \'foo\'');
+  assert.strictEqual(fn.promise, promise);
+  ee.removeListener('foo', fn);
+}
+
+process.on('unhandledRejection', common.mustNotCall());