rttc
Runtime (recursive) type-checking for JavaScript.
Installation
$ npm install rttc --save
Quick Start
var rttc = require('rttc');
rttc.coerce({ firstName: 'string'}, {firstName: 45});
rttc.coerce({ firstName: 'string'}, {something: 'totally incorrect'});
rttc.validate({ firstName: 'string'}, {something: 'totally incorrect'});
rttc.validate({ firstName: 'string'}, {firstName: 45});
rttc.validateStrict({ firstName: 'string'}, {firstName: 45});
rttc.validateStrict({ firstName: 'string'}, {firstName: '45'});
Philosophy
All of the validation and coercion strategies used in this modules are recursive through the keys of plain old JavaScript objects and the indices of arrays.
Coercion vs. Validation
.validateStrict()
throws if the provided value is not the right type (recursive)..validate()
either returns a (potentially "lightly" coerced) version of the value that was accepted, or it throws. The "lightly" coerced value turns "3"
into 3
, "true"
into true
, -4.5
into "-4.5"
, etc..coerce()
ALWAYS returns an acceptable version of the value, even if it has to mangle it to get there (i.e. by using the "base value" for the expected type.)
Base values
- For "string", base value is
""
- For "number", base value is
0
- For "boolean", base value is
false
- For any "dictionary" (
{}
), base value is {}
, with whatever keys are expected (recursive) - For a generic "array" (
[]
), base value is []
, with a single archetypal item matching the expectation (recursive)
Edge cases
undefined
will always be coerced to the base value of the expected type.null
is never valid.NaN
is never valid.Infinity
is never valid.-Infinity
is never valid.
Dictionaries
- Dictionaries (i.e. plain old JavaScript objects like
{}
) in type schemas can be infinitely nested. Type validation and coercion will proceed through the nested objects recursively.
{
id: 'number',
name: 'string',
isAdmin: 'boolean',
mom: {
id: 'number',
name: 'string',
occupation: {
title: 'string',
workplace: 'string'
}
}
}
When validating against a dictionary schema with at least one key, extra keys in the actual value will be stripped out. If the dictionary schema is empty, all actual keys will be left alone.
Arrays
- Arrays in type schemas must be homogeneous and have exactly one item; that is, if you want to validate an array, you only need to provide the type/schema for the first item in the array, e.g.:
[
{
id: 'number',
name: 'string',
email: 'string',
age: 'number',
isAdmin: 'boolean',
favoriteColors: ['string'],
friends: [
{
id: 'number',
name: 'string'
}
]
}
]
Usage
rttc.infer(value)
Infer the type/schema of the provided value.
require('rttc').infer(false);
require('rttc').infer(0);
require('rttc').infer({
foo: 'bar'
});
require('rttc').infer({
foo: 'whatever',
bar: { baz: true }
});
require('rttc').infer([{
foo: ['bar']
}]);
require('rttc').infer({
user: {
friends: [{
name: 'Lenny',
age: 77
}]
});
rttc.validate(expected, actual)
rttc.validate('string', 'foo');
rttc.validate('number', 4.5);
rttc.validate('boolean', true);
rttc.validate('string', -2);
rttc.validate('string', false);
rttc.validate('number', '3');
rttc.validate('boolean', 'true');
rttc.validate({
user: {
friends: [{
name: 'Lenny',
age: 77
}]
}, {
user: {
friends: [{
name: 'Lenny',
age: '77'
}]
}
});
If value cannot be properly coerced, throws error with code=E_INVALID_TYPE
:
rttc.validate('number', 'asdf');
rttc.coerce(expected, actual)
rttc.coerce('string', 'foo');
rttc.coerce('number', 4.5);
rttc.coerce('boolean', true);
rttc.coerce('string', -2);
rttc.coerce('string', false);
rttc.coerce('number', '3');
rttc.coerce('boolean', 'true');
If value can't be properly coerced, the "base value" for the type will be used:
rttc.coerce('number', 'asdf');
// => 0
rttc.coerce('boolean', 'asdf');
// => false
rttc.coerce({
user: {
friends: [{
name: 'Lenny',
age: 77
}]
}, 'err... some dude who\'s friends with lenny?');
// =>
/*
{
user: {
friends: [{
name: 'Lenny',
age: 77
}]
}
}
*/