events-async

Asynchronous emit for node event emitters.

Installation

$ npm install events-async

Features

• Support asynchronous executions inside listeners, on emit.
• Can pause, resume or abort a chain during event execution.
• Does NOT modify any of the emitter properties, nor EventEmitter.prototype.
• Wraps around any object, not just EventEmitter - Note: .listeners() method is required.
• Provides both the emit method replacer and AsyncEmitter class.
• a .ready() method for when a chain finished processing.

Exports

This module exposes the following properties:

• (Function) emit - Replacement function for EventEmitter.prototype.emit, which enables the features of the library.
• (Function) emitBool - Same as .emit, but will return a boolean.
• (Class) AsyncEmitter - EventEmitter subclass that has the .emit() method replaced with the one provided by this library.
  • Method: emit
• (Class) Emitter - Alias to AsyncEmitter.
• (Class) EventEmitter - Alias to AsyncEmitter.
• (Function) returns - Function used for post-processing the result returned by .emit and .emitBool exposed by this library.

Aditional reference

• wrapper (inside listeners)
  • wrapper.wait()
  • wrapper.wait(callback)
  • wrapper.next()
  • wrapper.abort()
• emitResult wrapper
  • emitResult.ready()
  • emitResult.ready(callback)
  • emitResult.ready(emitter)

Usage

Quick example:

var asyncEmitter = require('events-async');

var emitter = new EventEmitter();
// replace the emit method
emitter.emit = asyncEmitter.emit; // preferred over `emitter.emit = asyncEmitter`

// add some listeners
emitter.on('something', function listener1() {
    this.wait(); // pause the chain execution.
    var wrapper = this; // just a reference for later use.
    someAsyncFunction(function onAsyncFinished() {
        wrapper.next(); // execute next listener in chain. (line #9)
    });
});

emitter.on('something', function listener2() {
  // code will execute after 'onAsyncFinished' calls .next() [line #9]
});

// Now emit something
emitter.emit('something', someParameter);

// emit again, but this time do something after the chain finished
emitter.emit('something', someOtherParameter).ready(function onready() {
    if (this.ready.aborted) {
        // chain was aborted
    } else {
        // chain finished without being aborted
    }
});

AsyncEmitter example:

// load the library
var AsyncEmitter = require('events-async').AsyncEmitter;
// create an emitter
var emitter = new AsyncEmitter();
// add some listeners
emitter.on('something', function listener1() {
  // do some stuff just like in the quick example
});
// emit something
emitter.emit('something');

Using .emit() without replacing the method:

var emit = require('events-async').emit;

/**
 * same as
 * > emitter.emit = emit;
 * > emitter.emit('something', param1, param2, ...);
 */
emit.call(emitter, 'something', param1, param2, ...);

Contact

• Issues for this repo
• Wiki for this repo
• @mpotra on Twitter
• mpotra on GitHub