Have ideas to improve npm?Join in the discussion! »

    dispatchy

    1.0.3 • Public • Published

    NPM Version Build Status

    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' } 
      });

    Install

    npm i dispatchy

    DownloadsWeekly Downloads

    471

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • avatar