cycle-events

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.