#TDPJSONCurator

##Version Master: v0.5.4-alpha

##Overview A small javascript library which curates/maintains a JSON object to a defined structure/format (i.e. it will not allow setting of parameters whose type or value specification does not match the defined spec).

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

TDPJSONCurator 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/TDPJSONCurator.git

or...

npm method:

npm install tdp-json-curator

##Usage Since the module is very small, usage is correspondingly simple. There are 3 public functions:

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

var TDPJSONCurator=require("tdp-json-curator");

###Initialisation - the constructor

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

var curator=new TDPJSONCurator([objectToCurateOpt, JSONObjectSpecOpt, true, callback]);

If objectToCurateOpt and JSONObjectSpecOpt are provided as arguments, the constructor will automatically run a curate() on them. See below for argument, return and error information.

###curate(objectToCurateOpt, JSONObjectSpecOpt, failOnError, callback) curate() is the critical method in this library which curates/maintains a JSON object to a defined structure/format (i.e. it will not allow setting of parameters whose type or value specification does not match the defined spec).

####Arguments curate() takes four mandatory arguments:

#####objectToCurateOpt [object, mandatory] This must be a valid (non-null) javascript object and is the object you want to curate/manage according to JSONObjectSpecOpt.

#####JSONObjectSpecOpt [object, mandatory] This must be a valid (non-null) javascript object and is the specification (criteria) that the properties of the objectToCurateOpt must meet (see below).

#####failOnError [boolean, mandatory] A boolean parameter (which defaults to false if incorrectly specified via the !! operator) that determines whether the entire curate() operation should fail (and thus throw an error) if one or more set() operations on objectToCurateOpt fails e.g. due to the parameter not being present in JSONObjectSpecOpt or the value specified to be set() is disallowed due to either its type or value.

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

####Returns curate() will return the whole curated object on success (i.e. if the objectToCurateOpt satisfies the specifiers in JSONObjectSpecOpt).

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

• If a required argument is missing
• If the current objectToCurateOpt or JSONObjectSpecOpt are not objects
• If objectToCurateOpt does not satisfy JSONObjectSpecOpt and failOnError is true
• If a callback is supplied which is not a function

###get(propertyName, callback) As you'd expect, get() is the property getter method for the curated objectToCurate.

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

#####propertyName [mixed, mandatory] The property name (from the curated object) to get(). If a valid (string) property name is specified, it will be returned. If a non-string or empty string is specified, the whole object will be returned - see the example below.

#####callback [function, mandatory] A callback function which will be executed and will receive the returned value as its only argument.

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

• If a callback is supplied which is not a function
• If a (defined, non-null) propertyName is specified which is not a property of the curated object

####Example

var prop=curator.get("status", function(ret)
{
	console.log(ret);
	// 200
});

var obj=curator.get(null, function(ret)
{
	console.log(ret);
	/*
	{
		status:200,
		entity:null,
		err:null,
		ttl:0,
		stime:0
	}
	*/
});

###set(propertyName, value, callback) Again, as you'd expect, set() is the (property/object) setter for the curated objectToCurate.

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

#####propertyName [string, mandatory] If a string is specified, this must be the property name to set() on the curated object. This property must exist in the JSONSpecObject otherwise an error will be thrown, see below.

#####value [mixed, mandatory] The value to which the specified propertyName on the curated object should be set. This must conform to the allowedValues and allowedTypes in JSONSpecObject.

#####callback [function, mandatory] A callback function will will be executed and will receive the returned value as its only argument.

####Returns set() runs the value past the JSONObjectSpecOpt before setting and will always return the whole curated object for a successful set() or false otherwise (unless there is an error, see below).

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

• If a callback is supplied which is not a function
• If the current objectToCurate or JSONObjectSpec are not objects
• If the propertyName property does not exist in the JSONObjectSpec (i.e. it is not a valid property)
• If the propertyName supplied with the call is not a string or is null (V8 currently calculates typeof(null) as 'object' for historical reasons)
• If a string is specified for propertyName and value is undefined

##Full example A simple, full example (adapted from the tests included):

var TDPJSONCurator=require("tdp-json-curator");

var objectToCurate=
{
	num:100,
	str:"Some string",
	obj:
	{
		a:"b"
	},
	bool:true,
	mixed:"blah blah"
};

var JSONObjectSpec=
{
	num:
	{
		allowedTypes:["number"],
		allowedValues:[1,100,1000,10000]
	},
	str:
	{
		allowedTypes:["string"]
	},
	obj:
	{
		allowedTypes:["object"]
	},
	bool:
	{
		allowedTypes:["boolean"]
	},
	mixed:
	{
		
	}
};

// Async constructor:
new TDPJSONCurator(objectToCurate, JSONObjectSpec, true, function(ret)
{
	console.log(ret);
	/*
	{ 
		num: 100,
		str: 'Some string',
		obj: { a: 'b' },
		bool: true,
		mixed: 'blah blah' 
	}
	*/
});

// Sync constructor:
var curator=new TDPJSONCurator();

curator.curate(objectToCurate, JSONObjectSpec, true, function(ret)
{
	console.log(ret);
	/*
	{ 
		num: 100,
		str: 'Some string',
		obj: { a: 'b' },
		bool: true,
		mixed: 'blah blah' 
	}
	*/
});

##JSONObjectSpecOpt format JSONObjectSpecOpt is an object which defines the criteria by which the objectToCurate will be curated - i.e. what variable type each property of the object must be and/or which values are valid.

The structure of JSONObjectSpecOpt must match the required structure of objectToCurate i.e. each property of objectToCurate must be present in JSONObjectSpecOpt.

Each property of JSONObjectSpecOpt must be an object containing one or more specifiers, currently the only supported specifiers are:

• allowedType (array)
• allowedValues (array)

An important note is that multiple specifiers are and'ed together - i.e. both specifiers must be satisfied.

By way of an example, supposing we have a objectToCurate like this:

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

We might have a JSONObjectSpecOpt which looks like this:

{
	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"]
	}
}

The above should be pretty self-explanatory.

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

##Roadmap In no particular order, the features currently on the roadmap are:

• Write more/better tests
• Allow a wildcard in allowedTypes for all types (to allow e.g.: allowedTypes:["*"], disallowedTypes:["number"])
• Recurcivity (allowing objectToCurate's which have >1 dimension)
• Required attribute (bool) to ensure the (correct type) value is present in the object to be curated
• Min and max values in JSONObjectSpecOpt
• Ranges of values in JSONObjectSpecOpt
• Case (in)sensitivity in string allowedValues
• Negation of allowedValues, allowedTypes etc. as per above few points
• Support for more complex variable types in JSONObjectSpecOpt e.g. integer, float, array (these are not supported by the current nodeJS/V8 typeof() so will need to use something else, assert is a possibility)

##License TDPJSONCurator 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.