model-json
v0.2.3
Published
Enforces a schema on a JSON object.
Downloads
15
Maintainers
Readme
model-json
model-json
is a library which enforces a schema on a JSON object.
When the schema is applied to an object, coercion is applied where applicable and keys which do not belong are stripped. Keys which are within the schema are validated and are either removed, set to defaults, or rejected per configuration.
See usage examples to get started with the library.
Install
$ npm i model-json -S
Usage
Example of type coercion and field stripping:
import model from 'model_json'
const example = new model({
fieldA: {
type: 'string'
},
fieldB: {
type: 'number'
}
})
console.log(example.validate({
fieldA: 5,
fieldB: '15',
fieldC: 'this should be gone'
})) // -> { fieldA: '5', fieldB: 15 }
console.log(example.validate({
fieldA: 5,
fieldB: 'Since this field is not required and is not a number, it will be removed from the object.'
})) // -> { fieldA: '5' }
Example of defaults:
import model from 'model_json'
const example = new model({
fieldA: {
type: 'string',
required: true,
default: 'No string provided'
},
fieldB: {
type: 'string',
default: `This default will not appear by default because the field is not required. This behavior is configurable via an option, as shown.`
}
})
console.log(example.validate({ })) // -> { fieldA: 'No string provided' }
console.log(example.validate({ }, { defaults: true })) // -> { fieldA: 'No string provided', fieldB: 'This default <clip> ...' }
import model from 'model_json'
const example = new model({
fieldA: {
type: 'number',
required: true,
default: 1337
}
})
console.log(example.validate({ })) // -> { fieldA: 1337 }
console.log(example.validate({ fieldA: 3 })) // -> { fieldA: 3 }
console.log(example.validate({ fieldA: '3' })) // -> { fieldA: 3 }
console.log(example.validate({ fieldA: 'apple' })) // -> { fieldA: 1337 }
Example of validation:
import model from 'model_json'
const exampleA = new model({
field: {
type: 'string',
valid: str => str.length > 0
}
})
console.log(exampleA.validate({ field: '' })) // Error: Key field did not pass custom valid test, ''.
console.log(exampleA.validate({ field: 'Test' })) // -> { field: 'Test' }
// Valid is applied *after* default is set
// Usage of default on rejection may be forced with a flag as shown
const exampleB = new model({
field: {
type: 'string',
required: true,
default: '',
valid: str => str.length > 0
}
})
console.log(exampleB.validate({ })) // Error: Key field did not pass custom valid test, ''.
console.log(exampleB.validate({ }, { defaultOnReject: true })) // -> { field: '' }
Documentation
Types
Type | Coercion | Explanation
--- | --- | ---
any
| No | No value is disregarded
array
| No | Values which do not return true from Array.isArray
are disregarded
boolean
| Yes | null
is disregarded; true
, 'true'
, 't'
, 'yes'
, 'y'
, 1
, and '1'
are considered true
-- all other values false
function
| No | Type of field must be function
, otherwise disregarded
integer
| Yes | Disregards values which are NaN
when parsed; does not allow alphabetic characters while parsing; removes any precision (15.2
-> 15
)
number
| Yes | Disregards values which are NaN
when parsed; does not allow alphabetic characters while parsing
object
| No | Type of field must be object
, otherwise disregarded
string
| Yes | Disregards null
; all other values are coerced to a string via .toString()
Methods
- (constructor)(< object >schema)
- schema - object - The schema for this model.
- key1 - object - Specifies the type, validation, default, etc for a key within the schema.
- type - string - The type of this value, see Types above.
- preparse - function - Synchronously allows modification of the value before type coercion
- postparse - function - Synchronously allows modification of the value after type coercion
- required - boolean - Specify whether or not this value is required to be provided to the schema
- default - (as specified) - Specifies a default value when the value is required but missing from the schema
- valid - function - Synchronously or Asynchronously validates a value after coercion (use validate and validateAsync respectively)
- ... key2 ...
- ... key3 ...
- ...
- key1 - object - Specifies the type, validation, default, etc for a key within the schema.
- schema - object - The schema for this model.
- validate(< object >object [, < object >config]) - (object) - Synchronously applies the schema to the provided object adhering to the provided options.
- object - object - The object which the schema is being applied to.
- config - object - The options which alter schema application.
- defaults - boolean - Sets keys which are not
required
but missing from the schema to their provided default. - defaultOnReject - boolean - Sets a key to its provided default value when it fails its
valid
check.
- defaults - boolean - Sets keys which are not
- validateAsync(< object >object [, < object >config]) - (Promise) - Asynchronously applies the schema to the provided object adhering to the provided options (required when schema contains valid clauses which return a
Promise
).- object - object - see validate
- config - object - see validate