#TDPAHCMSResponseObject

##Version Master: v0.4.0-alpha

##Overview A small javascript library which is used in TDPAHCMS to enforce correct structure of the "response object" - the Javascript object which is returned by all queries to the origin server.

This module was written specifically for one of my projects, a CMS written using actionherojs. If you need something similar, you could either fork this repo or borrow the ideas and core lib/module - TDPJSONCurator.

This is currently a commonJS module but hopefully will soon be "properly" built as a more versatile AMD and commonJS module.

TDPAHCMSResponseObject is currently designed to be used in NodeJS, not in the browser although it would probably work in the browser also. Travis is hooked in and testing NodeJS 0.10, 0.11 (older builds of node aren't compatible with some of the test modules but should actually work with this module) - the current/latest Travis build status is shown above.

##Installation Installation is as simple as either a git clone or an npm install. Ensure you have git or npm installed as appropriate and then either:

git clone method:

git clone https://github.com/neilstuartcraig/TDPAHCMSResponseObject.git

or...

npm method:

npm install tdp-ah-cms-response-object

##Dependencies TDPAHCMSResponseObject has one production-level dependency which is another of my modules, TDPJSONCurator. TDPAHCMSResponseObject really just implements TDPJSONCurator with the requisite configuration and defaults for use in my CMS project.

##Usage Since the module is very small, usage is correspondingly simple. There are 4 public functions (plus the constructor):

###Inclusion Currently, this module is a commonJS module so needs a compatible module loader e.g. require() in nodeJS or browserify (etc.):

var TDPAHCMSResponseObject=require("tdp-ah-cms-response-object");

###Initialisation - the constructor

The module is function-scoped so needs to be initialised with the 'new' construct e.g.:

new ResponseObject(options, function(responseObject)
{
    // Your code goes here...
});

The constructor will automatically initialise and return an instance of the module to the callback function. See below for arguments, return and error information.

####Arguments for the constructor

#####options [object, optional] The options object is optional and can be used to replace one or both the default values of the responseObject (responseObjectOpt) or the object specification (responseObjectSpecOpt which controls the permitted object specification - this should be used only in very custom circumstances).

The format of the options object is important, possible child objects are defaultResponseObject and responseObjectSpec (any others will be ignored) and is as follows (showing default values):

var options=
{

    defaultResponseObject:
    {
        status:200,
        entity:null,
        err:null,
        ttl:0,
        stime:0
    },

    responseObjectSpec:
    {
        status:
        {
            allowedTypes:["number"],
            allowedValues:[200,201,202,204,400,401,403,404,500]
        },
        entity:
        {
            allowedTypes:["string","number","object","null","boolean"]
        },
        err:
        {
            allowedTypes:["string","number","object","null","boolean"]
        },
        ttl:
        {
            allowedTypes:["number"]
        },
        stime:
        {
            allowedTypes:["number"]
        }
    }
};

#####callback [function, mandatory] This is the callback function which will be executed when the initialisation completes. This function will receive one argument (responseObject) which will be an instantion of this module which can be used to execute subsequent public functions of this module, for example:

new ResponseObject(function(responseObject)
{
    responseObject.getObject(function(ro)
    {               
        // Your code goes here...
    });
});

####Errors/exceptions The constructor will throw an error under some circumstances:

• If the options argument is not an object
• If the options.defaultResponseObject is supplied but is not an object
• If the options.defaultResponseObject violates the specification set by options.responseObjectSpec
• If the options.responseObjectSpec is supplied but is not an object
• If the options.responseObjectSpec is incorrectly formatted
• If the callback argument is not a function

###get(property, callback) A property getter for the responseObject.

####Arguments get() takes 2 mandatory arguments:

#####property [string, mandatory] A valid (according to responseObjectSpec) property name whose current value will be retrieved from the responseObject.

#####callback [function, mandatory] A mandatory callback function which will receive the retrieved property value as its only argument.

####Errors get() will throw an error under some circumstances:

• If the property argument is not a string
• If an invalid (according to responseObjectSpec) property name is specified
• If the callback supplied is not a function

####Example

new ResponseObject(function(responseObject)
{
    responseObject.get("status", function(val)
    {               
        console.log("val");
        // 200
    });
});

###getObject(callback) An entire object getter for the responseObject.

####Arguments getObject() takes 1 mandatory argument:

#####callback [function, mandatory] A mandatory callback function which will receive the retrieved responseObject as its only argument.

####Errors getObject() will throw an error under some circumstances:

• If the callback supplied is not a function

####Example

new ResponseObject(function(responseObject)
{
    responseObject.getObject(function(ro)
    {               
        console.dir(ro);
        /*
        {
            status:200,
            entity:null,
            err:null,
            ttl:0,
            stime:0
        }
        */
    });
});

###set(property, value, callback) A property setter for the responseObject.

####Arguments set() takes 3 mandatory arguments:

#####property [string, mandatory] A valid (according to responseObjectSpec) property name whose current value will be set on the responseObject.

#####value [mixed, mandatory] The value to set the property of responseObject to.

#####callback [function, mandatory] A mandatory callback function which will receive the entire responseObject (on successful set) or false (on failure) as its only argument.

####Errors set() will throw an error under some circumstances:

• If the property argument is not a string
• If an invalid (according to responseObjectSpec) property name is specified
• If no value is specified
• If an invalid (according to responseObjectSpec) value is specified
• If the callback supplied is not a function

####Example

new ResponseObject(function(responseObject)
{
    responseObject.set("status", 500, function(ro)
    {               
        console.dir(ro);
        /*
        {
            status:500,
            entity:null,
            err:null,
            ttl:0,
            stime:0
        }
        */
    });
});

###setObject(callback) An entire object setter for the responseObject.

####Arguments setObject() takes 2 mandatory arguments:

#####objectToSet [object, mandatory] An object to set which will replace some or all properties of the current responseObject. This must be valid (according to responseObjectSpec).

#####callback [function, mandatory] A mandatory callback function which will receive the entire responseObject as its only argument.

####Errors setObject() will throw an error under some circumstances:

• If objectToSet is not an object
• If objectToSet is invalid (in one or more properies, according to responseObjectSpec)
• If the callback supplied is not a function

####Example

new ResponseObject(function(responseObject)
{
    var otc=
    {
        status:404,
        entity:"",
        err:null,
        ttl:0,
        stime:0
    }
    responseObject.setObject(otc, function(ro)
    {               
        console.dir(ro);
        /*
        {
            status:200,
            entity:null,
            err:null,
            ttl:0,
            stime:0
        }
        */
    });
});

###More examples For more examples of correct (and incorrect) usage, see the tests.

##Tests Tests currently use Mocha and should.js and are run via Travis CI.

##License TDPAHCMSResponseObject is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.