dispatchy

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

Usage no npm install needed!

<script type="module">
  import dispatchy from 'https://cdn.skypack.dev/dispatchy';
</script>

README

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