obey

Obey

Asynchronous Data Modelling and Validation.

Contents

• Introduction
• Installation
• Rules
• Models
• Validation
  • Validation Error Handling
• Definition Properties
• Types
  • Adding New Types
    • Adding Single-Method Type
    • Adding Type with Subs
• Modifiers
  • Creating Modifiers
• Generators
  • Creating Generators
• Strict Mode
• Asynchronous Validation
• 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 JavaScript Promises.

Installation

Obey can be installed via NPM: npm install obey --save

Rules

Rules are core definitions of how a value should be validated:

import obey from '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:

import obey from 'obey'

const userModel = obey.model({
  id: { type: 'uuid', generator: 'uuid', required: true },
  email: { type: 'email', required: true },
  password: { type: 'string', modifier: 'encryptPassword', required: true },
  fname: { type: 'string', description: 'First Name' },
  lname: { type: 'string', description: 'Last Name', empty: true },
  phone: { type: 'phone:numeric', min: 7, max: 10 },
  // 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.

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: '[phone]', // 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 Types
• keys: Property of object type, indicates nested object properties
• values: Defines value specification for arrays or key-independent objects
• modifier: uses a method and accepts a passed value to modify or transform data, see Modifiers
• generator: uses a method to create a default value if no value is supplied, see Generators
• empty: Set to true allows empty string or array, (default false)
• default: The default value if no value specified
• min: The minimum character length for a string, lowest number, or minimum items in array
• max: The maximum character length for a string, highest number, or maximum items in array
• required: Enforces the value cannot be undefined during validation (default false)
• allow: Array of allowed values or single allowed value
• strict: Enable or disable strict checking of an object, see Strict Mode
• description: A description of the property

Types

Reference: Type Documentaion

Types are basic checks against native types, built-ins or customs. The library includes native types (boolean, number, string, array, and object) 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 model
• sub: The sub-type (if provided)
• key: The name of the property being tested (if an element in a model/object)
• value: The value to test
• fail: 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.

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

Generators

Generators allow custom methods to return values which set the value similar to the default property. When validating, if a value is not provided the generator assigned will be used to set the value.

Creating Generators

Generators can be added to the Obey lib with the obey.generator method:

obey.generator('timestamp', () => new Date().getTime())

The above example would add a generator named timestamp which could be assigned as shown below:

created: { type: 'number', generator: 'timestamp' }

When the model is validated, if no created property is provided the timestamp generator will assign the property a UTC timestamp.

Similar to modifiers, generators 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)

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, generators, 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... */)

License

Obey is developed and maintained by TechnologyAdvice and released under the MIT license.