osv - Object Schema Validation
This library can be used for validating JavaScript objects or other data types like numbers, strings, booleans or arrays. It is very strongly inspired by @hapijs/joi and mongoose schema validation.
; ; // asynchronous ; // Promise<Data> resultAsync .then .catch; // synchronous ; // { value?: Data, error?: ValidationError, exec: () => Promise<Data> } resultSync.exec .then .catch;
Installation
$ npm install --save osv
or
$ yarn add osv
API
This library is able to validate arrays
, booleans
, numbers
, strings
and of course objects
.
By default, all specified keys of an object are optional
. If a key is missing in an object but it has an object with additional keys as its value, a plain object will be added (see examples).
ObjectSchema
// types; ;
Simply define your object schema and create an ObjectSchema
instance.
; ; ;
After that you can validate objects. The validate
method returns a Promise which resolves to the validated data if successful. Otherwise it rejects with a ValidationError
.
The validateSync
method returns an object with the following schema:
// Data: the data type of the validated value
; // async schema.validateuser1 .then; // sync ; console.logresult.value, result.error; ; schema.validateuser1 .catch;
You can also omit specific paths during checking. These are just transfered onto the result value the way they are on the initial value. A whitelist and a blacklist are both optional.
schema.validate, // succeeds .then;
ObjectSchema.Types.Base
BaseSchemaType - This is the schema type which all others extend from.
Options
Option Path | Info | Type | Default |
---|---|---|---|
required? |
if a value is required or not | boolean | <D = any>(value: any, data: D) => boolean |
|
pre?.validate? |
run before every validation, returns value | <D = any>(value: any, data: D) => any; |
|
post?.validate? |
run after every validation, returns value | <D = any>(value: any, data: D) => any; |
OSV.array(options)
- ObjectSchema.Types.Array
ArraySchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
item |
array item object schema | ObjectSchema |
|
allowNull? |
allow null as a valid value |
boolean |
|
min? |
at least ... items | number |
|
max? |
... items at maximum | number |
|
length? |
exact ... items | number |
OSV.boolean(options)
- ObjectSchema.Types.Boolean
BooleanSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
allowNull? |
allow null as a valid value |
boolean |
OSV.custom(options)
- ObjectSchema.Types.Custom
CustomSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
validate |
custom validation callback | see options or callback type |
OSV.number(options)
- ObjectSchema.Types.Number
NumberSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
allowNull? |
allow null as a valid value |
boolean |
|
min? |
value has to be ... at least | number |
|
max? |
value has to be ... at maximum | number |
|
greater? |
value has to be greater than ... | number |
|
less? |
value has to be less than ... | number |
|
integer? |
value has to be an integer | boolean |
|
positive? |
value has to be positive | boolean |
|
negative? |
value has to be negative | boolean |
OSV.optional(options)
- ObjectSchema.Types.Optional
OptionalSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
item |
array item object schema | ObjectSchema |
|
allowNull? |
allow null as a valid value |
boolean |
OSV.string(options)
- ObjectSchema.Types.String
StringSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
allowNull? |
allow null as a valid value |
boolean |
|
empty? |
value is allowed to have a length of 0 | boolean |
true |
oneOf? |
value is allowed to be one of values | string[] |
|
regex? |
value has to match regex | RegExp |
|
length? |
value has to be of length | number |
|
minLength? |
value has to be longer than minLength | number |
|
maxLength? |
value has to be shorter than maxLength | number |
OSV.union(options)
- ObjectSchema.Types.Union
UnionSchemaType - Options
Everything from BaseSchemaType
and ...
Option Path | Info | Type | Default |
---|---|---|---|
schemas |
array of ObjectSchemas which to use for validation | ObjectSchema[] |
|
allowNull? |
allow null as a valid value |
boolean |
|
resolve? |
get index of schema in schemas array to use for validation. otherwise all schemas are tried. | (data: any) => number |
Example
; schema.validate .then;
Contributing
PR welcome. This repository uses git flow
.
Commit format: ACTION: message
.
Example: ADD: tests for schema types & object schema validator
.
Action words could be e.g. ADD
, REFACTOR
, RENAME
or REMOVE
.