Add events.once

[goto-bus-stop]

Node.js 11.13 added an EventEmitter.once method: https://nodejs.org/api/events.html#events_events_once_emitter_name

It returns a Promise that resolves when the requested event is fired. If an 'error' event is fired first, the Promise rejects with the error.

The path to implementing this looks a bit like:

• Finding the Node.js implementation (start in lib/events.js in the nodejs/node repository)
• Finding the Node.js tests for this method. Test files are normally named something like test-modulename-functionname.js so you can find them by searching for events-once via the Github UI https://github.com/nodejs/node/find/master
• Copy-paste the test file from Node.js into tests/ and add its require call to tests/index.js. Since this test will require Promise support, it should only be executed if Promises are available. See the require('./symbols.js') call for one approach. (We run browser tests in old IE etc, so Promise support isn't guaranteed.)
• Copy-paste the implementation code into events.js at the correct location (it should be in the same order in the file as in Node.js, to make things easy to cross-reference).
• Port everything to ES5…! It's okay for the method itself to fail if Promise doesn't exist. It should still be possible to use all other events features in environments that do not support Promises, though.
• Document that Promise support or a global polyfill are required for the EventEmitter.once API to work in README.md.

We can then release this as a minor version.

[vvscode]

@goto-bus-stop as far as I see - there is already some .once implementation. And the existing one is incompatible with a new description

https://github.com/Gozala/events/blob/master/tests/once.js

[vweevers]

@vvscode That's require('events').EventEmitter.prototype.once, rather than require('events').once

[goto-bus-stop]

Yes, there is already a EventEmitter.prototype.once method that adds an event listener:

var emitter = new EventEmitter()
emitter.once('xyz', function (arg1, arg2) {
})

This is for the new EventEmitter.once method that returns a Promise instead:

var emitter = new EventEmitter()
var [arg1, arg2] = await EventEmitter.once(emitter, 'xyz')

[vvscode]

Ok. A frew more questions - don't you use any build system for https://github.com/Gozala/events/blob/master/events.js ?

Is it required copy-paste tests or I can write to them by myself?

[goto-bus-stop]

We don't have any build system for events.js. The tests are bundled using browserify but without babel or anything, so they should work in old browsers as much as possible (eg always use .then() instead of await).

The goal is to have identical behaviour to Node.js, so I think our tests should at least be based on Node's. they can be rewritten a bit (and have to be ported to older JS) but they should test the same functionality.

[vweevers]

You can pretty much copy https://github.com/nodejs/node/pull/26078/files, there have been no changes to the once function since that PR

[Doogiemuc]

Most recent version of NodeJS v12.10.0 changed the order of arguments for theoncemethod: https://nodejs.org/api/events.html

[goto-bus-stop]

@Doogiemuc hmm, I don't see it? that would break the entire ecosystem so I hope they wouldn't do that :) There are two .once() functions: the long-time emitter.once(eventName, callback) method and the newer EventEmitter.once(emitter, eventName) associated function.

[vweevers]

It really should have gotten a distinct name 😄