emitters

emitters

Fancy node-compatible event emitters, including bubbling and singleton ready events.

var emitters = require('emitters');

// Polyfill for a node-compatible EventEmitter.
var ee = new emitters.EventEmitter();

var count = 0
,   counter = function (evt){
        console.log("Count: "+(count++)+" because "+this+" fired "+evt);
    };

// An emitter that auto-invokes listeners if the "ready" event has already occurred.
var re = new emitters.ReadyEmitter();
re.on('ready', counter);

// Fires the ready event unless already ready.
re.ready(true); // -> count == 1

// Invokes our callback because we're already ready.
re.on('ready', counter); // -> count == 2

// Or...
re.ready(counter); // -> count == 3

// A ChainedEmitter bubbles events to its parent.
var c1 = new emitters.ChainedEmitter(ee)
,   c2 = new emitters.ChainedEmitter(c1)
,   c3 = new emitters.ChainedEmitter()
;

// You can also get/set the parent emitter later.
c3.parentEmitter(c1);

// So we're bubbling from c2 -> c1, c3 -> c1, and c1 -> ee; let's listen in.
ee.on('bonk', counter);
c1.on('bonk', counter);
c2.on('bonk', counter);
c3.on('bonk', counter);

c2.emit('bonk'); // -> We see c2, c1, and ee all recieve events, putting our counter to 6.

// Event handlers can stop propagaion by returning false.
c1.on('bonk', function (){
    console.log('STOP!');
    return false;
});

c3.emit('bonk'); // -> c3 and c1 both have listeners who will get the event...
// But the second listener we just registered will end the bubbling. (Even if the 
// listener were first, the rest of c1's listeners would be notified. Stopping 
// propagation prevents the event from moving *up*.)

Usage

For usage in node.js, install it via npm: npm install emitters.

A browser distribution is coming soon!

API

Coming soon — use the source, Luke!

Feedback

Find a bug or want to contribute? Open a ticket (or fork the source!) on github. You're also welcome to send me email at [e-mail].

License

emitters was written by David Schoonover (in Coco, a dialect of CoffeeScript that compiles down to JavaScript). It is open-source software and freely available under the MIT License.