obey
v5.0.1
Published
Data modelling and validation library
Downloads
3,058
Readme
Obey
Asynchronous Data Modelling and Validation.
Contents
- Introduction
- Installation
- API Documentation
- Rules
- Models
- Validation
- Definition Properties
- Types
- Allow
- Modifiers
- Creators
- Strict Mode
- Asynchronous Validation
- Contributing
- License
Introduction
Obey is a library for creating asynchronous data models and rules. The core goal of the project is to provide methods for managing data models both through synchronous and asynchronous validation and alignment using Promises.
Installation
Obey can be installed via NPM: npm install obey --save
API Documentation
Detailed API Documentation is available for assistance in using, modifying, or contributing to the Obey library.
Rules
Rules are core definitions of how a value should be validated:
const obey = require('obey')
const firstName = obey.rule({ type: 'string', min: 2, max: 45, required: true })
Models
Models allow for creating validation rules for entire object schemas. The following demonstrates a model being created with Obey:
const obey = require('obey')
const userModel = obey.model({
id: { type: 'uuid', creator: 'uuid', required: true },
email: { type: 'email', required: true },
password: { type: 'string', modifier: 'encryptPassword', required: true },
passwordConfirm: { type: 'string', equalTo: 'password' },
fname: { type: 'string', description: 'First Name' },
lname: { type: 'string', description: 'Last Name', empty: true },
suffix: { type: 'string', allowNull: true },
phone: { type: 'phone:numeric', min: 7, max: 10 },
phoneType: { type: 'string', requiredIf: 'phone' },
carrier: { type: 'string', requiredIf: { phoneType: 'mobile' }},
// Array
labels: { type: 'array', values: {
type: 'object', keys: {
label: { type: 'string' }
}
}},
// Nested object
address: { type: 'object', keys: {
street: { type: 'string', max: 45 },
city: { type: 'string', max: 45 },
state: { type: 'string', max: 2, modifier: 'upperCase' },
zip: { type: 'number', min: 10000, max: 99999 }
}},
// Key-independent object validation
permissions: { type: 'object', values: {
type: 'string'
}},
account: { type: 'string', allow: [ 'user', 'admin' ], default: 'user' }
})
Validation
Using the example above, validation is done by calling the validate
method and supplying data. This applies to both individual rules and data models:
userModel.validate({ /* some data */ })
.then(data => {
// Passes back `data` object, includes any defaults set,
// generated, or modified data
})
.catch(error => {
// Returns instance of ValidationError
// `error.message` => String format error messages
// `error.collection` => Raw array of error objects
})
The validate method returns a promise (for more information see [Asynchronous Validation](#Asynchronous Validation)). A passing run will resolve with the data, any failures will reject and the ValidationError
instance will be returned.
Validating Partials
The validate
method has the ability to validate partial data objects:
// Allow partial validation by supplying second argument with `partial: true`
userModel.validate({ /* some (partial) data */ }, { partial: true })
The default for the partial option is false
, but passing true
will allow for validation of an object containing a subset (i.e. will not throw errors for required
properties).
The common use-case for validating partials is PATCH
updates.
Note: Running a partial validation will prevent running creator
's on any properties
Validation Error Handling
Validation errors are collected and thrown after all validation has run. This is as opposed to blocking, or stopping, on the first failure.
As shown in the example above, the catch
will contain an instance of ValidationError
with two properties; message
and collection
. The message
simply contains the description of all errors.
The collection
is an array of objects containing details on each of the validation errors. For example, if a type
evaluation for phone:numeric
was performed and the value failed the following would be contained as an object in the array:
{
type: 'phone', // The type evaluation performed
sub: 'numeric', // The sub-type (if applicable)
key: 'primaryPhone', // Name of the property in the model
value: '(555) 123-4567', // The value evaluated
message: 'Value must be a numeric phone number' // Message
}
Definition Properties
When setting definitions for rules or model properties, the following are supported:
type
: The type of value with (optional) sub-type see Typeskeys
: Property ofobject
type, indicates nested object propertiesvalues
: Defines value specification for arrays or key-independent objectsmodifier
: uses a method and accepts a passed value to modify or transform data, see Modifierscreator
: uses a method to create a default value if no value is supplied, see Creatorsempty
: Set totrue
allows empty string or array, (defaultfalse
)default
: The default value if no value specifiedmin
: The minimum character length for a string, lowest number, or minimum items in arraymax
: The maximum character length for a string, highest number, or maximum items in arrayrequired
: Enforces the value cannot beundefined
during validation (defaultfalse
)requiredIf
: Enforces the value cannot beundefined
if a value exists or matches a given value ({ propertyName: 'requiredValue' }
), or any of a list of values ({ propertyName: [ 'val1', 'val2' ] }
)requiredIfNot
: Enforces the value cannot beundefined
if a value does not exist or match a given value ({ propertyName: 'requiredValue' }
), or any of a list of values ({ propertyName: [ 'val1', 'val2' ] }
)equalTo
: Enforces the value to be the same as the corresponding fieldallow
: Object, array or single value representing allowed value(s), see AllowallowNull
: Accepts a null value or processes specified typestrict
: Enable or disable strict checking of an object, see Strict Modedescription
: A description of the propertyjexl
: One or more objects containing anexpr
string for validating data against Jexl expressions. See Jexl Validation.
Types
Reference: Type Documentation
Types are basic checks against native types, built-ins or customs. The library includes native types (
boolean
,number
,string
,array
, andobject
) as well other common types. A list of built-in types is contained in the source.
The type
definition can also specify a sub-type, for example:
phone: { type: 'phone:numeric' }
The above would specify the general type phone
with sub-type numeric
(only allowing numbers).
Adding New Types
New types can be added to the Obey lib with the obey.type
method. Types can be added as single methods or objects supporting sub-types:
Adding Single-Method Type
obey.type('lowerCaseOnly', context => {
if (!/[a-z]/.test(context.value)) {
context.fail(`${context.key} must be lowercase`)
}
})
Adding Type with Subs
obey.type('password', {
default: context => {
if (context.value.length < 6) {
context.fail(`${context.key} must contain at least 6 characters`)
}
},
strong: context => {
if (!context.value.test((/^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])[0-9a-zA-Z]{8,}$/))) {
context.fail(`${context.key} must contain a number, letter, and be at least 8 characters`)
}
}
})
The definition object contains keys that indicate the subtype (or default
if no sub-type specified).
Each method will be passed a context
object at runtime. This object has the following properties:
def
: The entire rule for the property in the modelsub
: The sub-type (if provided)key
: The name of the property being tested (if an element in a model/object)value
: The value to testfail
: A function accepting a failure message as an argument
The above would add a new type which would then be available for setting in the model configuration for any properties.
password: { type: 'password', /* ...additional config... */ }
/* ...or... */
password: { type: 'password:strong', /* ...additional config... */ }
Types can be synchronous or asynchronous. For example, if a unique email is required the following could be used to define a uniqueEmail
type:
obey.type('uniqueEmail', context => {
return someDataSource.find({ email: context.value })
.then(record => {
if (record.length >= 1) {
context.fail(`${context.key} already exists`)
}
})
}
Types can return/resolve a value, though it is not required and is recommended any coercion be handled with a modifier.
Regardless of if a value is returned/resolved, asynchronous types must resolve. Errors should be handled with the context.fail()
method.
Allow
The allow
property in definition objects accepts three formats; string
, array
or object
The string
and array
methods are straight-forward:
// Only allow 'bar'
foo: { type: 'string', allow: 'bar' }
// Allow 'buzz', 'bazz', 'bizz'
fizz: { type: 'string', allow: [ 'buzz', 'bazz', 'bizz' ] }
The object
representation of the allow
property gives the ability to store enums alongside the model structure making sharing/reuse of the objects simplified:
const allowedStatuses = {
'prog': 'in progress',
'comp': 'completed',
'arch': 'archived'
}
// Allow statuses
{ status: { type: 'string', allow: allowedStatuses } }
In the above example, the model would only accept the keys (prog
, comp
, arch
) during validation.
Modifiers
Modifiers allow custom methods to return values which are modified/transformed versions of the received value.
Creating Modifiers
Modifiers can be added to the Obey lib with the obey.modifier
method:
obey.modifier('upperCase', val => val.toUpperCase())
When the model is validated, the value in any fields with the upperCase
modifier will be transformed to uppercase.
Similar to types, modifiers may be synchronous (returning a value) or asynchronous (returning a promise).
Creators
Creators allow custom methods to return values which set the value similar to the
default
property. When validating, if a value is not provided the creator assigned will be used to set the value.
Creating Creators
Creators can be added to the Obey lib with the obey.creator
method:
obey.creator('timestamp', () => new Date().getTime())
The above example would add a creator named timestamp
which could be assigned as shown below:
created: { type: 'number', creator: 'timestamp' }
When the model is validated, if no created
property is provided the timestamp
creator will assign the property a UTC timestamp.
Similar to modifiers, creators may be synchronous (returning a value) or asynchronous (returning a promise).
Strict Mode
By default, Obey enforces strict matching on objects; meaning an object must define any keys that will be present in the data object being validated.
To disable strict mode on a rule or object set the strict
property to false:
foo: { type: 'object', strict: false, keys: { /* ... */ } }
To disable strict mode on a model pass the (optional) strict argument as false
:
const model = obey.model({ /* definition */ }, false)
Jexl Validation
Obey allows for validating data against Jexl expressions via the jexl
rule:
obey.model({
exprVal: {
type: 'string',
jexl: [{
expr: "value == root.testVal.nestedObjArray[.name == 'some specific name'].payload",
message: "Do not seek the treasure" // Optional expression-specific error message
}]
},
testVal: {
type: 'object',
keys: {
nestedObjArray: {
type: 'array',
values: {
type: 'object',
keys: {
name: { type: 'string' },
payload: { type: 'string' }
}
}
}
}
}
})
Note: the jexl
validator uses value
and root
as its context keys for the specific value being validated and the corresponding data, respectively, so expression strings should be constructed accordingly.
If necessary, a preconfigured Jexl instance can be passed in before the model is constructed, in order to utitlize user-defined transforms in validation:
const obey = require('obey')
const jexl = require('jexl')
jexl.addTransform('upper', val => val.toUpperCase(val))
obey.use('jexl', jexl)
obey.model({/* ...definition... */})
Asynchronous Validation
The goal with Obey is to provide more than just standard type/regex checks against data to validate values and models. The ability to write both synchronous and asynchronous checks, creators, and modifiers, and include data coercion in the validation simplifies the process of validation and checking before moving onto data source interactions.
Additionally, with the widespread use of promises, this structure fits well in the scheme of data processing in general:
// Define a model somewhere in your code...
const user = obey.model(/* ...Model Definition... */)
// Use it to validate before creating a record...
user.validate(/* ...some data object... */)
.then(createUser)
.then(/* ...response or other action... */)
.catch(/* ...handle errors... */)
Contributing
Contibutions to Obey are welcomed and encouraged. If you would like to make a contribution please fork the repository and submit a PR with changes. Acceptance of PR's is based on a review by core contributors. To increase the likelihood of acceptance please ensure the following:
- The PR states the reason for the modification/addition to the API in detail
- All tests are passing and coverage is at, or near, 100%
- The code submitted follows the conventions used throughout the library
- JSDoc is in place and generates via
npm run doc
- Any needed documentation on the
README
is supplied
License
Obey was originally created at TechnologyAdvice in Nashville, TN and released under the MIT license.