dissemination

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

Installation

npm install dissemination --save

Usage

• ES6:

  import dissemination from 'dissemination';

• require with Node.js:

  var dissemination = require('dissemination');

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

  var dissemination = window.dissemination;

and then

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

Examples

Channel

• get default channel (with application name):

  const c = dissemination();

• get named channel:

  const c = dissemination('myChannel');

• create channel directly:

  import { Channel } from 'dissemination';
  const c = new Channel();

Events

• add event listener:

  const listener = () => { console.log('event is fired'); };
  dissemination().on('event', listener);

• remove specific event listener:

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

• remove all event listeners for a given event:

  dissemination().off('event');

• fire event:

  dissemination().fire('event');

• fire event with parameters:

  const listener = params => {
    console.log(params); // => { item: 1 }
  };
  dissemination().on('event', listener);
  dissemination().fire('event', { item: 1 });

• add event listener with additional options:

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

• add event listener that will be executed once:

  let count = 0;
  const listener = () => { count += 1; };
  dissemination().once('event', listener);
  dissemination().fire('event');
  dissemination().fire('event');
  console.log(count); // => 1

• interrupt event listeners' execution chain:

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

• check whether event listeners are registered:

  const listener = () => { console.log('event is fired'); };
  dissemination().on('event', listener);
  console.log(dissemination().listenersRegistered('event')); // => true

Commands

• add command handler:

  const handler = () => { console.log('command is handled'); };
  dissemination().handle('command', handler);

• remove specific command handler:

  dissemination().unhandle('command');

• execute command:

  dissemination().execute('command');

• execute command with response result:

  const handler = () => { return 1 };
  dissemination().handle('command', handler);
  console.log(dissemination().request('command')); // => 1

• add command handler with additional options:

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

• check whether command handler is registered:

  const handler = () => { console.log('command is handled'); };
  dissemination().handle('command', handler);
  console.log(dissemination().handlerRegistered('command')); // => true

Mixins

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

  import { EventMixin } from 'dissemination';
  const events = Object.assign({}, EventMixin);
  events.on('event', () => { console.log('event is fired'); });
  events.fire('event');

  import { CommandMixin } from 'dissemination';
  const commands = Object.assign({}, 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

Run tests with coverage:

npm run test:coverage

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

COVERALLS_REPO_TOKEN=<token> npm run test:coverage

Contributing

Before making a pull request, please, be sure that you are starting from develop branch.

License

MIT