events: add once method to use promises with EventEmitter

This change adds a EventEmitter.once() method that wraps ee.once in a
promise.

Co-authored-by: David Mark Clements <david.mark.clements@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/26078
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

1 files changed, 93 insertions, 0 deletions

diff --git a/test/parallel/test-events-once.js b/test/parallel/test-events-once.js
new file mode 100644
index 0000000000..f99604018a
--- /dev/null
+++ b/test/parallel/test-events-once.js
@@ -0,0 +1,93 @@
+'use strict';
+
+const common = require('../common');
+const { once, EventEmitter } = require('events');
+const { strictEqual, deepStrictEqual } = require('assert');
+
+async function onceAnEvent() {
+  const ee = new EventEmitter();
+
+  process.nextTick(() => {
+    ee.emit('myevent', 42);
+  });
+
+  const [value] = await once(ee, 'myevent');
+  strictEqual(value, 42);
+  strictEqual(ee.listenerCount('error'), 0);
+  strictEqual(ee.listenerCount('myevent'), 0);
+}
+
+async function onceAnEventWithTwoArgs() {
+  const ee = new EventEmitter();
+
+  process.nextTick(() => {
+    ee.emit('myevent', 42, 24);
+  });
+
+  const value = await once(ee, 'myevent');
+  deepStrictEqual(value, [42, 24]);
+}
+
+async function catchesErrors() {
+  const ee = new EventEmitter();
+
+  const expected = new Error('kaboom');
+  let err;
+  process.nextTick(() => {
+    ee.emit('error', expected);
+  });
+
+  try {
+    await once(ee, 'myevent');
+  } catch (_e) {
+    err = _e;
+  }
+  strictEqual(err, expected);
+  strictEqual(ee.listenerCount('error'), 0);
+  strictEqual(ee.listenerCount('myevent'), 0);
+}
+
+async function stopListeningAfterCatchingError() {
+  const ee = new EventEmitter();
+
+  const expected = new Error('kaboom');
+  let err;
+  process.nextTick(() => {
+    ee.emit('error', expected);
+    ee.emit('myevent', 42, 24);
+  });
+
+  process.on('multipleResolves', common.mustNotCall());
+
+  try {
+    await once(ee, 'myevent');
+  } catch (_e) {
+    err = _e;
+  }
+  process.removeAllListeners('multipleResolves');
+  strictEqual(err, expected);
+  strictEqual(ee.listenerCount('error'), 0);
+  strictEqual(ee.listenerCount('myevent'), 0);
+}
+
+async function onceError() {
+  const ee = new EventEmitter();
+
+  const expected = new Error('kaboom');
+  process.nextTick(() => {
+    ee.emit('error', expected);
+  });
+
+  const [err] = await once(ee, 'error');
+  strictEqual(err, expected);
+  strictEqual(ee.listenerCount('error'), 0);
+  strictEqual(ee.listenerCount('myevent'), 0);
+}
+
+Promise.all([
+  onceAnEvent(),
+  onceAnEventWithTwoArgs(),
+  catchesErrors(),
+  stopListeningAfterCatchingError(),
+  onceError()
+]);