qEvents

v. 0.1.0

Installing

npm install qevents

Description

This very small module might become usefull when you want to: - Have an event-driven environment - Simple message broadcasting

What is it?

An wrapper over NodeJS native events in order to control your application via events.

It has no special requirements or dependencies.

Why use it?

You can avoid callback hell and code redundancy.

A word on coding standards

In order to keep track of events throughout your application, certain standards must be use 1. Creating listener methods 1.1 Should be function expressions in order to remove them when you want 2. Create at the beginning of the module declaration listeners methods and then create listeners. All application listeners should be loaded on applicaiton launch

Usage

1. Simple usage

controller_1.js

var qEvents = require('qevents'),
    Control_1 = {};

//--- Create a private channel for this controller
Control_1.events = new qEvents.instance('C_1Events');

/**
 * Create event listeners
 */

//--- You can create responses first

Control_1.response = {
    action: function _action () {
        console.log('Received', arguments);
    },
    tempAction: function _tempAction () {
        console.log('One time received', arguments)
    }
}

//--- Then add the listener
Control_1.events.listen('ListenAction', Control_1.response.action);

//--- And a listener that will be called once
Control_1.events.listenOnce('ListenTempAction', Control_1.response.tempAction);


//--- Dispatch locally
Control_1.events.dispatch('ListenAction', 'string param', {p2: 'Object param'});
Control_1.events.dispatch('ListenTempAction', 'string param', {p2: 'Object param'});

controller_2.js

var qEvents = require('qevents'),
    Control_2 = {};
    
//--- Dispatch to controller 1 from here
qEvents.remote.dispatch('C_1Events', 'ListenTempAction', 'param1', 'param2'); //---Will not work
qEvents.remote.dispatch('C_1Events', 'ListenAction', 'param1', 'param2'); //---Will work

2. Same listener key

If you don't care which is the order processing you can add more listeners to the same listener key

var qEvents = require('qevents'),
    Control = {};

//--- Create a private channel for this controller
Control.events = new qEvents.instance('CEvents');
    
Control.action_1: function _action () {
    console.log('Received', arguments);
}

Control.action_2: function _action () {
    console.log('Received', arguments);
}

Control.events.listen('ListenAction', Control.action_1);
Control.events.listen('ListenAction', Control.action_2);

//--- Will dispatch to both actions
Control.events.dispatch('ListenAction', 'string param', {p2: 'Object param'});

3. Chaining listeners

Once a listener receives data you can trigger new event with the build in method chainTo

var qEvents = require('qevents'),
    Control = {};

//--- Create a private channel for this controller
Control.events = new qEvents.instance('CEvents');

Control.action_1: function _action1 () {
    console.log('Received', arguments);
    
    //--- Chain locally
    this._chainTo('CEvents', 'chain_1', {param: 'Send this to chain_1 listener'});
}

Control.chain_1: function _chain1 () {
    console.log('Received', arguments);
}

//--- Create listeners
Control.events.listen('ListenAction', Control.action_1);
Control.events.listen('ListenChain', Control.chain_1);

//--- Will dispatch to both actions
Control.events.dispatch('ListenAction', 'string param', {p2: 'Object param'});

Or chain from a remote

var qEvents = require('qevents'),
    Remote = {};
    
Remote.events = new qEvents.instance('RemoteEvents');

Remote.rAction_1 = function _rAction1 () {
    this.__chainTo('CEvents', 'action_1', {rParam: "This is a remote received object"});
};

//--- Define listener
Remote.events.listen('RemoteListen', Remote.rAction_1);

//--- This will fire all the way to Control.chain_1 method
Remote.events.dispatch('rAction_1');

4. Removing listeners

Remove one listener

Control.events.remove('ListenAction', Control.action_1);

Remove all listeners

Control.events.purge('ListenAction');

[NOTE!] Remote events section has no event listener adding or event listener removing for security resons

TODO

Combine channel and header into an object
Improve internal listeners storage