skemer

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

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

validateAdd

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

validateNew

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