event-wire

Mediator with dynamic responsibility chains.

Idea if this package is to have hybrid of EventEmitter and chain-of-Responsibility. In short - dynamic channels with wildcards, and guaranteed execution order for listeners.

Features:

sync, async, promise-based & generator listeners
wildards
exclusions

Install

npm install event-wire --save

API

constructor

Create new event-wire instanse.

//
// Simple. Recommended.
//
var wire = require('event-wire')();


//
// Advanced, with enabled support for generators.
//
const wire = require('event-wire')({
  co: require('co')
})


//
// Advanced, with alternate promise/coroutine lib
//
const bb   = require('bluebird');
const wire = require('event-wire')({
  p: bb,
  co: (fn, params) => bb.coroutine(fn)(params)
});

.emit(channel [, obj, callback])

Sends message with obj param into the channel. Once all sync and ascync handlers finished, optional callback(err) (if specified) fired.

If callback not passed, Promise is returned.

.on(channels [, options], handler)

Registers handler to be executed upon messages in the a single channel or a sequence of channels stored in channels parameter. Handler can be either sync, async or generator function:

wire.on('foobar', function* (obj) {
  // do stuff here
  yield ...
});

wire.on('foobar', function (/* obj */) {
  return new Promise(resolve => { // You can return Promise
    setTimeout(() => { resolve(); }, 1000);
  });
});

wire.on('foobar', function (obj) {
  // do stuff here

  // and you can generate error via throw
  throw new Error('test');
});

wire.on('foobar', function (obj, callback) {
  // do stuff here
  callback();
});

If handler returns error, chain will be terminated - all next handlers except "ensured" (see below) will be skipped.

options:

priority (Number, Default: 0) - execution order (lower is earlier). Handlers with equal priorities are executed in definition order.
ensure (Boolean, Default: false) - If true, will run handler even if one of previous fired error.

parallel (Boolean, Default: false) - all adjacent handlers with the same priority that also have parallel=true will be executed in parallel.

For example:

wire.on('foobar', { priority: 9, parallel: true }, handler1); // different priority
wire.on('foobar', { priority: 10, parallel: true }, handler2); // handler2 and handler3 are parallel
wire.on('foobar', { priority: 10, parallel: true }, handler3); // handler2 and handler3 are parallel
wire.on('foobar', { priority: 10 }, handler4); // not parallel
wire.on('foobar', { priority: 10, parallel: true }, handler5); // handler5 and handler6 are parallel
wire.on('foobar', { priority: 10, parallel: true }, handler6); // handler5 and handler6 are parallel
wire.on('foobar', { priority: 11, parallel: true }, handler7); // different priority

name (String) - handler name, if function is anonymous or you need to keept it intact after code uglifiers.

.once(...)

The same as .on(...), but executed only one time.

.before(...), .after(...)

Aliases of .on(...), but with priority -10 and +10

.off(channel [, handler])

Removes handler of a channel, or removes ALL handlers of a channel if handler is not given.

.skip(channel, skipList)

Exclude calling list of named handlers for given channel (wildard allowed at the end):

wire.skip('server:static.*', [
  session_start,
  cookies_start
]);

.has(channel) -> Boolean

Returns if channel (String) has at least one subscriber with zero priority (main handler). Useful for dynamic routing

.stat() -> Array

Returns array of info about every channel. For debug purposes. For example, you can write dumper to check that all expected channels have required handlers. Or to track number of calls.

.hook(eventName, fn)

Internal messaging for debug. Currently supported events:

eachBefore (handlerInfo, params) - called before every handler execute.
eachAfter (handlerInfo, params) - called after every handler execute.

License

MIT

nodeca/event-wire