valerie
Simple javascript object validator
The goal of this project is to provide a simple, intuitive, extensible, independent, and isomorphic javascript object validation library.
What makes Valerie any different from other validation libs?
- No dependencies
- Very lightweight
- Easy to use both server- and browser-side
- Validation rules are standard functions (keep it simple)
- Supports async/promise-based validation rules
- Custom rules are super easy to make
- Custom error messages for all built-in rules
- Source uses ES6/7 features (transpiled to ES5 for browsers)
- Full tests and linting
Usage
Import the function and built-in rules
;;;
Compose the validation schema for our object
const schema = id: name: first: last: age: favoriteColor: ;
Create the object validator, which is a function taking a single object parameter, and returns a Promise
which resolves to an array containing errors. The array will be empty if there are no errors.
const validate = ;
Validate
const input = id: 10 name: first: 'foo' age: 99 favoriteColor: 'potato'; // ES7const errors = await ; // ES6 // ES5; /*[ { property: 'name.last', message: 'last name is required' }, { property: 'favoriteColor', message: 'must be a primary color' }]*/ // or just get the first errorconst errors = await ; /*[ { property: 'name.last', message: 'last name is required' }]*/
Rules
Validation rules are just simple functions that take a single input, the value to validate, and return undefined
if valid, or an error message if not.
The built-in rule objects exported from valerie/rules
are functions that take a set of options and return the rule function itself.
Example:
; const isTrue = ; ; // 'value must be true';; // undefined
Simple rules
The simple rules are largely based on the fundamental javascript operations.
Equality rules
is(target, [message = "is"])
Tests if a value is strictly equal (===
) to a target value.
target
: what the validated value should equalmessage
: optional custom error message
const isBar = ; const validate = ; const errors = await ;
equalTo(target, [message = "equalTo"])
Tests if a value is loosely equal (==
) to a target value.
target
: what the validated value should equalmessage
: optional custom error message
const isBar = ; const validate = ; const errors = await ;
Numeric rules
number([message = "number"])
Tests if a value is a number (!isNaN
).
message
: optional custom error message
const isNumber = ; const validate = ; const errors = await ;
greaterThan(target, [message = "greaterThan"])
Tests if a value is greater than (>
) a target value.
target
: what the validated value should be greater thanmessage
: optional custom error message
const isPositive = ; const validate = ; const errors = await ;
lessThan(target, [message = "lessThan"])
Tests if a value is less than (<
) a target value.
target
: what the validated value should be less thanmessage
: optional custom error message
const isNegative = ; const validate = ; const errors = await ;
Array rules
array([message = "array"])
Tests if a value is an array (Array.isArray
).
message
: optional custom error message
const isArray = ; const validate = ; const errors = await ;
contains(item, [message = "contains"])
Tests if a value contains (indexOf
) an item.
item
: item that value should containmessage
: optional custom error message
const containsBar = ; const validate = ; const errors = await ;
oneOf(options, [message = "oneOf"])
Tests if a value is equal to (===
) an item in an Array
.
options
: array of items to check againstmessage
: optional custom error message
const isPrimaryColor = ; const validate = ; const errors = await ;
Type rules
isInstanceOf(type, [message = "isInstanceOf"])
Tests if a value is an instance of a class (instanceof
).
type
: what the validated value should be an instance ofmessage
: optional custom error message
const isBar = ; const validate = ; const errors = await ;
isTypeOf(type, [message = "isTypeOf"])
Tests if a value is of a given type (typeof
).
type
: what the validated value should be a type ofmessage
: optional custom error message
const isString = ; const validate = ; const errors = await ;
hasProperty(property, [message = "hasProperty"])
Tests if an object has a child property (hasOwnProperty
).
property
: name of the propertymessage
: optional custom error message
const hasBar = ; const validate = ; const errors = await ;
Logical operators
These rules take one or more rules as input and return new, compoud rule.
async and(rules, [message = "and"])
Tests if a value is valid against all rules within an Array
.
rules
: array of rules to validate againstmessage
: optional custom error message
const isArrayContainingBar = ; const validate = ; const errors = await
async or(rules, [message = "or"])
Tests if a value is is valid against at least one rule within an Array
of rules.
rules
: array of rules to validate againstmessage
: optional custom error message
const isNumberOrX = ; const validate = ; const errors = await
async not(rule, [message = "not"])
Tests if a value is not valid against rule.
rule
: rule to validate againstmessage
: optional custom error message
const isNotNumber = ; const validate = ; const errors = await
Other rules
regex(pattern, [message = "regex"])
Tests if a value matches a regex (.match
)
pattern
: regexp (RegExp
or/pattern/
)message
: optional custom error message
const isEMail = ; const validate = ; const errors = await ;
Extended Rules
Extended rules use the simple rules to form more complex logic
async range(min, max, [message = "range"])
Tests if a value is between two values. Generally want to use with number
. Depends on and
, or
, greaterThan
, lessThan
, and equalTo
.
min
: minimum value, inclusivemax
: maximum value, inclusivemessage
: optional custom error message
const isNumber = ;const isHumanAge = ; const validate = ; const errors = await ;
async required([message = "required"])
Tests if a value exists (not undefined
, not an empty string, not an empty array). Depends on and
, defined
, and notEmpty
.
message
: optional custom error message
const isRequired = ; const validate = ; const errors = await
Custom Rules
Custom rules are easy to implement. They're simply functions that take a single value and return an error message for failure, and undefined
for passing.
const isEven = { if value % 2 !== 0 return 'value must be even';}; ; // undefined; // value must be even const validate = ; const errors = await ; /* [ { property: 'foo', message: 'value must be even' }]*/
Built-in rules use currying to allow options and custom error messages to be set. You can follow this technique like so:
const divisibleBy = { return { if value % divisor !== 0 return message; }}; const isDivisibleBy3 = ;
Check out the other rules for more examples.
TODO:
- Rules
email
- Examples of client- and server-side usage
- Example of promise rule
- Compare to other libs
- https://github.com/hapijs/joi (large)
- https://github.com/molnarg/js-schema (no custom messages)
- https://github.com/ansman/validate.js