expectation

Define rules by which a single parameter can be validated and revised to contain the desired value. Has built-in checks to remove common undesirable values, check value type, etc and hooks where additional methods can easily be added to further clean up values.

options

Options is an object which defines properties that will define how an expectation will behave. These properties may also be set on Expectation to define your own default values.

name

Defines what it is known by. Useful when assigning the resulting values to objects, maps, etc.

Default: '[Expectation]'

acceptEmpty

Should empty collections (strings, arrays, maps, sets, buffers) be allowed. In addition to these well known collection types any iterator object with a length or size property will be considered a colection.

Default: undefined

acceptErrors

Should error values be allowed. If undefined and either the defaultValue or requiredType is an error then will be true.

Default: undefined

acceptFunctions

Should function values be allowed. If undefined and either the defaultValue or requiredType is a function then will be true.

Default: undefined

acceptMultiples

Should arrays of values be allowed.

Default: undefined

acceptNaN

Should NaN be allowed.

Default: undefined

acceptNull

Should null be allowed.

Default: undefined

acceptSymbols

Should symbol values be allowed. If undefined and either the defaultValue or requiredType is a symbol then will be true.

Default: undefined

defaultValue

Value that will be returned if given value fails to meet any of the criteria.

Default: undefined

preferMultiples

Should the return value be an array whenever possible? Only considered if acceptMultiples is true.

If true, will push any indidivual values into an array. If acceptEmpty is true will return an empty array instead of the default value.

If false, empty arrays will instead return the default value and arrays with a single member will return just that indidivual.

If undefined, doesn't do anything.

Default: undefined

required

If true and given value fails to meet any of the criteria then will throw an error instead of returning a default value.

Default: undefined

requiredType

A class/prototype function or a string to compare the values type against.

If a function then will check if value is an instanceof that function.

If a string then will check if typeof value equals string.

If typeof doesn't match then will attemp to convert the value using a matching implicit conversion function.

If undefined then any value is fine.

Default: undefined

revisor

A function ( value, expectation ) => value that gets a copy of the working value after the build-in methods have had their turn evaluating and revising it but before the default value is applied. Whatever value returned from this function will then be checked and the default value applied if needed or error thrown.

Default: undefined

implicitConverters

An object with implicit conversion functions ( value ) => value as members. If an implicit conversion operation is being done then the string name of the required type will be used to lookup a matching function. If that function exists then it will be passed the value and whatever value it returns will be the new working value.

If a matching function isn't found on the instance then it will also be looked for in Expectation.implicitConverters.

Default: undefined

static members

Expectation.create(options) => expectation

Create a new expectation instance with the given options object to set the criteria. Returns the new expectation.

Alternatively, options can be either: a two element array with default name and value, or a string to use as the default name.

Expectation.createList([options1,options2,..optionsN]) => [expectation1,expectation2,..expectationN]

Create an array of expectations from option objects passed as criteria.

instance members

name

The expectation's name. Where appropiate this value should be used in naming revised values.

revise(value) => value

Validates and revises a value against an expectation's criteria. Returns the revised value.

initialize() => value

Produces an initial value based on the expectation's criteria. Ignores the required rule that otherwise might throw an error.

included implicit convertors

string

If it's null, NaN, or undefined return undefined. Otherwise return a string.

uppercase

Same as string but returns in locale uppercase.

lowercase

Same as string but returns in locale lowercase.

json

If it's undefined return undefined. Otherwise return as JSON.

date

If it's a Date or can be parsed into a Date from a string or number then return as a Date. Otherwise return undefined.

datestring

Same as date but returns in locale date format.

timestring

Same as date but returns in locale time format.

isodate

Same as date but returns in JavaScript ISO format.

utcdate

Same as date but returns in JavaScript UTC format.

iso8601

Same as date but returns in iso8601 format.

number

If it's a number or can be parsed into a number return as a number. Otherwise return NaN.

integer

If it's an integer or can be parsed into an integer return as an integer. Otherwise return NaN.

boolean

If it's a boolean or can be parsed into a boolean return as a boolean. Otherwise return undefined.

byte

Try to parse into a byte value. If it's a number 0-255 then return that value as an integer. If it's a single char string and the char code is 0-255 then return that value. Otherwise return undefined.

finite

If it parses to a finite number then return that value. Otherwise return undefined.

url

If it's a Url object or can be parsed to a Url object then return a Url. Otherwise return undefined.

email

If it's a emailaddress object or can be parsed into a emailaddress object then will return a string representation of the email addresses. If optional emailaddress dependency isn't installed then just treats it as string.

epochs

If it's a number it is treated as epochs. If it is a date or can be parsed as a date then will be output as epochs.

Requires Node 4 with harmony features or Traceur.

License

ISC