README.md

Promise Events

An asynchronous event listener for Promise/A+ implementations. This module inherits Node's built-in EventEmitter interface, except that selected methods are overridden to return a promise for easy workflow.

In essence, replacing existing code with this emitter should have no impact whatsoever, added that this emitter can work either synchronously or asynchrnously, except that all events are emitted asynchronously.

NOTE: Modules that expect event emitting to be synchronous should be refactored to wait for the promise resolution instead.

Usage

const EventEmitter = require('promise-events');

var events = new EventEmitter();

// synchronous
events.on('syncEvent', hello => {
  console.log(hello);
});

events.emit('syncEvent', 'hello!');


// asynchronous
Promise.all([
  events.on('asyncEvent', hello => {
    console.log('Handler 1', hello);
    return 'Bye!';
  }),
  events.on('asyncEvent', hello => {
    console.log('Handler 2', hello);
  })
]).then(() => {
  console.log("Event added and any newListener listeners emitted!");
}).then(() => {

  events.emit('asyncEvent', 'Hello async!').then(results => {
    console.log(results);
    // results = [ 'Bye!', undefined ]
  });

});

// using async/await
await events.on('asyncEvent', hello => {
  console.log('Handler 1', hello);
  return 'Bye!';
});
await events.on('asyncEvent', hello => {
  console.log('Handler 2', hello);
});

console.log("Event added and any newListener listeners emitted!");

const results = await events.emit('asyncEvent', 'Hello async!');

console.log(results);
// results = [ 'Bye!', undefined ]

All listeners are executed using Promise.all.

A call to events.emit will always resolve with an array if successful, or a single value--usually an Error--otherwise from any listener; the first error thrown, or failure/rejection, will be passed to the rejection callback and all subsequent listeners' resturned values will be ignored.

If necessary, a filter function may be specified for the array of return values using events.setResultFilter(filter) (resp. events.getResultFilter() and EventEmitter.defaultResultFilter, analogous to EventEmitter.defaultMaxListeners). Because listeners are called asynchronously, the order of the items in results is undefined. Therefore, the amount of listeners, for a given event, and their added order to an emitter is not an indicator of the length of results or even the order of values returned when emitting that event. In other words, do not rely on results to determine a particular listener's return value.

This module also provides a sugar overload of .once() for a Promise-based version of .once() which will guarantee to be called after all listeners have been emitted, regardless when the listeners were added.

// nearly equivalent to events.once('foo', () => console.log('foo!'));
events.once('foo').then(() => console.log('Done!'));
// IMPORTANT : Do not use await on this method unless you know the event will
//             be emitted from another asynchronous function!

events.on('foo', () => console.log('foo'));

events.emit('foo');
// => foo
// => Done!
events.emit('foo');
// => foo

API

Most of the implementation is fully compatible with the standard EventEmitter. Any extension and overrides are in bold, and differences are annotated.

• Event: 'newListener'

• Event: 'removeListener'

• EventEmitter.listenerCount(emitter, eventName) deprecated

• EventEmitter.defaultMaxListeners

• EventEmitter.defaultResultFilter

• EventEmitter.errorMonitor

• emitter.addListener(eventName, listener)

  Returns a Promise resolving when all newListener events have been emitted.

• emitter.emit(eventName[, ...args])

  Returns a Promise.

• emitter.eventNames()

• emitter.getMaxListeners()

• emitter.getResultFilter()

  Return the result filter function.

• emitter.listenerCount(eventName)

• emitter.listeners(eventName)

• emitter.maxListeners

  Alias for emitter.getMaxListeners() and emitter.setMaxListeners().

• emitter.on(eventName, listener)

  Returns a Promise resolving when all newListener events have been emitted.

• emitter.once(eventName)

  Returns a Promise that is resolved once only after all listeners for the specified event have been called for the given event. (Any newListener event will be emitted.)

• emitter.prependListener(eventName, listener)

  Returns a Promise resolving when all newListener events have been emitted.

• emitter.prependOnceListener(eventName)

  Returns a Promise that is resolved once only before all listeners for the specified event have been called for the given event. (Any newListener event will be emitted.)

• emitter.removeAllListeners([eventName])

  Returns a Promise resolving when all removeListener events have been emitted.

• emitter.removeListener(eventName, listener)

  Returns a Promise resolving when all removeListener events have been emitted.

• emitter.resultFilter

  Alias for emitter.getResultFilter() and emitter.setResultFilter().

• emitter.setMaxListeners(n)

• emitter.setResultFilter()

  Set the result filter function.

Contribution

All contributions welcome! Every PR must be accompanied by their associated unit tests!

License

MIT