event-actions

EventActions

Application level event and action emitter. Used to connect different components to each other by using common emitter for events and actions. EventActions support namespacing which makes it easy to separate components, and use same listeners and emitter in different namespaces.

Events are used for notify listeners when something happens.

Actions are used to trigger things in other components.

Install

npm install event-actions

Example usage

var EventActions = require('event-actions');

// create EventActions instance
var root = new EventActions();
// create namespaced instance from 'root'
var child = root.createNamespace('child');

// add action listener for root namespaces 'action'
root.onAction(':action', function() {
    console.log('Root action');
});
// add action listener for 'child:action'
child.onAction(':action', function() {
    console.log('Child action');
});
// same as: child.onAction('child:action', ...

// namespaced EventEmitters can listen for any other namespace
// add action listener in child for roots 'action'
child.onAction('action', function() {
    console.log('Root action in child');
});

// add listener for all actions that are emitted
root.on('action', function(target, action, args) {
    // target: namespace action was target to
    // action: name of the action
    // args: arguments passed to action
});

// emit 'action' in the root namespace
root.emitAction('action');
// or
child.emitAction('action');

// emit 'action' in the child namespace
child.emitAction(':action');
// or
root.emitAction('child:action');
// or
child.emitAction('child:action');


// same rules apply also for events, just replace word 'action' with 'event'..

See example.js for more complete usage example.

Namespacing

Namespacing actions and events is crusial, expecially when number of connected components grows.

Either absolute or relative namespaces can be used when adding listeners or emitting events. Relative namespace starts with : and will be prepend with EventActions instances namespace.

In example if EventActions namespace is root:child, then emitting :action will actually trigger listeners registered for root:child:action. Same goes for registering listeners. Adding listener for :action on EventActions that has namespace root:child, it will listen for events root:child:action.

Events

action

• target Target namespace of the action
• action Name of the action
• args Arguments passed with action

Emitted when action is emitted from any emitter that share same root emitter.

event

• target Target namespace of the event
• event Name of the event
• args Arguments passed with event

EventEmitters

EventActions instance has two EventEmitter, actions and events. They can be used as normal EventEmitter.

Methods

createNamespace

• ns Namespace

Create namespaced version of EventActions instance. Namespaced instances share emitters with root. Namespace is appended to relative action/event names.

parent

Returns parent EventActions instance or null if root.

root

Returns root EventActions instance.

onAction / onEvent

• name Action/event name, absolute or relative
• listener Action/event listener

Add listener for action/event.

emitAction / emitEvent

• name Action/event name, absolute or relative
• arguments ...

Triggers action/event listener with given name.

removeAction / removeEvent

• name Action/event name, absolute or relative
• listener Action/event listener to remove (optional)

Remove all or specific listener with given name.

onceAction / onceEvent

• name Action/event name, absolute or relative
• listener Action/event listener

Listen for action/event. Listener is removed after triggering.

pipeToAction / pipeToEvent

• emitter Emitter to listen, any EventEmitter
• event Event to listen for
• toName Bind to name

Binds any EventEmitter event to specified action or event. Enables action/event piping:

pipeEventToEvent / 'pipeEventToAction' / 'pipeActionToAction' / 'pipeActionToEvent'

• from event/action to pipe from
• to event/action to pipe to

Pipes the given event/action to other event/action in same EventActions object.

Example of piping:

var emitter = new EventEmitter();
var A = new EventActions();
var B = new EventActions();

// pipe emitter 'remove' event to A 'emitter:remove' action
A.pipeToAction(emitter, 'remove', 'emitter:remove');

// pipe emitter 'removed' event to B 'emitter:changed' event
B.pipeToEvent(emitter, 'changed', 'emitter:changed');

// pipe B event to other B event
B.pipeEventToEvent(':first', 'second');

// pipe B event to B action
B.pipeEventToAction(':first', 'third');

// NOTE: while piping things between two different EventActions object
// 'events' and 'actions' properties have to be used as normal EventEmitters

// when 'click' action is emitted from A, it is piped to B action 'child:action'
B.bindAction(A.actions, 'click', 'child:action');

// when 'player:paused' event is emitted from B, it is piped to A action 'controls:update'
A.bindAction(B.events, 'player:paused', 'controls:update');