eventplus

Events Plus

This module defines a class implementing Node's events.EventEmitter, but with extra methods: .handle() and .cascade().

This allows handlers to either consume the event or pass it on (possibly asynchronously):

var EventPlus = require('eventplus');
var emitter = new EventPlus();

emitter.handle('myevent', function (foo, bar, next) {
    if (foo === 'foo') {
        // handle it
    } else {
        next();
    }
});
emitter.handle('myevent', function (foo, bar, next) {
    // Async handler
    someAsyncFunction(bar, function (error, result) {
        if (error) return next(error);
        // handle it
    });
});
emitter.on('myevent', function (foo, bar) {
    // Only called if both handlers fail
    console.log('Unhandled myevent:', foo, bar);
});

emitter.emit('myevent', 'foo', 'bar');

This module does not depend on Node's EventEmitter, but it implements the same API.

Methods

This class implements all the methods of Node's events.EventEmitter, plus the following:

.handle(event, handler)

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) {
    // handle it or call next()
});

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

If an error is supplied (next(new Error(...))), then the remaining handlers are skipped, but listeners are still notified.

If the supplied next() is called more than once, an error is thrown.

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

.handlers()

Same as .listeners(), but for handlers.

.off(?event, ?fn)

The .off() method can also be used to remove a function as either a listener or a handler. If fn is not supplied, all handlers/listeners for that event are removed. If event is not supplied then all handlers/listeners for all events are removed.

For listeners, this makes it equivalent to either .removeListener() or .removeAllListeners(), depending on arguments used.

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.

.cascade(event, [args, ...], callback)

This is similar to .emit(), but with a callback as the final argument:

emitter.cascade('my-event', {...}, function (error, obj) {
});

Similar to .emit(), if any call to next() (see .handle()) provides an error object, then the remainder of the handlers are skipped.

Extra events

Similar to the newListener and removeListener events (fired before a listener is added or after it's removed, respectively), two new events are introduced:

newHandler

Called before a new handler is added, with two arguments:

• event - event name (string)
• handler - handler function to be added

removeHandler

Called after a handler is removed, with two arguments:

• event - event name (string)
• handler - handler function that was removed

Inheriting

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()
• .cascade()

The minified version basic.min.js is quite small (less than 850 bytes / 500 bytes gzipped) 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).