Event Driven JS

a not so obtrusive and highly optimized attempt to make JavaScript more awesome than ever!

Now in cdnJS

Many thanks to cdnjs for hosting this script. Following an example on how to include it.

<script
  src="//cdnjs.cloudflare.com/ajax/libs/eddy/0.6.3/eddy.dom.js"
>/* eddy.js */</script>

In order to have a fully patched environment for older browser too, we could include these scripts too:

<!--[if IE 8]><script
  src="//cdnjs.cloudflare.com/ajax/libs/ie8/0.2.3/ie8.js"
></script><![endif]-->
<script
  src="//cdnjs.cloudflare.com/ajax/libs/dom4/1.0.1/dom4.js"
>/* DOM4 */</script>
<script
  src="//cdnjs.cloudflare.com/ajax/libs/eddy/0.6.3/eddy.dom.js"
>/* eddy.js */</script>

The eddy.js Philosophy

It does not matter if you code client or server side, we all need the same thing and we keep using this or that library to obtain the same behavior.

I am talking about all de-facto standards API such .on(type, handler), .once(type, handler), .off(type, handler) together with .emit(type, arg1, argN) and .listeners(type) or .trigger(type, detail) to deal with DOM nodes.

eddy.js aim is to harmonize all these API at core level polluting in a non enumerable way the Object.prototype in a smart way that simply works!

This means no worries at all for any for/in loop you might have in there, even in IE.

As summary, this is the philosophy behind this module

eddy.js is a very pragmatic approach, back those days where developers enriched native prototypes to do more with less code ;-)

Compatibility

eddy.js is tested and compatible with the following mobile platforms

• iOS 5, 6, 7+
• Android 2.2+, 3, 4.0, 4.1, 4.2, 4.3+
• Windows Phone 7, 8+
• FirefoxOS 0.X, 1+
• Blackberry 10 (probably older too, haven't tested yet)
• Opera Mini, Opera Mobile, and Opera Mobile Beta
• webOS 2+
• Nokia Asha and Nokia Xpress browser
• UC Browser for Android 2.X or higher

eddy is also compatible with the following desktop browsers

• Chrome, Canary, and Chromium channel
• Safari 5+ and Webkit Nightly
• Internet Explorer 8, 9, 10, 11+
• Firefox, Aurora, and Nightly channel
• Opera

In order to verify your browser too please visit the test page.

Last, but not least, eddy.js has been used and tested in the following server side platforms

• node.js
• rhino

If you clone the repo, just make test for node or be sure you have a stable rhino jar and java -jar /path/to/that/jar/js.jar testrhino.js.

Object.prototype Enriched API

Here a list of methods you can use by default in an eddy.js environment.

Object#on(type, handler[, capture])

Returns the object itself after adding an event handler. This is basically the equivalent of addListener or addEventListener, where duplicated handlers for the same event are not allowed.

var stopWatch = {
  startTime: Date.now()
}.on(
  'change',
  function () {
    // log elapsed time per each change
    console.log(Date.now() - this.startTime);
  }
);

setInterval(function () {
  stopWatch.emit('change');
}, 10);

// or using the boundTo method
// and the extra arguments accepted by setInterval
setInterval(stopWatch.boundTo('emit'), 10, 'change');

The handler can be either a function or an object as it is for DOM methods such addEventListener or removeEventListener. In this case the method handleEvent is invoked with the object itself as context as it is for the native DOM behavior.

The third boolean capture argument is useless with JS objects but might be used in some DOM specific case. By default, capture is false.

Object#once(type, handler[, capture])

Similar to Object#on(type, handler[, capture]), except the event is triggered once and never again unless specified later on.

// on a generic HTML page inside a script tag...
this.once('load', function(e) {
  console.log('page fully loaded');
  // even if triggered manually
  // this event won't fire anymore
  this.fire('load');
  // nothing happened
});

Please read the note about .off before chosing this method.

Object#off(type, handler[, capture])

Returns the object itself after removing an event handler, if present. This is basically the equivalent of removeListener or removeEventListener.

function clearAllEntries() {
  database.clear();
}
window.on('unload', clearAllEntries);
keepEntriesButton.on('click', function () {
  // drop the clear procedure
  window.off('unload', clearAllEntries);
});

Note about .off and .once

Please note that in case .once was used, instead of .on, this method will not remove the listener. Accordingly, if you need to eventually drop later on a listener via .off, use .on and not .once.

Object#trigger(type[, detail])

Triggers / fires all handlers associated to the event type enriching the event with arbitrary detail simulating what CustomEvent does in DOM Level 4 specifications.

This method is more suitable for DOM events or those events based on a single argument parameter/object.

window.onresize = function (e) {
  alert(e.detail); // object {any:'detail'}
};
window.trigger('resize', {any:'detail'});

In the DOM world, it is possible to use directly .trigger(new CustomEvent(type, {cancelable:true, bubbles: true, detail: anyData})).

This method will return false if any listener called event.preventDefault() since by default all triggered events will be cancelable.

Object#emit(type[, arg1][, argN])

This method behaves like node.js one, accepting one or more optional arguments after the type.

var object = {}
  .on('modify', function (key, value) {
    this[key] = value;
  })
  .on('delete', function (key) {
    delete this[key];
  })
;
object.emit('modify', 'key', Math.random());
console.log(object.key); // 0.3245979759376496
object.emit('delete', 'key');
console.log(object.key); // undefined

In the DOM world this method will dispatch an event with specified type and an arguments property for interoperability purpose. Such property will contain optional extra arguments used to .emit(type, a1, aN) in first place.

Object#listeners(type)

This method behaves like node.js one but on DOM object it will always return an empty array-like object.

function handler() {}
var obj = {}.on('event', handler);
var listeners = obj.listeners('event');

console.log(listeners[0] === handler); // true

In the DOM world there's no way to retrieve back nodes and it has never been a real problem but for node.js or generic JS business logic the possibility to understand already added listeners might be handy (I needed this in dblite and I've realized it is a very handy method!)

