Simple Schema Validation


Validate object properties in javascript.

* install
* Usage
+ Custom error messages
+ Nesting
- Naming conflicts
+ Custom validators
+ Custom types
+ Chainable API
+ Typecasting
+ 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
* License

install

npm install --save simple-schema-validation

Usage

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 "simple-schema-validation"

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.'
`

$3

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.'
}
}
})
`

$3

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
})
`

Nesting with parent having required = false is also possible.
In this case the properties in parent will only be validated if address is not null or undefined.

`js
const user = new Schema({
name: {
type: String,
required: true
},
email: {
type: String,
required: true
},
address: {
required: false,
street: {
type: String,
required: true
},
city: {
type: String,
required: true
}
}
})
`

#### 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.

$3

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
car.message({
hexColor: path => ${path} must be a valid color.
})
`

$3

Pass a constructor to .type to validate against a custom type:

`js
class Car {}

const user = new Schema({
car: { type: Car }
})
`

$3

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 }]})
`

$3

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)
})
`

$3


When strict mode is enabled, properties that are not defined in the schema will trigger a validation error. Set .strict = true 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 schema 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 schema.message()

The message generator receives the value being validated,
the object it belongs to and any additional arguments.

##### Parameters

- fns 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.
If set to false and object is null or undefined children are not validated.

##### Parameters

- bool 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 type

##### Parameters

- type (String \| Function) type to check for

##### Examples

`javascript
prop.type(String)
`

`javascript
prop.type('string')
`

Returns Property

#### string

Convenience method for setting type to String

##### Examples

`javascript
prop.string()
`

Returns Property

#### number

Convenience method for setting type to Number

##### Examples

`javascript
prop.number()
`

Returns Property

#### array

Convenience method for setting type to Array

##### Examples

`javascript
prop.array()
`

Returns Property

#### date

Convenience method for setting type to Date

##### Examples

`javascript
prop.date()
`

Returns Property

#### length

Registers a validator that checks length.

##### Parameters

- rules (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

- rules (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

- enums
- rules Array allowed values

##### Examples

`javascript
prop.enum(['cat', 'dog'])
`

Returns Property

#### match

Registers a validator that checks if a value matches given regexp.

##### 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 rules.

##### 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

- arr 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

- props 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

- args ...any

##### Examples

`javascript
schema
.path('name').type(String).required()
.path('email').type(String).required()
`

#### typecast

Typecast given value

##### Parameters

- value Mixed value to typecast

##### Examples

`javascript
prop.type(String)
prop.typecast(123) // => '123'
`

Returns Mixed

#### validate

Validate given value

##### Parameters

- value 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

- obj 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 path 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 obj.

##### 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 obj 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

- name (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

- name (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

- name (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

License

MIT