Event Chains

This is a copy of the node EventEmitter API with a few changes:

Async

All events are emitted asynchronously. This means that given the following code:

var obj = new EventEmitter();
obj.on('foo', function(){ console.log('foo'); });
obj.emit('foo');
console.log('bar');

The native EventEmitter will log:

foo
bar

Whereas this library will log:

bar
foo

This is a design decision. Since some handlers can now be forced to be async (see "Event Execution and Cancellation" below), it's appropriate for them all to be async.

Scope

The event listener functions (.addListener, .on, .once) accept an optional 3rd scope argument.

Single Event Emitters

Taking a cue from signals, you can have EventEmitters with "default" events:

var events = new EventEmitter().singleEvent();
events.addListener(function(){

});
events.emit('a', 'b', 'c');

Note that newListener and removeListener still fire, but they only include one argument, the listener function. These become the only events you can manually listen for. Every function drops the event param except when listening for one of these two events.

Event Execution and Cancellation

Events can be stopped by calling this.stop() from within an event, or by returning a promise that gets rejected.

Note that if you return a promise, all future event handlers will get delayed until the promise is resolved. If you return anything other than a promise, the next event handler will get called immediately.

events.addListener(function(animal){
  if (animal === 'spider') {
    this.stop();
  }
});