Validate object properties in javascript.
npm install validateValidate object properties in javascript.
Define a schema and call .validate() with the object you want to validate.
The .validate() function returns an array of validation errors.
``js
import Schema from 'validate'
const user = new Schema({
username: {
type: String,
required: true,
length: { min: 3, max: 32 }
},
pets: [{
name: {
type: String
required: true
},
animal: {
type: String
enum: ['cat', 'dog', 'cow']
}
}],
address: {
street: {
type: String,
required: true
},
city: {
type: String,
required: true
}
zip: {
type: String,
match: /^[0-9]+$/,
required: true
}
}
})
const errors = user.validate(obj)
`
Each error has a .path, describing the full path of the property that failed validation, and a .message describing the error.
`js`
errors[0].path //=> 'address.street'
errors[0].message //=> 'address.street is required.'
You can override the default error messages by passing an object to Schema#message().
`js
const post = new Schema({
title: { required: true }
})
post.message({
required: (path) => ${path} can not be empty.
})
const [error] = post.validate({})
assert(error.message = 'title can not be empty.')
`
It is also possible to define messages for individual properties:
`js`
const post = new Schema({
title: {
required: true,
message: 'Title is required.'
}
})
And for individual validators:
`js`
const post = new Schema({
title: {
type: String,
required: true,
message: {
type: 'Title must be a string.',
required: 'Title is required.'
}
}
})
Objects and arrays can be nested as deep as you want:
`js`
const event = new Schema({
title: {
type: String,
required: true
},
participants: [{
name: String,
email: {
type: String,
required: true
},
things: [{
name: String,
amount: Number
}]
}]
})
Arrays can be defined implicitly, like in the above example, or explicitly:
`js`
const post = new Schema({
keywords: {
type: Array,
each: { type: String }
}
})
Array elements can also be defined individually:
`js`
const user = new Schema({
something: {
type: Array,
elements: [
{ type: Number },
{ type: String }
]
}
})
Nesting also works with schemas:
`js
const user = new Schema({
name: {
type: String,
required: true
},
email: {
type: String,
required: true
}
})
const post = new Schema({
title: {
type: String,
required: true
},
content: {
type: String,
required: true
},
author: user
})
`
If you think it should work, it probably works.
#### Naming conflicts
Validate will naively assume that a nested object where _all_ property names are validators is not a nested object.
`js`
const schema = new Schema({
pet: {
type: {
required: true,
type: String,
enum: ['cat', 'dog']
}
}
});
In this example, the pet.type property will be interpreted as a type rule, and the validations will not work as intended. To work around this we could use the slightly more verbose properties rule:
`js`
const schema = new Schema({
pet: {
properties: {
type: {
required: true,
type: String,
enum: ['cat', 'dog']
}
}
}
});
In this case the type property of pets.properties will be interpreted as a nested property, and the validations will work as intended.
Custom validators can be defined by passing an object with named validators to .use:
`js
const hexColor = val => /^#[0-9a-fA-F]$/.test(val)
const car = new Schema({
color: {
type: String,
use: { hexColor }
}
})
`
Define a custom error message for the validator:
`js${path} must be a valid color.
car.message({
hexColor: path =>
})
Pass a constructor to .type to validate against a custom type:
`js
class Car {}
const user = new Schema({
car: { type: Car }
})
`
If you want to avoid constructing large objects, you can add paths to a schema by using the chainable API:
`js
const user = new Schema()
user
.path('username').type(String).required()
.path('address.zip').type(String).required()
`
Array elements can be defined by using $ as a placeholder for indices:
`js`
const user = new Schema()
user.path('pets.$').type(String)
This is equivalent to writing
`js`
const user = new Schema({ pets: [{ type: String }]})
Values can be automatically typecast before validation.
To enable typecasting, pass an options object to the Schema constructor with typecast set to true.
`js`
const user = new Schema(definition, { typecast: true })
You can override this setting by passing an option to .validate().
`js`
user.validate(obj, { typecast: false })
To typecast custom types, you can register a typecaster:
`js
class Car {}
const user = new Schema({
car: { type: Car }
})
user.typecaster({
Car: (val) => new Car(val)
})
`
By default, all values not defined in the schema will be stripped from the object.
Set .strip = false on the options object to disable this behavior. This will likely be changed in a future version.
on the options object to enable strict mode.API
#### Table of Contents
- Property
- Parameters
- message
- Parameters
- Examples
- schema
- Parameters
- Examples
- use
- Parameters
- Examples
- required
- Parameters
- Examples
- type
- Parameters
- Examples
- string
- Examples
- number
- Examples
- array
- Examples
- date
- Examples
- length
- Parameters
- Examples
- size
- Parameters
- Examples
- enum
- Parameters
- Examples
- match
- Parameters
- Examples
- each
- Parameters
- Examples
- elements
- Parameters
- Examples
- properties
- Parameters
- Examples
- path
- Parameters
- Examples
- typecast
- Parameters
- Examples
- validate
- Parameters
- Examples
- Schema
- Parameters
- Examples
- path
- Parameters
- Examples
- validate
- Parameters
- Examples
- assert
- Parameters
- Examples
- message
- Parameters
- Examples
- validator
- Parameters
- Examples
- typecaster
- Parameters
- Examples
$3
A property instance gets returned whenever you call
schema.path().
Properties are also created internally when an object is passed to the Schema constructor.#### Parameters
-
name String the name of the property
- schema Schema parent schema#### message
Registers messages.
##### Parameters
-
messages (Object \| String) ##### Examples
`javascript
prop.message('something is wrong')
prop.message({ required: 'thing is required.' })
`Returns Property
#### schema
Mount given
on current path.##### Parameters
-
schema Schema the schema to mount##### Examples
`javascript
const user = new Schema({ email: String })
prop.schema(user)
`Returns Property
#### use
Validate using named functions from the given object.
Error messages can be defined by providing an object with
named error messages/generators to
The message generator receives the value being validated,
the object it belongs to and any additional arguments.
##### Parameters
-
Object object with named validation functions to call##### Examples
`javascript
const schema = new Schema()
const prop = schema.path('some.path')schema.message({
binary: (path, ctx) =>
${path} must be binary.,
bits: (path, ctx, bits) => ${path} must be ${bits}-bit
})prop.use({
binary: (val, ctx) => /^[01]+$/i.test(val),
bits: [(val, ctx, bits) => val.length == bits, 32]
})
Returns Property
#### required
Registers a validator that checks for presence.
##### Parameters
-
Boolean? true if required, false otherwise (optional, default true)##### Examples
`javascript
prop.required()
`Returns Property
#### type
Registers a validator that checks if a value is of a given
##### Parameters
-
(String \| Function) type to check for##### Examples
`javascript
prop.type(String)
`javascript
prop.type('string')
`Returns Property
#### string
Convenience method for setting type to
##### Examples
javascript
prop.string()
`Returns Property
#### number
Convenience method for setting type to
##### Examples
javascript
prop.number()
`Returns Property
#### array
Convenience method for setting type to
##### Examples
javascript
prop.array()
`Returns Property
#### date
Convenience method for setting type to
##### Examples
javascript
prop.date()
`Returns Property
#### length
Registers a validator that checks length.
##### Parameters
-
(Object \| Number) object with .min and .max properties or a number
- rules.min Number minimum length
- rules.max Number maximum length##### Examples
`javascript
prop.length({ min: 8, max: 255 })
prop.length(10)
`Returns Property
#### size
Registers a validator that checks size.
##### Parameters
-
(Object \| Number) object with .min and .max properties or a number
- rules.min Number minimum size
- rules.max Number maximum size##### Examples
`javascript
prop.size({ min: 8, max: 255 })
prop.size(10)
`Returns Property
#### enum
Registers a validator for enums.
##### Parameters
-
- rules Array allowed values##### Examples
`javascript
prop.enum(['cat', 'dog'])
`Returns Property
#### match
Registers a validator that checks if a value matches given
.##### Parameters
-
regexp RegExp regular expression to match##### Examples
`javascript
prop.match(/some\sregular\sexpression/)
`Returns Property
#### each
Registers a validator that checks each value in an array against given
.##### Parameters
-
rules (Array \| Object \| Schema \| Property) rules to use##### Examples
`javascript
prop.each({ type: String })
prop.each([{ type: Number }])
prop.each({ things: [{ type: String }]})
prop.each(schema)
`Returns Property
#### elements
Registers paths for array elements on the parent schema, with given array of rules.
##### Parameters
-
Array array of rules to use##### Examples
`javascript
prop.elements([{ type: String }, { type: Number }])
`Returns Property
#### properties
Registers all properties from the given object as nested properties
##### Parameters
-
Object properties with rules##### Examples
`javascript
prop.properties({
name: String,
email: String
})
`Returns Property
#### path
Proxy method for schema path. Makes chaining properties together easier.
##### Parameters
-
...any ##### Examples
`javascript
schema
.path('name').type(String).required()
.path('email').type(String).required()
`#### typecast
Typecast given
##### Parameters
-
Mixed value to typecast##### Examples
`javascript
prop.type(String)
prop.typecast(123) // => '123'
`Returns Mixed
#### validate
Validate given
##### Parameters
-
Mixed value to validate
- ctx Object the object containing the value
- path String? path of the value being validated (optional, default this.name)##### Examples
`javascript
prop.type(Number)
assert(prop.validate(2) == null)
assert(prop.validate('hello world') instanceof Error)
`Returns ValidationError
$3
A Schema defines the structure that objects should be validated against.
#### Parameters
-
Object? schema definition (optional, default {})
- opts Object? options (optional, default {})
- opts.typecast Boolean typecast values before validation (optional, default false)
- opts.strip Boolean strip properties not defined in the schema (optional, default true)
- opts.strict Boolean validation fails when object contains properties not defined in the schema (optional, default false)#### Examples
`javascript
const post = new Schema({
title: {
type: String,
required: true,
length: { min: 1, max: 255 }
},
content: {
type: String,
required: true
},
published: {
type: Date,
required: true
},
keywords: [{ type: String }]
})
`javascript
const author = new Schema({
name: {
type: String,
required: true
},
email: {
type: String,
required: true
},
posts: [post]
})
`#### path
Create or update
with given rules.##### Parameters
-
path String full path using dot-notation
- rules (Object \| Array \| String \| Schema \| Property)? rules to apply##### Examples
`javascript
const schema = new Schema()
schema.path('name.first', { type: String })
schema.path('name.last').type(String).required()
`Returns Property
#### validate
Validate given
.##### Parameters
-
obj Object the object to validate
- opts Object? options, see Schema (optional, default {})##### Examples
`javascript
const schema = new Schema({ name: { required: true }})
const errors = schema.validate({})
assert(errors.length == 1)
assert(errors[0].message == 'name is required')
assert(errors[0].path == 'name')
`Returns Array
#### assert
Assert that given
is valid.##### Parameters
-
obj Object
- opts Object? ##### Examples
`javascript
const schema = new Schema({ name: String })
schema.assert({ name: 1 }) // Throws an error
`#### message
Override default error messages.
##### Parameters
-
(String \| Object) name of the validator or an object with name-message pairs
- message (String \| Function)? the message or message generator to use##### Examples
`javascript
const hex = (val) => /^0x[0-9a-f]+$/.test(val)
schema.path('some.path').use({ hex })
schema.message('hex', path => ${path} must be hexadecimal)
`javascript
schema.message({ hex: path => ${path} must be hexadecimal })
`Returns Schema
#### validator
Override default validators.
##### Parameters
-
(String \| Object) name of the validator or an object with name-function pairs
- fn Function? the function to use##### Examples
`javascript
schema.validator('required', val => val != null)
`javascript
schema.validator({ required: val => val != null })
`Returns Schema
#### typecaster
Override default typecasters.
##### Parameters
-
(String \| Object) name of the validator or an object with name-function pairs
- fn Function? the function to use##### Examples
`javascript
schema.typecaster('SomeClass', val => new SomeClass(val))
`javascript
schema.typecaster({ SomeClass: val => new SomeClass(val) })
``Returns Schema
MIT