waechter
v1.0.0-alpha.6
Published
simple, functional, sync/async validation for Node.js and browsers
Downloads
4
Maintainers
Readme
waechter
simple, functional, sync/async validation for Node.js and browsers
inspired by Prismatic/schema
waechter is german for guardian
npm install waechter
bower install waechter
lib/waechter.js supports AMD.
if AMD is not available it sets the global variable waechter
.
require:
> var waechter = require('waechter');
predicates
a predicate is a function that takes a value and returns a boolean indicating whether that value is valid.
is.js
is a big collection of predicates.
waechter doesn't reinvent the wheel and uses is.js predicates:
> var isjs = require('isjs');
> isjs.email('i am definitely not an email address');
false
> isjs.email('[email protected]');
true
validators
a validator is a function that takes a value and
returns nothing (null
or undefined
) if the value is valid.
otherwise it returns a value describing the error.
that value is usually a string that is a helpful error message
or an object whose values are error messages.
you can make a validator from a predicate using waechter.predicateToValidator
> var validateEmail = waechter.predicateToValidator(
// the predicate
isjs.email,
// the value that is returned when the predicate returns false
'must be an email address'
);
you can then use the validator to validate some data:
> validateEmail('i am definitely not an email address');
'must be an email address'
> validateEmail('[email protected]');
null
these validators are builtin
waechter.exist
waechter.string
waechter.stringNotEmpty
waechter.email
waechter.stringMinLength(min)
waechter.number
waechter.numberWithin(min, max)
(range is exclusive)waechter.true
waechter.false
waechter.undefined
waechter.null
waechter.boolean
you can easily make your own validators using waechter.predicateToValidator
.
composing validators
waechter.and(validators...)
returns a validator that returns
null if all validators return null and otherwise returns the first error.
waechter.or(validators...)
returns a validator that returns
null if at least one of the validators returns null and otherwise returns
an array of errors.
use waechter.undefinedOr(validators...)
to make things optional.
schemas
a schema is an object whose values are validators:
> var userSchema = {
email: waechter.email,
password: waechter.stringNotEmpty
};
you can make a validator from a schema:
> var validateUser = waechter.schemaToValidator(userSchema);
you can then use that validator to validate the structure of objects:
> validateUser({
email: 'invalid'
});
{
email: 'must be an email address',
password: 'must not be null or undefined'
}
> validateUser({
email: '[email protected]',
password: 'topsecret'
});
null
keys that are not present in the schema are not allowed in the data:
> validateUser({
email: '[email protected]',
password: 'topsecret'
is_admin: true
});
{
is_admin: 'disallowed key'
}
async validators
an async validator is like a validator but returns a promise.
you can lazily (only when needed) run async validators after sync validators like so:
> var userSchema = {
email: waechter.email,
password: waechter.stringNotEmpty
};
> var userSchemaAsync = {
email: function(email) {
return doesUserWithEmailAlreadyExistInDatabase(email).then(function(exists) {
if (exists) {
return 'taken';
}
});
}
};
> validateUser = waechter.schemasToLazyAsyncValidator(
userSchema,
userSchemaAsync
);
you can mix schemas with sync and async validators in the arguments to
waechter.schemasToLazyAsyncValidator
.
validators in later schemas are only run for keys that have no errors yet:
> validateUser({
email: 'invalid'
}).then(function(errors) {
> errors
{
email: 'must be an email address',
password: 'must not be null or undefined'
}
});
here the validator userSchemaAsync.email
wasn't called.
> validateUser({
email: '[email protected]'
}).then(function(errors) {
> errors
{
email: 'taken',
password: 'must not be null or undefined'
}
});
this time the validator userSchemaAsync.email
was called.
see the tests for more usage examples.