async-eventemitter

What is async-eventemitter?

The async-eventemitter npm package is an extension of the Node.js EventEmitter that supports asynchronous event handlers. It allows you to handle events with asynchronous functions, making it easier to work with promises and async/await in event-driven programming.

What are async-eventemitter's main functionalities?

Basic Asynchronous Event Handling

This feature allows you to register an asynchronous event handler using the `on` method. The event handler can use async/await to handle asynchronous operations.

const AsyncEventEmitter = require('async-eventemitter');
const emitter = new AsyncEventEmitter();

emitter.on('event', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 1000));
  console.log('Event handled with data:', data);
});

emitter.emit('event', 'some data');

Handling Multiple Asynchronous Listeners

This feature demonstrates how multiple asynchronous listeners can be registered for the same event. Each listener will handle the event asynchronously and independently.

const AsyncEventEmitter = require('async-eventemitter');
const emitter = new AsyncEventEmitter();

emitter.on('event', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 1000));
  console.log('First listener handled with data:', data);
});

emitter.on('event', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 500));
  console.log('Second listener handled with data:', data);
});

emitter.emit('event', 'some data');

Waiting for All Listeners to Complete

This feature shows how to wait for all asynchronous listeners to complete before proceeding. The `emit` method returns a promise that resolves when all listeners have finished handling the event.

const AsyncEventEmitter = require('async-eventemitter');
const emitter = new AsyncEventEmitter();

emitter.on('event', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 1000));
  console.log('First listener handled with data:', data);
});

emitter.on('event', async (data) => {
  await new Promise(resolve => setTimeout(resolve, 500));
  console.log('Second listener handled with data:', data);
});

(async () => {
  await emitter.emit('event', 'some data');
  console.log('All listeners have completed');
})();

Other packages similar to async-eventemitter

events

The `events` package is the standard Node.js EventEmitter module. It provides basic event handling capabilities but does not natively support asynchronous event handlers. You can use promises or async/await within event handlers, but the EventEmitter itself does not manage the asynchronous flow.

eventemitter2

The `eventemitter2` package is an enhanced version of the Node.js EventEmitter with additional features like wildcard event names and event namespacing. While it offers more flexibility in event handling, it does not specifically focus on asynchronous event handling like async-eventemitter.

eventemitter3

The `eventemitter3` package is a lightweight and fast EventEmitter implementation. It is designed for performance and simplicity but does not include built-in support for asynchronous event handlers. It is suitable for scenarios where performance is critical and asynchronous handling is managed manually.

README

AsyncEventEmitter

An EventEmitter that supports serial execution of asynchronous event listeners. It also supports event listeners without callbacks (synchronous), as well as interrupting the call-chain (similar to the DOM's e.stopPropagation()).

Example

var AsyncEventEmitter = require('async-eventemitter');
var events = new AsyncEventEmitter();

events.on('test', function (e, next) {
  // The next event listener will wait til this is done
  setTimeout(next, 1000);
});

events
  .on('test', function (e) {
    // This is behaves a synchronous event listener (note the lack of a second
    // callback argument)
    console.log(e);
    // { data: 'data' }
  })
  .on('test', function (e, next) {
    // Even if you're not truly asynchronous you can use next() to stop propagation
    next(new Error('You shall not pass'));
  });

events.trigger('test', { data: 'data' }, function (err) {
  // This is run after all of the event listeners are done
  console.log(err);
  // [Error: You shall not pass]
});

More examples are found in the test-folder.

Important differences between AsyncEventEmitter the native EventEmitter

The API and behavior of AsyncEventEmitter is as far as possible and meaningful identical to that of the native EventEmitter. However there are some important differences which should be noted.

• Data sent to event listeners (eg emit(data)) must always be zero or one argument, and can not be a function.
• Event listeners will always recieve the data object, which may or may not be undefined.
• The second argument can only be a callback, and will only be supplied if the event listener has an arity of two or more (eg function(e, next){}).
• Event listeners with an arity of one or zero (eg without a callback argument specified) will be treated as synchronous.
• Even if all event listeners are synchronous, the will still be executed asynchronously (through setImmediate) and thus code suceeding .emit() will be executed before any event listeners.

Usage

Unchanged

For addListener() on() once() removeListener() removeAllListeners() setMaxListeners() listeners() see the EventEmitter docs, nothing new here.

emit(event, [data], [callback])

Executes all listeners for the event in order with the supplied data argument. The optional callback is called when all of the listeners are done.

To do

The following are features that will be necessary now that the order of event listeners really matters:

• .first(event, new)
  • should unshift an event listener
• .before(event, target, new)
  • should insert an event listener before the target
• .after(event, target, new)
  • should insert an event listener after the target
• .at(event, index, new)
  • should insert an event listener at the specified index

Contribution

1. Create an issue and tell me what you're gonna do, just to make sure there's no duplicate work
2. Fork and branch your feature-branch of the develop branch
3. Write tests for changed/added functionality and make sure you don't break existing ones
4. Adhere to existing code style
5. Submit a pull-request to the develop branch

License

The MIT License (MIT)

Copyright © 2013 Andreas Hultgren