Clarify behaviour when listening for 'error' event using once()

[aalexgabi]

The documentation for once states:

Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected when the EventEmitter emits 'error'. The Promise will resolve with an array of all the arguments emitted to the given event.

It's not clear from the documentation what happens when once is used to listen for error event. In my case this is the desired behaviors but I was surprised when my tests were not failing because an error event was emitted.

This:

const { EventEmitter, once } = require('events');

const ee = new EventEmitter();

once(ee, 'error').then(([err]) => {
    console.log('resolves', err);
}).catch((err) => {
    console.log('rejects', err);
})

ee.emit('error', new Error('Hi'))

Prints:

resolves Error: Hi
    at Object.<anonymous> ...

Can you clarify this behaviour in the documentation please?

[sam-github]

Its documented here: https://nodejs.org/api/events.html#events_error_events

This issue isn't specific to the promisified methods. Perhaps every method that listens for an event needs to be linked to that section? Can you do a PR?

[aalexgabi]

@sam-github I don't understand your comment. The section of the documentation you linked does not mention the behavior of once() but the behavior of an EventEmitter.

My issue is that when I read this:

Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected when the EventEmitter emits 'error'. The Promise will resolve with an array of all the arguments emitted to the given event.

I don't know what's going to happen when I listen for an error event using once() because both are true:

• is fulfilled when the EventEmitter emits the given event
• is rejected when the EventEmitter emits 'error'

[simonkcleung]

It is fulfilled if 'error' is emitted, ie the fulfilled handler will be called. The 2nd statement is ignored in this case.

[SowmyaGrama]

Can i work on this?