truflux-state-msg v2.1.0

Truflux State Message

To install

npm install --save truflux-state-msg

The truflux message definition is designed to be separate from the actual messaging system to allow you to separate protocol from implementation.This messaging module contains internal mechanisms for managing message state when using truflux.

New in v2.0.0

To provide better decoupling, truflux-state-msg now no longer supports the enforce Schema methods any more, which have been moved to a separate module, truflux-msg-schema. The prebuilt browser versions have removed to allow one to include their own specialized build if need be

Example

The following example is adapted from the stateless truflux-msg protocol definition module.It is suggested that you try out truflux-msg before moving on to using truflux-state-msg

//In your protocol definition file lets call it protocol.js
var TrufluxStateMessage = require('truflux-state-msg'),
    protocol            = new TrufluxStateMessage();

protocol.add('provideUsername')
        .add('providePassword')
        .add('login')
        .add('somethingOnlyOnce');

//login may only be called once the provideUsername and providePassword messages have been called before hand 
protocol.depend('login',['provideUsername','providePassword']);

//Will make sure this message will only be called once, otherwise an error will be emitted
protocol.singleton('somethingOnlyOnce');

module.exports = protocol;

To show you how to deal with protocol errors see the following example

    protocol.onUnimplemented     = function(identifier,socket)
    {
        console.log('Whoops, forgot to specify '+identifier);
    };
    protocol.onMultipleSingleton = function(messageID,socket)
    {
        console.log('Message : '+protocol.getMessageName(messageID)+'has been called more than once');
    }; 
    protocol.onMultipleSingleton = function(messageID,dependancyID,socket)
    {
        console.log('Message : '+protocol.getMessageName(messageID)+'has not had dependancy fulfilled : '+protocol.getMessageName(dependancyID));
    };

API

The preferred method of accessing the integer value of a message is to use msgObjectInstance.id.identifierName , this can be used to obtain values for has and call if needed

Constructor(options)

/**
 * Creates a new TrufluxMessage
 * @param {Object}  [options] 
 * @param {Boolean} [options.noThrow] If true, we will not throw an error for unimplemented functions for "add" 
 */

add(identifier,func)

/**
 * Adds a function handler for the provided string
 * @param  {String} identifier 
 * @param  {Function} [func]  function(data,socket)   
 * @return {TrufluxMessage}    
 */

specify(identifier,func)

/**
 * Specifies the function to be used for the provided identifier. Used to override add
 * @param  {String|Number} identifier 
 * @param  {Function} func function(data,socket)       
 * @return {TrufluxMessage}            
 */

call(id,payload,socket)

/**
 * Calls the handler associated with the message ID. NOTE This will throw an error if there is no 
 * handler associated. It is assumed you have called "has" before hand
 * @param  {Number} id      
 * @param  {Any} payload 
 * @param  {TrufluxSocket} socket
 * @return {TrufluxMessage}   
 */

has(messageID)

/**
 * Checks to see if it has the specified message handler
 * @param  {Number}  messageID 
 * @return {Boolean}       
 */

singleton(identifier)

/**
 * Makes a specified message a singleton
 * @param  {String|Number} identifier 
 * @return {TrufluxMessage}            
 */

depend(dependant,prerequisites)

/**
 * Makes a function depend on previous functions having been called
 * @param  {String|Number} dependant  
 * @param  {String|Array}  prerequisites The string identifiers of the messages that must be called before this
 * @return {TrufluxMessage}            
 */

changeMessageID(oldId,newID)

/**
 * Changes the ID of a message handler. Ideal if you need to make sure that the ID has a certain value 
 * @param  {Number|String} oldId The old identifer of the handler
 * @param  {Number} newID  The new ID value 
 * @throws {Error } If the newID is already taken
 * @return {TrufluxMessage}       
 */

Instance properties

/**
 * Called when a message handler has recieved a message but was unimplemented
 * @property {Function} onUnimplemented 
 */

/**
 * Called when a message handler has recieved a message but has unsatisfied dependancies 
 * @property {Function} onUnsatisfiedDependancy 
 */

/**
 * Called when a message handler has recieved a message and was a singleton, but has been called more than once
 * @property {Function} onMultipleSingleton 
 */