dissemination

dissemination

Lightweight event/command library created to replace Backbone.Radio in projects ported from Backbone/Marionette to React.

Installation

npm install dissemination --save

Usage

• require with Node.js:

  var channel = require('dissemination');
  

• in browser include dist/dissemination.js or dist/dissemination.min.js script:

  var channel = window.dissemination;
  

and then

channel().on('event', function() { console.log('event is fired'); });
channel().fire('event');

Examples

Channel

• get default channel (with application name):

  var c = channel();
  

• get named channel:

  var c = channel('myChannel');
  

Events

• add event listener:

  var listener = function() { console.log('event is fired'); };
  channel().on('event', listener);
  

• remove specific event listener:

  channel().off('event', listener);
  

• remove all event listeners for a given event:

  channel().off('event');
  

• fire event:

  channel().fire('event');
  

• fire event with parameters:

  var listener = function(name, params) {
      console.log(name); // => 'event'
      console.log(params); // => { item: 1 }
  };
  channel().on('event', listener);
  channel().fire('event', { item: 1 });
  

• add event listener with additional options:

  var listener = function(name, params, options) {
      console.log(name); // => 'event'
      console.log(params); // => { item: 1 }
      console.log(options); // => { message: 'hello world' }
  };
  channel().on('event', listener, {
      message: 'hello world'      
  });
  channel().fire('event', { item: 1 });    
  

• interrupt event listeners' execution chain:

  var result = 0;
  var listener1 = function() { result += 1; return false; }
  var listener2 = function() { result += 2; }
  channel().on('event', listener1);
  channel().on('event', listener2);
  channel().fire('event');
  console.log(result); // => 1
  

Commands

• add command handler:

  var handler = function() { console.log('command is handled'); };
  channel().handle('command', handler);
  

• remove specific command handler:

  channel().unhandle('command');
  

• execute command:

  channel().execute('command');
  

• execute command with response result:

  var handler = function() { return 1 };
  channel().handle('command', handler);
  console.log(channel().request('command')); // => 1
  

• add command handler with additional options:

  var positive = function(options) {
      return options.number >= 0;
  };
  channel().handle('positive', positive);
  console.log(channel().request('positive', { number: 2 })); // => true
  console.log(channel().request('positive', { number: -1 })); // => false
  

Mixins

• add EventMixin or/and CommandMixin to any custom object:

  var events = Object.assign({}, channel.EventMixin);
  events.on('event', function({ console.log('event is fired'); }));
  events.fire('event');
  

  var commands = Object.assign({}, channel.CommandMixin);
  commands.handle('command', function({ return 'hello world'; }));
  console.log(commands.request('command')); // => 'hello world'
  

Building

In order to build library run:

npm run build

Testing

Run unit tests:

npm test

In order to run tests with Coveralls locally you have to provide COVERALLS_REPO_TOKEN:

COVERALLS_REPO_TOKEN=<token> npm run test:coverage

Contribution

Before making a pull request, please, be sure that your changes are rebased to dev branch.

License

MIT