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(responseObject, 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

responseObject [object, optional]

responseObject is optional and can be used to replace the default values of the responseObject.

The format of the responseObject object is as follows (showing default values):

var responseObject=
{
    status:200,
    entity:null,
    err:null,
    ttl:0,
    stime:0
};

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 responseObject argument is supplied but is not an object
• If the responseObject violates the specification set by options.responseObjectSpec
• If the callback argument is supplied but 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.