Object#boundTo(method)

This method creates a single bound version of the generic function or instance method.

var obj = {
  test: function () {
    console.log(this === obj);
  }
};
console.log(
  obj.boundTo('test') === obj.boundTo('test')
); // true
obj.boundTo('test')(); // true

If the argument is a function instead of a string that function is used instead.

function test() {
  console.log(this === obj);
}
var obj = {};
console.log(
  obj.boundTo(test) === obj.boundTo(test)
); // true
obj.boundTo(test)(); // true

Same thing if we pass the method itself as function instead of method name:

var obj = {
  test: function () {
    console.log(this === obj);
  }
};
console.log(
  obj.boundTo(obj.test) === obj.boundTo('test')
); // true

since version 0.5.2

The boundTo method now is able to set, if not already present, a method to a generic object.

var fn = function(){return this};
obj.boundTo('test', fn) === obj.boundTo('test', function(){})
obj.boundTo('test', fn)() === obj
obj.test === fn

This can be very useful for runtime, in scope, function addressing as example for DOM handlers.

Object#expect(type1, ..., typeN)

Prepares upfront the generic object to accept later on when calls so that it's not needed to when with empty listeners anymore but just declare through this method what might be emitted/dispatched/triggered later on.

var myApp = new MyApp().expect(
  'geolocation',
  'filePermission',
  'fullScreen'
);

navigator.geolocation.getCurrentPosition(
  function(info) {
    myApp.emit('geolocation', info);
  }
);

// ... later on ...
myApp
  .when('geolocation', function (info) {
    // map it
  })
  .when('filePermission', function (file) {
    // upload it
  })
  .when('fullScreen', function (err, ok) {
    if (ok) ;// show it!
  })
;

Object#when(type, handler)

This method simply provides a way to retrieve some data the very first time it has been triggered.

