EventMachine is a light-weight, deferred execution event emitter.

I needed a event emitter that:

1. works in a browser;
2. is not a resource hog (EventMachine is just 1.4kB minified);
3. has no external dependencies;
4. callbacks be executed in a fresh stack;
5. with a learning curve analogue to that of banana;

EventMachine is pretty similar to a lot of other event emiters out there, with the only major difference being that all event handler calls are wrapped inside a JavaScript setTimeout function call with a timeout value 0.

This forces the event handlers to be placed and executed at the end of the execution stack by 'pausing' JavaScript execution providing time for the rendering threads in the browser to catch up.

I found this to be a major issue while using other event emiter implementations, for example, the one from backbone.

You can look at the demo on how this affects UI rendering in this JSFiddle.

You can read more about the effect this has in this StackOverflow question, especially this answer.

None.

• clone this repository; or
• download the dist/eventmachine.js; or
• bower install eventmachine; or
• npm install eventmachine.

var options = {};
var eventMachine = EventMachine(options);

eventMachine.on('some:demo:event', function (arg1, arg2) {
    console.log(arg1, arg2);
});

eventMachine.emit('some:demo:event', 'arg1 value', 'arg2 value');

These methods are available for a instantiated EventMachine, e.g. for instance after EventMachine(opts) constructor is called.

Adds a listener to the end of the listeners array for the specified event.

Emit an event with given name and optional arguments.

Get a wrapper to forward given call to event handler. This function is pretty neat, as it allows you to do this -

document.getElementById('button')
    .addEventListener('click', eventMachine.forward('some:event'));

or this

$('#button').click(eventMachine.forward('some:event'));

Remove a listener from the listener array for the specified event.

Remove all listeners from the listener array for the specified event.

Returns an array of listeners for the specified event.

Turn deferred execution for handler on or off, for all current and future handlers of given event.

These methods are directly available via EventMachine.{method}.

Extend an object with EventMachine functionality. Wrap works similarly as EventMachine() factory, but instead of giving a new instance of the EventMachine, this method returns the given instance of already existing object with all the functionality of the EventMachine.

var foo = new function () {};

EventMachine.extend(foo);

foo.on('bar', function (arg) {
    console.log(arg);
});

foo.emit('bar', 'value'); // value

Consider this example:

var handler = new function () {};
handler.disableDeferred = true;

em.on('event', handler); // Executes immediately

debug: true/false: print mostly useless debug messages

disableDeferred: disable deferred execution for the entire EventMachine instance.

disableDeferredFor: object with event name as key, and boolean as value: disable deferred execution for indicated events by name.

eventErrorHandler: function (e, eventName, args, eventHandler) do something when invoked event does boo-boo

As you might imagine, wrapping execution in setTimeout takes resources and ... time? No pun intended.

Consider the fallowing benchmark (median office machine) doing ee.emit(x)) with empty callback function X number of times:

The only difference between the two is that execution of the callback is wrapped in setTimout, nothing more. So you should be careful about how many emits you do. For that reason it is possible to disable this either globally for instance of the emitter, for event by name and for each separate handler.

Since v1.1.1 in Firefox, execution of the event handler is delayed by 4ms. This is to compromise with Firefox's 4ms minimum timeout value. This should not be a show-stopper in most cases, however, I am now actively searching how to circumvent this limitation.

Running tests require that you install mocha and chai dev dependencies (see package.json). You can then run the tests using the command npm test.

Licensed under terms and conditions of Apache 2.0 license.