cycle-events

Provides event-based pub/sub to cycle.js applications.

Installation

npm i cycle-events --save

Scripts

NOTE: Make sure you've installed all dependencies using npm install first.

To generate documentation: npm run doc. This will create documentation in the build/docs folder.

To run unit tests: npm test

API

Broker

Kind: global class

• Broker
  • new Broker()
  • instance
    • .on(event, callback) ⇒ function
    • .one(event, callback) ⇒ function
    • .off(event, callback)
    • .removeAllListeners(event)
    • .emit(event, args)
    • "error"
    • "listenerAdded"
    • "listenerRemoved"
  • static
    • .Events : Events
  • inner
    • ~Events : Object

new Broker()

Provides pub/sub functionality to Cycle.js applications.

Example

var broker = require('cycle-events')(); // create instance
var off = broker.on('my-custom-event', // register handler
  function myCallback(arg1, arg2) { ... }
);
broker.emit('my-custom-event', 'arg1', 'arg2'); // fire event
off(); // remove the event handler

Example

// add pub/sub functionality to a class and
// automatically log any errors caused by
// subscribers of the class:
function MyClass() {
  Broker.call(this); // mixin pub/sub
  Rx.Observable.fromEvent(this, 'error')
    .subscribe(logger.error);
}

// now use the class:
var myClass = new MyClass();
myClass.on('some-custom-event', function() {
  methodDoesNotExist(); // error logged automatically
});

broker.on(event, callback) ⇒ function

Registers a listener for the specified event.

Kind: instance method of Broker
Returns: function - A method to invoke to remove the listener from the specified event.
Throws:

• TypeError Parameter event must be a non-empty string.
• TypeError Parameter callback must be a function.

Emits: listenerAdded

| Param | Type | Description | | --- | --- | --- | | event | String | The event to subscribe to. | | callback | function | The listener to invoke when the specified event is emitted. |

Example

// register an event handler:
broker.on('my-custom-event', myEventHandler(arg1, arg2) { ... };
// invoke the event handler (any any others registered):
broker.emit('my-custom-event', 'arg1', 'arg2');

broker.one(event, callback) ⇒ function

Registers a listener for the specified event, but ensures the listener will only be fired at most 1 time. Once a listener has been invoked, it will automatically be removed.

Kind: instance method of Broker
Returns: function - A method to invoke to remove the listener from the specified event.
Throws:

• TypeError Parameter event must be a non-empty string.
• TypeError Parameter callback must be a function.

Emits: listenerAdded

| Param | Type | Description | | --- | --- | --- | | event | String | The event to subscribe to. | | callback | function | The listener to invoke when the specified event is emitted. |

Example

// register a handler to only run once:
broker.one('my-custom-event', myEventHandler(arg1, arg2) { ... };
// the handler will be removed after being invoked:
broker.emit('my-custom-event', 'arg1', 'arg2');

broker.off(event, callback)

Removes the specified listener for the specified event.

Kind: instance method of Broker
Throws:

• TypeError Parameter event must be a non-empty string.
• TypeError Parameter callback must be a function.

Emits: listenerRemoved

| Param | Type | Description | | --- | --- | --- | | event | String | The event whose listener should be removed. | | callback | function | The listener to remove. |

Example

function myHandler() { ... }
broker.on('my-custom-event', myHandler);
broker.off('my-custom-event', myHandler);

broker.removeAllListeners(event)

Removes all listeners registered for the specified event.

Kind: instance method of Broker
Throws:

• TypeError Parameter event must be a non-empty string.
• TypeError Parameter callback must be a function.

Emits: listenerRemoved

| Param | Type | Description | | --- | --- | --- | | event | String | The event whose listeners should all be removed. |

Example

broker.on('custom-event', function myHandler1() { ... });
broker.on('custom-event', function myHandler2() { ... });
broker.emit('custom-event'); // both handlers invoked
broker.removeAllListeners('custom-event');
broker.emit('custom-event'); // no handlers invoked

broker.emit(event, args)

Invokes any listeners for the specified event--in the order they were registered--and passes any provided arguments to those listeners. If a listener throws an exception, the error event will be emitted but subsequent listeners will still be invoked.

Kind: instance method of Broker
Throws:

• TypeError Parameter event must be a non-empty string.

Emits: error

| Param | Type | Description | | --- | --- | --- | | event | String | The event to emit. | | args | * | Any additional arguments to pass to listeners. |

Example

broker.on('my-custom-event', function() { ... });
broker.emit('my-custom-event'); // handler fired

Example

broker.on('log', function(msg, ...args) {
   log.write(msg, args);
});
broker.emit('log', 'Today is %s', new Date());

Example

broker.on('sum', function(...nums) {
   var sum = nums.reduce(function(result, num) {
       return result + num;
   }, 0);
   log.info('The sum of', nums, 'is', sum);
});
broker.emit('add', 1, 2, 3, 4, 5);

"error"

An error occurred in an event listener while firing an event.

Kind: event emitted by Broker
Properties

| Name | Type | Description | | --- | --- | --- | | event | String | The event the listener was registered for. | | callback | function | The listener that caused the error. | | error | Error | The error that occurred while invoking the listener. |

Example

broker.on(Broker.Events.ERROR, function(data) {
  log.error('An error occurred:', data.error);
});

"listenerAdded"

A listener was added. Examine the event properties for details.

Kind: event emitted by Broker
Properties

| Name | Type | Description | | --- | --- | --- | | event | String | The event the listener was registered for. | | callback | function | The listener registered for the event. |

Example

broker.on(Broker.Events.ADDED, function(data) {
  log(data.event); // 'my-custom-event'
  log(data.callback); // function callback() { ... }
});
broker.on('my-custom-event', function callback() { ... });

"listenerRemoved"

A listener was removed. Examine the event properties for details.

Kind: event emitted by Broker
Properties

| Name | Type | Description | | --- | --- | --- | | event | String | The event the listener was removed from. | | callback | function | The listener removed from the event. |

Example

broker.on(Broker.Events.REMOVED, function(data) {
  log(data.event); // 'my-custom-event'
  log(data.callback); // function callback() { ... }
});
var off = broker.on('my-custom-event', function callback() { ... });
off(); // remove the event handler

Broker.Events : Events

An enumeration of event names used internally that external callers can also subscribe to.

Kind: static property of Broker
Example

broker.on(Broker.Events.ADDED, function listenerAdded() { ... });
broker.on(Broker.Events.ERROR, function errorOccurred() { ... });

Broker~Events : Object

Kind: inner typedef of Broker
Properties

| Name | Type | Description | | --- | --- | --- | | ERROR | String | 'error' - An error occurred in an event listener. | | ADDED | String | 'listenerAdded' - An event listener was registered. | | REMOVED | String | 'listenerRemoved' - An event listener was removed. |