Please note this is not an equivalent to Promises/A+, the one implemented in next version of JavaScript, neither when library, this is just meant to simplify few common cases in an Event_ish_ way.

// async, who knows if and when it will happen
// will be asked only once in any case (not a watchPosition)
navigator.geolocation.getCurrentPosition(
  function(info) {
    myApp.emit('geocurrentposition', null, info);
  },
  function(err) {
    myApp.emit('geocurrentposition', err || 'unknown', null);
  }
);


// wait to retrieve initial position
myApp.when('geocurrentposition', function(err, pos) {
  if (err) {
    console.error('' + err);
  } else {
    console.log(pos.coords);
  }
});

// any other object could listen even if resolved
// it wan't ask again for the position

Above example could be extended to database access request or any other classic user operation that should not be asked more than once, decoupling different requests independently.

document.when("ready", callback)

This is a very special case featured directly in core. Inspired by the most famous $(document).ready(callback) behavior, document.when("ready", callback) acts exactly the same way.

If you load eddy.dom.js lazily, this should work in any case even after the DOMContentLoaded and for all supported browsers.

// even if lazily loaded
document.when('ready', function(e){
  console.log('we are ready to go');
});

// later, even loaded asynchronously and without AMD
document.when('ready', initLibrary);

This will ensure that the event will be available whenever a script will ask to listen for the ready event.

Please note that if the document is already ready, this will be fired asynchronously and ASAP but never inline.

DOM Only

In order to make life easier on DOM world too, there are few extra methods on top of regular eddy stuff, including same behavior for XMLHttpRequest.

DOM#data(key[, value])

This method is a normalizer for the dataset magic attributes behavior with one exception: you can simply assign null or undefined to remove the attribute when and if not needed anymore.

var div = document.createElement('div');
div.data('key', 'value');
div.hasAttribute('data-key'); // true
div.data('key'); // 'value'
div.data('key', null);
div.hasAttribute('data-key'); // false

Array.prototype Enriched API

New in version 0.3, all Array.prototype methods but boundTo and listeners have been made smart enough to perform the same call inside each item of the array.

This approach simplifies a very common pattern with collections, specially in the DOM world, so that we can add or remove events to many objects at once.

function $(CSS, parentNode) {
  // @link http://webreflection.blogspot.com/2014/05/134-bytes-for-optimized-and-very-basic.html
  var el = parentNode || document,
      first = CSS.lastIndexOf(':first') === CSS.length - 6,
      query = first ?
        el.querySelector(CSS.slice(0, -6)) :
        el.querySelectorAll(CSS);
  return first ?
    (query ? [query] : []) :
    Array.prototype.slice.call(query);
}

// later on ...
$('ul > li').on('click', doStuff);

The assumption is that collections are commonly used like that.

Which File ?

eddy.js comes in different flavors but it operates on global, native, constructors. This means once you require or include or load eddy.js you need to manually delete polluted prototypes if needed. Anyway, here the list of files you need:

• browser without DOM, for browsers meaning down to IE6 baby, fear not!
• browser with DOM, for browsers meaning IE8, using ie8 file plus all modern mobile and desktop browsers. In order to have an almost fully standard and updated DOM environment, please add dom4 after ie8 as done as example in the test page.
• AMD including DOM, same as eddy.dom.js inside the require AMD logic. Both ie8 and dom4 are strongly suggested here too.
• node.js, meaning node.js and other server side engines since no export is used/needed

You can install eddy.js directly via npm install eddy too and simply use require('eddy'). The version for node should work for Rhino too without problems ;-)

Why Eddy As Name ?

Not only because of the " Event Driven sound check ", the definition I prefer is the following one:

a current or trend, as of opinion or events, running counter to the main current.

but all other definitions are somehow very metaphoric too ;-)

Not Your Meal ?

If you are stuck in late 90s dogmas about JS and forbidden Object.prototype pollution, you can always go for EventTarget mixin and use that with all your classes.

What eddy.js gives you here, is the ability to forget all these problems and use emitters when you need them, if you need them, as easy as that.