emitr
A simple emitter for node and the browser.
The rendered form of this document includes the Emitter script so you can open a console and try it immediately.
My two main inspirations in making this implementation were the events in backbone, and the EventEmitter in node.
If we hadn't required the ability to pass 'context' into on
and off
, we probably would have gone with
LucidJS. Not leaking memory is difficult enough when
building large applications; forcing people to keep extra objects around just so they can clean up after
themselves is ugly enough that it discourages people from doing something important.
While I haven't come across this exact combination of focussed microlibrary combined with context, the only unusual feature of this Emitter (and deliberately so) is that it allows you to listen to and dispatch objects rather than just strings. Related to this is type based events, which I describe later.
Getting It
In node
$ npm install emitr --save
To get the source (you'll want to npm install it afterwards)
$ git clone https://github.com/BladeRunnerJS/emitr.git
With Bower
$ bower install emitr
In the browser (better to take a copy of the file and serve it from within your app)
<script type="text/javascript" src="http://bladerunnerjs.github.io/emitr/dist/emitr.js"></script>
With require.js (again, better to take a copy and serve it within your app)
require(["http://bladerunnerjs.github.io/emitr/dist/emitr.js"], function(emitr) {
// do your thing with emitr
});
Making an Emitter
While you can directly create a new Emitter (with new emitr()
, or use standard prototypical
inheritance to inherit from it, usually you will want to mix the Emitter
methods in to your own classes or objects.
{}; emitr; var emitter = ;
Standard Emitter Features
The big three methods are provided:
on:
// Basic example: emitter; // Example using context: {} MyObjectprototype { // in this example, 'this' is set to 'obj'. }; var obj = ; emitter;
The poorly (but commonly) named off:
// clears all listeners registered on emitter. emitter; // clears all listeners for 'some-event'. emitter; // removes the listener added with // emitter.on('some-event', callback); emitter; // removes the listener added with // emitter.on('some-event', callback, context); emitter; // removes all listeners registered with a context of context. emitter; // or emitter;
trigger (sometimes called emit or fire or notify):
// All listeners registered for the 'end-of-the-world' event // will get called with alienSpacecraft as their first argument. emitters;
once is another function that is commonly provided by Emitters:
// Once behaves similarly to .on, but the listener is only // ever called once. emitter; emitter; emitter;
Extra Features
This Emitter provides two extra features.
MetaEvents
The emitter will also trigger special events that you can listen to in certain
circumstances. The event emitter in node does a similar thing, firing newListener
and removeListener
events at the appropriate time.
There are three meta events which are:
emitr.meta.AddListenerEvent
, triggered when a listener is added.emitr.meta.RemoveListenerEvent
, triggered when a listener is removed.emitr.meta.DeadEvent
, triggered when an event is fired but no listeners receive it.
// In this example, I use an AddListenerEvent metaevent to // create 'sticky' events behaviour for the ready event. { thisisReady = false; this; } Emitter; Documentprototype { thisisReady = true; this; }; var doc = ; doc; // Even though makeReady was called before this 'on', // the listener will still be called. doc;
Type Based Events
The Events themselves in normal usage are usually string identifiers and then a list of arguments, almost like an algebraic data type - a tag and then a tuple of data items. In an object language like javascript, it seems more natural to dispatch event objects instead and listen for them based on their type.
{ thisx = x; thisy = y; } emitter; emitter;
It obeys the Liskov Substitution Principle, so a listener will also get notified of events that are subclasses of the event type it is registered for.
{ MouseEvent; thisbutton = button; } ClickEventprototype = Object; emitter; emitter;