eventplus

Events Plus

This module defines an API similar to EventEmitter (like Node's built-in events module), but with an extra method: .handle().

The .handle() method

Events are a broadcast system - when .emit() is called, all listeners get notified.

With .handle(), you have the option to consume the event such that no other handlers or listeners are notified. This is done asynchronously, by appending an additional argument next() to the event arguments for handlers:

myObj.handle('message', function (arg1, next) {
    // Asynchronously
    setTimeout(function () {
        next();
    }, 1000);
});
myObj.on('message', function (arg1) {
    // Called only if all handlers pass through - therefore not guaranteed to by synchronous
});

myObj.emit('message', 'foo');

Handlers are always called before listeners. Handlers are called in the order they are registered.

The .off() method (equivalent to .removeListener() or .removeAllListeners() depending on arguments) can also be used to remove a function as either a listener or a handler. Much like .removeListener(), if a function is present in both capacities, or is present multiple times, it will only be removed once and it is undefined which entries will be removed first.

Usage

Nothing lives in the prototype, so you can include the interface just by calling the constructor. You can pass in the object to enhance as the first argument - otherwise it uses this:

function MyClass() {
    EventPlus(this); // or: EventPlus.call(this) if it makes you happier
    // init
}
MyClass.prototype = {...} // No need to inherit prototype

Minimal version

The version in basic.js contains only the basic methods:

• .on()
• .handle()
• .off()
• .emit()

The minified version basic.min.js is quite small (around 750 bytes) so that you can easily include it in your own project.

License

This package is released as CC-0 - you can re-use any part of it in any way without restriction (including re-licensing under different terms).