MORX. A simple util for validation and parameter transformation

How to use

$3

npm install morx

$3

``
var morx = require('morx');
var spec = morx.spec() //Begin spec-ing parameters
.build('id', 'required:true, map:user_id')
.build('username', 'required:true')
.end(); //End parameter spec-ing

//Call validation
var validated = morx.validate({id:23, username:'demio9009'}, spec);
console.log(validated);
/*
{
no_errors:true,
error_messages:"",
params:{
'user_id':23,
'username':'demio9009'
},
excluded_params:{},
failed_params:[]
}
*/
`

$3


`
var morx = require('morx');
var spec = morx.spec() //Begin spec-ing parameters
.build('id', 'required:true, validators:isInt, map:user_id')
.build('username', 'required:true, validators:isAlphanumeric.isAscii, filters:toUpper')
.end(); //End parameter spec-ing

//Call validation
var validated = morx.validate({id:23, username:'demio9009'}, spec);
console.log(validated);
/*
{
no_errors:true,
error_messages:"",
params:{
'user_id':23,
'username':'DEMIO9009'
},
failed_params:[]
}
*/
`

$3


`
spec = {
'paramTovalidate':ValidationExtractionAndTransformationRules
}
`
paramToValidate - The key / name of the parameter to apply the ObjectValidationRequirements to. E.g. id , username e.t.c. If you passing an array as your Parameter source, valid values for paramToValidate include 0,1 e.t.c.

ValidationExtractionAndTransformationRules - Key/value pair of a list of rules to use for validating, extracting and transforming paramToValidate as found in the parameter source. It has the following properties:

* required : (boolean True or False) indicates whether or not paramToValidate is required. Internally morx checks to see if paramToValidate is undefined or ""
* map : If present, indicates the key paramToValidate should be returned with. Without map, id will be returned as id. With map (map:user_id), id will be returned as user_id (see example under basic usage)
* validators: A dot separated list of validators to apply to paramToValidate. Internally, morx uses the validator package on npm to validate parameter values. A list of supported validators can be found here.
* filters : A dot separated list of filters / sanitizers to apply to paramToValidate. All filters with the exception of toUpper and toLower are the same as those provided by the validator package. A list can be found here.
* not_param : A boolean value indicated wether the paramToValidate should be returned as part of the extracted params. Useful for cases when a parm is required but not needed for functional operations.

Parameter specs can be created either using object literals or morx's inbuilt spec-er:
`
var paramSpec = morx.spec() //Begin spec-ing parameters
.build('id', 'required:true, map:user_id')
.build('username', 'required:true')
.end(); //End parameter spec-ing
/*
paramSpec is the same as the object literal:
{
id:{
required:true,
map:'user_id'
},
username:{
required:true,
}
}
*/
`

$3

The morx validator takes three arguments, the first two are required.
var validated = morx.validate(ParameterSource, ParameterSpec, validationOptions)

* ParameterSource - The object / array source to validate the ParameterSpec against i.e The parameters defined in the spec will be looked up in the parameter source. In a function, the arguments array-like object is a valid parameter source. In a web app / api, the req.body, req.params, req.query objects are all valid parameter sources. (When using arguments, an interesting usecase could be to use the map spec property to transform arguments passed to a function into an object)
* ParameterSpec - The spec definition with which to validate and extract values from the parameter source. See specing with morx for a more detailed explanation. The spec also precludes needless parameters from filtering into your apps. In cases of APIs / web projects where req.body / req.query could contain a number of properties, spec-ing ensures only what's needed by a function / service / endpoint is extracted
* ValidationOptions - The options that define the way morx handles validation success or faliure. By default, morx will not fail until all parameters defined in the spec requirements have been checked - even if one of the requirements of a spec is not met. It will return all failed params as well as error messages. With ValidationOptions we can fine-tune this behavior. There are three main properties:
* fail_on_first_error - If this is set to true, morx will fail (i.e return to the calling function) at the first occurence of a validation error
* throw_error - If this is set to true, instead of returning a well formed object, morx will throw an error with the validation error messages
* throw_error_on_first_fail - Similar to fail_on_first_error but instead of returning, an error with the validation error message is thrown.

$3

To use morx with morx-cha, the additional spec properties are required

* eg - Example value for the parameter
* eg_specialcase` - Example special case value for the parameter, e.g. eg_invalid_email or eg_exists e.t.c. _This is yet to be implemented_

See example here