Skip to content

Latest commit

 

History

History
160 lines (103 loc) · 6.89 KB

README.md

File metadata and controls

160 lines (103 loc) · 6.89 KB

Promise Events

Build Status Coverage Status

NPM

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.

Contribution

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

License

MIT