skemer 0.8.6



A Javascript variable validation and merge tool.

This library can be used to ensure a variable and any additions to that
variable adhere to a certain schema. The schema can be as simple as allowing
a string value, to as complex as a nested Object.

The library contains the validateNew function for validating
and merging all new data, the validateAdd function for doing
validating and merging new data into existing data, a Skemer
prototype for doing multiple validations / merges against the same schema,
and a buildJsDocs function for creating
a JSDoc comment string from the schema and its doc parameters.

- Uses
- Example
- Skemer API
- buildJsDocs
- Skemer
- validateAdd
- validateNew
- validateAdd
- validateNew
- Schema and Validate Options
- options
- schema
- Skemer Errors
- DataInvalidError
- DataItemsError
- DataRangeError
- DataRequiredError
- DataTypeError
- OptionsError
- SchemaError

Uses

- Validating static data during testing
- Validating dynamic data during runtime

Example

Try on Tonic

``javascript
var skemer = require('skemer');


var schema = {
doc: 'A basic schema',
type: {
value: {
doc: 'Some string value',
type: 'string'
},
figure: {
doc: 'A number value',
type: 'number',
min: 20,
max: 50
}
}
};

var valid = {
value: 'a string',
figure: 30
};

var valid1 = {
figure: 35
};

var valid2 = {
value: 'a different string'
};

var invalid = false;

var stringSchema = {
type: 'string'
};

var aString = 'string';


skemer.validateNew({ schema: stringSchema }, aString);

var Schema, data;

console.log(data = skemer.buildJsDocs(schema, {
wrap: 80,
preLine: ' * ',
lineup: true
}));

Schema = new skemer.Skemer({ schema: schema });

console.log(data = Schema.validateNew(valid));

console.log(data = Schema.validateAdd(data, valid1));

Schema.validateAdd(data, valid2, invalid);

`

Skemer API

buildJsDocs

Build a JSDoc for a variable using the given schema.

Parameters

- schema Object An Object containing a valid
schema
- options Object An Object containing build options
- options.name [string] Name of the object documenting (will be
prepended to any parameter names
- options.type [string] Specify what block tag should be used
for the variables (optional, default 'prop')
- options.tabWidth [number] The width (number of characters) of a
tab (optional, default 8)
- options.preLine [string] String (normally indentation) to include
before each line
- options.lineup [boolean] Whether to line up text in a JSDoc
block (eg @param) with the end of the block command (optional, default true)
- options.wrap [number] Number of characters to wrap the JSDoc lines
at

Returns string A string containing the JSDoc for the given
schema

Skemer

Skemer prototype to enable simple reuse of a schema

Parameters

- options Object An object containing the validation
options, including the schema

$3

Add new data to existing validated data based on the stored schema.
NOTE: Existing data WILL NOT be validated

Parameters

- data Any Existing data to merge new data into.
- newData ...Any Data to validate and merge into the existing data.

Returns Any Validated and merged data

$3

Validate and merge new data based on the stored schema.

Parameters

- newData ...Any Data to validate, merge and return. If no data is
given, a variable containing any default values, if configured,
will be returned.

Returns Any Validated and merged data

validateAdd

Validata and add new data to existing validated data based on the given
schema. NOTE: Existing data WILL NOT be validated

Parameters

- options Object An object containing the validation
options, including the schema
- data Any Data to validate and return. If no data is given,
data containing any default values will be returned. If newData
is given, newData will be validated and merged into data.
- newData ...Any Data to validate and merge into data

Returns Any Validated and merged data

validateNew

Validate and merge new data based on the given schema.

Parameters

- options Object An object containing the validation
options, including the schema
- newData ...Any Data to validate, merge and return

Returns Any Validated and merged data




Schema and Validate Options

options

Options Object that must be passed to the one-off
validate functions and
on creating an instance of a Skemer

Parameters

- schema schema schema to use for the validation
- baseSchema [schema] schema to be used for recursive
schemas. If none given, the given, the full schema given in
schema will be used
- replace [boolean or Array<boolean>] A boolean to specify whether to
globally replace all existing values for arrays and objects, or an
object of string/boolean key/value pairs used to specify what
variables(their name given as the key) should have their value
replaced by default (a boolean value of true)

schema

Schema Object detailing the schema to be used for validating and merging
data.

Parameters

- doc [string] A String giving information on the value expected
- docType [string] A string containing the type of the value
expected that will be used instead of calculating the type of value
expected
- noDocDig [boolean] If set and the value expected is an object,
buildJsDoc will not document the parameters of the object
- type [string or or Array<schema>] The value type of the parameter
expected
- types [Array<schema>] An Array or Object of schema containing
different schemas of the values expected
- values [Array<Any>] Specifies the possible values for strings, numbers
and dates
- multiple [boolean] Whether or not multiple values (stored in an
Array, or if object is set totrue an Object) are allowed. Can be
a boolean, a number (the number of values that the value expected
must have), or an array containing the minimum number of values and,
optionally, the maximum number of values.
- object [boolean] If multiple is true and object is true, the
multiple values will be stored in an object. If multiple is true and
object is false, any keys will be ignored and the values will be
stored in an array
- regex [RegExp] A regular expression to validate a String value
- min [number or date] The minimum number, string length or number of
Array elements required
- max [number or date] The maximum number, string length or number of
Array elements allowed
- replace [boolean] Whether a new value should completely replace an
old value when the value expected is either an array or an object
- required [boolean or Function or number or Array<number>] Either true/false or
a function returning true/false whether the parameter is required,
or if the variable is a multiple stored in an array an number given
the number of required elements, or an array of numbers, the first
being the minimum number of elements and the second being the
maximum number of elements (a maximum is not required)
- default [Any] Default value to use if no value is given

Skemer Errors

The Skemer module will throw the following Errors if any errors in the Schema
or the variables are found

DataInvalidError

Thrown if the parameter value is not valid

Parameters

- message string Error message
- extra Any Extra information

DataItemsError

Thrown if the parameter value is out of the given range

Parameters

- message string Error message
- extra Any Extra information

DataRangeError

Thrown if the parameter value is out of the given range

Parameters

- message string Error message
- extra Any Extra information

DataRequiredError

Thrown if a parameter is required, but was not given

Parameters

- message string Error message
- extra Any Extra information

DataTypeError

Thrown if the type of value for a parameter in the schema is incorrect,

Parameters

- message string Error message
- extra Any Extra information

OptionsError

Thrown if the parameter value is out of the given range

Parameters

- message string Error message
- extra Any Extra information

SchemaError

Thrown if the parameter value is out of the given range

Parameters

- message string Error message
- extra Any Extra information