fastest-validator
⚡️ The fastest JS validator library for NodeJS.
Key features
- fast! Really!
- 9 built-in validator
- nested object & array handling
- multiple validators for fields
- customizable error messages
- programmable error object
- unit tests & 100% cover
How fast?
Very fast! 3 million validation/sec (on Intel i7-4770K, Node.JS: 6.10.0)
√ validate with pre-compiled schema x 3,052,280 ops/sec ±0.82% (93 runs sampled)
Compared to other popular libraries:
100x faster than Joi.
Would you like to test it?
$ git clone https://github.com/icebob/fastest-validator.git
$ cd fastest-validator
$ npm install
$ npm run bench
Installation
NPM
You can install it via NPM.
$ npm install fastest-validator --save
or
$ yarn add fastest-validator
Usage
Simple method
Call the validate
method with the object
and the schema
.
If the performance is important, you won't use this method.
let Validator = ; let v = ; const schema = id: type: "number" positive: true integer: true name: type: "string" min: 3 max: 255 status: "boolean" // short-hand def; console;// Returns: true console;/* Returns an array with errors: [ { type: 'stringMin', expected: 3, actual: 2, field: 'name', message: 'The \'name\' field length must be larger than or equal to 3 characters long!' } ]*/
Fast method
In this case, the first step is to compile the schema to a compiled "checker" function. After it if you would like to validate your object, just call this "checker" function with your object.
This method is ~10x faster than "simple method".
let Validator = ; let v = ; const schema = id: type: "number" positive: true integer: true name: type: "string" min: 3 max: 255 status: "boolean" // short-hand def; const check = v; console;// Returns: true console;/* Returns an array with errors: [ { type: 'required', field: 'status', message: 'The \'status\' field is required!' } ]*/
Optional & required fields
Every fields in the schema will be required field. If you would like to define optional fields, set optional: true
.
let schema = name: type: "string" // required age: type: "number" optional: true v; // Validv; // Validv; // Fail
Multiple validators
There is possible to define more validators for a field. In this case if one of all validators is success, the field will be valid.
let schema = cache: type: "string" type: "boolean" v; // Validv; // Validv; // Fail
Built-in validators
any
This is not validate the type of value. Accept any types.
let schema = prop: type: "any" v; // Validv; // Validv; // Valid
array
This is an Array
validator.
Simple example with strings:
let schema = roles: type: "array" items: "string" v; // Validv; // Validv; // Fail
Example with only positive number:
let schema = list: type: "array" min: 2 items: type: "number" positive: true integer: true v; // Validv; // Validv; // Fail (min 2 elements)v; // Fail (negative number)
Example with object list:
let schema = users: type: "array" items: type: "object" props: id: type: "number" positive: true name: type: "string" empty: false status: "boolean" v; // Valid
Properties
Property | Default | Description |
---|---|---|
empty |
true |
If true, the validator accepts empty array [] . |
min |
null |
Minimum count of elements. |
max |
null |
Maximum count of elements. |
length |
null |
Fix count of elements. |
contains |
null |
The array must contains this element too. |
enum |
null |
Every element must be an element of the enum array. |
Example for enum
:
let schema = roles: type: "array" items: "string" enum: "user" "admin" v; // Validv; // Validv; // Fail
boolean
This is a Boolean
validator.
let schema = status: type: "boolean" v; // Validv; // Validv; // Failv; // Fail
Properties
Property | Default | Description |
---|---|---|
convert |
false |
if true and the type is not Boolean , try to convert. 1 , "true" , "1" , "on" will be true. 0 , "false" , "0" , "off" will be false. |
date
This is a Date
validator.
let schema = dob: type: "date" v; // Validv; // Validv; // Fail
Properties
Property | Default | Description |
---|---|---|
convert |
false |
if true and the type is not Date , try to convert with new Date() . |
email
This is an e-mail address validator.
let schema = email: type: "email" v; // Validv; // Validv; // Fail
Properties
Property | Default | Description |
---|---|---|
mode |
quick |
Checker method. Can be quick or precise . |
forbidden
This validator gives error if the property is exists in the object.
let schema = password: type: "forbidden" v; // Validv; // Fail
function
The type of value must be Function
.
let schema = show: type: "function" v; // Validv; // Validv; // Fail
number
This is a number validator. The type of value must be Number
.
let schema = age: type: "number" v; // Validv; // Validv; // Fail
Properties
Property | Default | Description |
---|---|---|
min |
null |
Minimum value. |
max |
null |
Maximum value. |
equal |
null |
Fix value. |
notEqual |
null |
Can't be equal with this value. |
integer |
false |
The value must be a non-decimal value. |
positive |
false |
The value must be larger than zero. |
negative |
false |
The value must be less than zero. |
convert |
false |
if true and the type is not Number , try to convert with parseFloat . |
object
This is a nested object validator.
let schema = address: type: "object" props: country: type: "string" city: "string" // short-hand zip: "number" // short-hand v; // Valid v; // Fail ("The 'address.zip' field is required!")
string
This is a string
validator. The type of value must be String
.
let schema = name: type: "string" v; // Validv; // Validv; // Fail
Properties
Property | Default | Description |
---|---|---|
empty |
true |
If true, the validator accepts empty string "" . |
min |
null |
Minimum length of value. |
max |
null |
Maximum length of value. |
length |
null |
Fix length of value. |
pattern |
null |
Regex pattern. |
contains |
null |
The value must contains this text. |
enum |
null |
The value must be an element of the enum array. |
url
This is an URL validator.
let schema = url: type: "url" v; // Validv; // Validv; // Fail
Custom validator
You can also create your custom validator.
let v = messages: // Register our new error message text evenNumber: "The '{field}' field must be an even number! Actual: {actual}" ; // Register a custom 'even' validatorv; const schema = name: type: "string" min: 3 max: 255 age: type: "even" ; console;// Returns: true console;/* Returns an array with errors: [{ type: 'evenNumber', expected: null, actual: 19, field: 'age', message: 'The \'age\' field must be an even number! Actual: 19' }]*/
Or you can use the custom
type with inline checker function:
let v = messages: // Register our new error message text weightMin: "The weight must be larger than {expected}! Actual: {actual}" ; const schema = name: type: "string" min: 3 max: 255 weight: type: "custom" minWeight: 10 { return value < schemaminWeight ? this : true; } ; console;// Returns: true console;/* Returns an array with errors: [{ type: 'weightMin', expected: 10, actual: 8, field: 'weight', message: 'The weight must be larger than 10! Actual: 8' }]*/
Custom error messages (l10n)
You can set your custom messages in constructor of validator.
const Validator = ;const v = messages: stringMin: "A(z) '{field}' mező túl rövid. Minimum: {expected}, Jelenleg: {actual}" stringMax: "A(z) '{field}' mező túl hosszú. Minimum: {expected}, Jelenleg: {actual}" ; v;/* Returns:[ { type: 'stringMin', expected: 6, actual: 4, field: 'name', message: 'A(z) \'name\' mező túl rövid. Minimum: 6, Jelenleg: 4' } ]*/
Message types
Name | Default text |
---|---|
required |
The '{field}' field is required! |
string |
The '{field}' field must be a string! |
stringEmpty |
The '{field}' field must not be empty! |
stringMin |
The '{field}' field length must be larger than or equal to {expected} characters long! |
stringMax |
The '{field}' field length must be less than or equal to {expected} characters long! |
stringLength |
The '{field}' field length must be {expected} characters long! |
stringPattern |
The '{field}' field fails to match the required pattern! |
stringContains |
The '{field}' field must contain the '{expected}' text! |
stringEnum |
The '{field}' field does not match any of the allowed values! |
number |
The '{field}' field must be a number! |
numberMin |
The '{field}' field must be larger than or equal to {expected}! |
numberMax |
The '{field}' field must be less than or equal to {expected}! |
numberEqual |
The '{field}' field must be equal with {expected}! |
numberNotEqual |
The '{field}' field can't be equal with {expected}! |
numberInteger |
The '{field}' field must be an integer! |
numberPositive |
The '{field}' field must be a positive number! |
numberNegative |
The '{field}' field must be a negative number! |
array |
The '{field}' field must be an array! |
arrayEmpty |
The '{field}' field must not be an empty array! |
arrayMin |
The '{field}' field must contain at least {expected} items! |
arrayMax |
The '{field}' field must contain less than or equal to {expected} items! |
arrayLength |
The '{field}' field must contain {expected} items! |
arrayContains |
The '{field}' field must contain the '{expected}' item! |
arrayEnum |
The '{field} field value '{expected}' does not match any of the allowed values! |
boolean |
The '{field}' field must be a boolean! |
function |
The '{field}' field must be a function! |
date |
The '{field}' field must be a Date! |
dateMin |
The '{field}' field must be larger than or equal to {expected}! |
dateMax |
The '{field}' field must be less than or equal to {expected}! |
forbidden |
The '{field}' field is forbidden! |
email |
The '{field}' field must be a valid e-mail! |
Message fields
Name | Description |
---|---|
field |
Name of field |
expected |
The expected value of field |
actual |
The actual value of field |
type |
Type of field |
Development
npm run dev
Test
npm test
Coverage report
---------------|----------|----------|----------|----------|----------------|
File | % Stmts | % Branch | % Funcs | % Lines |Uncovered Lines |
---------------|----------|----------|----------|----------|----------------|
All files | 100 | 100 | 100 | 100 | |
lib | 100 | 100 | 100 | 100 | |
messages.js | 100 | 100 | 100 | 100 | |
validator.js | 100 | 100 | 100 | 100 | |
lib/rules | 100 | 100 | 100 | 100 | |
any.js | 100 | 100 | 100 | 100 | |
array.js | 100 | 100 | 100 | 100 | |
boolean.js | 100 | 100 | 100 | 100 | |
date.js | 100 | 100 | 100 | 100 | |
email.js | 100 | 100 | 100 | 100 | |
forbidden.js | 100 | 100 | 100 | 100 | |
function.js | 100 | 100 | 100 | 100 | |
number.js | 100 | 100 | 100 | 100 | |
object.js | 100 | 100 | 100 | 100 | |
string.js | 100 | 100 | 100 | 100 | |
url.js | 100 | 100 | 100 | 100 | |
---------------|----------|----------|----------|----------|----------------|
Contribution
Please send pull requests improving the usage and fixing bugs, improving documentation and providing better examples, or providing some testing, because these things are important.
License
fastest-validator is available under the MIT license.
Contact
Copyright (C) 2017 Icebob