dispatchy

A jquery like event emitter/dispatcher that could be mixed with other objects to provide emitting capabilities ala jQuery Style

Install

npm i --save dispatchy

Usage

dispatchy implements the same interface of the jquery events related methods, but for any object.

Example

var dispatchy = require('dispatchy');
 
var myObject = dispatchy.create(); // will return a newly fresh dispatchy instance for your use and pleasure
 
// now you can do
 
myObject.on('some:event', function (e, args) {
  // do something when the event is fired
  console.log('received', args.some);
});
 
later you can
 
myObject.fire('some:event', {
  some: 'data'
});
 
//and you will see in the console
// received data.

API

The main methods are:

• on: add event listeners to the dispatcher instance

  var obj = {};
  var dispatchy = require('dispatchy');
  var extend = require(lodash.merge);
   
  extend(obj, dispatchy);
   
  obj.on('some:event', function(e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.on('some:event another:event', function(e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.on('some:event.namespace1 another:event.namespace2', function (e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.on( {
    'item:action' : function (e, args) {
      console.log('handler called for', e, args);
     },
    'another:action.withNS some:other:here.too': function (e, args) {
      console.log('handler called for', e, args);
    }
  } );

• off: remove event listeners from the dispatcher instance

  var fn = function(e, args) {
        console.log('handler called for ', e, args);
      };
  // registering the listener
  obj.on('some:event', fn);
   
  // removing it
  obj.off('some:event', fn);
   
  // registering the listener
  obj.on('another:event.withNamespace', function (e) {});
   
  // removing it using the namespace. No need to pass the listener
  obj.off('another:event.withNamespace');
   
  // registering the listeners
  obj.on('another:event.withNamespace', function (e) {});
  obj.on('justonemore:event.withNamespace', function (e) {});
   
  // removing all events with the given namespace. handy to remove all events with the same namespace
  obj.off('.withNamespace');

• one: add an event to the dispatcher instance that will be removed after its execution

  var obj = {};
  var dispatchy = require('dispatchy');
  var extend = require(lodash.merge);
   
  extend(obj, dispatchy);
   
  obj.one('some:event', function(e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.one('some:event another:event', function(e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.one('some:event.namespace1 another:event.namespace2', function (e, args) {
    console.log('handler called for ', e, args);
  });
   
  obj.one( {
    'item:action' : function (e, args) {
      console.log('handler called for', e, args);
     },
    'another:action.withNS some:other:here.too': function (e, args) {
      console.log('handler called for', e, args);
    }
  } );

• fire: fires an event, executing all the listeners added to the particular fired event,

  var fn = function(e, args) {
    console.log('handler called for ', e, args);
  };
  // registering the listener
  obj.on('some:event', fn);
   
  // executing it
  obj.fire('some:event');
   
  // registering other listener
  obj.on('some:event.withNamespace', function (e) {});
   
  // this will fire the event with the given namespace if found. won't try to fire some:event.
  obj.fire('some:event.withNamespace');
   
  // execute all events of the given namespace
  obj.fire('.withNamespace');

Other methods: This methods are not like the ones in jQuery but can be used to achieve something like special events on the dispatchers.

• registerEvent: Register an event with a given lifecycle, similar to jQuery Special Events

  var customEventLifeCycle = {
    // executed the first time a listener is added for the given event
    setup: function () {},
    // executed every time an event listener is added
    add: function () {},
    // executed every time an event listener is removed
    remove: function () {},
    // execute when the last listener is about to be removed from the dispatcher
    teardown: function () {}
  };
   
  var dispatchy = require('dispatchy').create();
  dispatchy.registerEvent('app:ready', customLifeCycle);
   

• registerPersistentEvent: For a lack of a better name this method register a special event that once is fired Any listeners added after will be immediately executed. Is like the jQuery ready event.

  var dispatchy = require('dispatchy');
  dispatchy.registerPersistentEvent('app:ready');
   
  dispatchy.fire('app:ready', { some: 'data' }); // no event listeners added yet.. no problem
   
  // later in the code
   
  dispatchy.on('app:ready', function (e, args) {
    // this will be executed immediately, the args passed to the original event 
    // are also passed to this one so in this case the args will be
    // { some: 'data' } 
  });