Dezer NPM | npm.io

dezer

Small utility to help library authors verify configuration objects adherence to a configuration schema.

What dezer isn't

A way to circumvent the dynamic nature of javascript's type system.
A way to enforce every object in your app to have a certain shape during runtime.
A replacement or substitute for tools and languages like typescript or flow.
A utility that can be called thousands of times, or be used in a performance intensive part of your app.
Dezer shouldn't be used with proxies, it was made to easily validate ordinary objects.

What dezer is

A utility that helps library & tool authors easily validate configuration objects given to their constructors by foreign code.

Features

Tiny (1.5KB minified, 800B minified and gzip compressed).
Simple API (dezer contains one function vet).
No dependencies.
Can run in any ES5 supporting environment.

Usage

add dezer to your project's dependencies.

# npm
npm install dezer --save
# yarn
yarn add dezer

then require it in code.

const dezer = require('dezer');
// Or you can use ES module syntax
import * as dezer from 'dezer';

API

`dezer.vet(obj: any, schema: rule[], ignoreInvalidKeys?: boolean): vetError[]`

obj : The object to be tested.

schema : an array of rule objects (schema rules)

a rule object must contains the following properties:

    {
        // The property's key
        key: string | symbol,

        // The required type, must be a lower case string returned by the typeof  
        // operator (for example: number, boolean, string), can also be an array
        // it can also be an array of type strings.
        type: string | string[],

            // This method is called after the initial
            // if this function doesn't return a truthy
            // the vet will fail and a 'user_rejected'
            // error will be pushed to the list of 
            // violations
            additional?: (key?: string | symbol, value?: any, requiredType?: string | string[]) => boolean,


            // This method is called if the property
            // passes the initial type checks (and
            // if additional returns true if defined)
            onPass?: (key?: string | symbol, value?: any, requiredType?: string | string[]) => void,

            // Called if the object fails
            // to adhere to this rule.
            onError?: (key?: string | symbol, value?: any, errorType?: string) => void

            // if set to true then a "missing_key" error will
            // not be pushed to the schema list violation
            // if the property doesn't exist
            // on the object.
            optional?: boolean

        }
    ```
    * errorType can be one of four strings `"type_mismatch"`,
    `"missing_key"`, `"invalid_key"`, `"user_rejected"`.

    * all rule properties and function arguments of rule methods are optional except for the type & key properties.

ignoreInvalidKeys (optional): if set to a truthy value dezer will ignore keys that exist on the object but are not defined in the schema, by default this is set to false and dezer will report keys on the object & not defined on the schema as a violation.

vetError[]: vet returns an array of vetError objects, vet will always return an array so if the returned array is of 0 length then the object has passed the vet process.

* a vetError object contains the following properties:
    ```
        {
            // the type of schema violation
            // that occurred
            errorType: 'type_mismatch' | 'missing_key' | 'invalid_key' | 'user_rejected',

            // The key of the faulty property
            faultyKey: string | symbol
        }
    ```

note: when given incorrect parameters (such as obj not being an actual object or schema not being an array of rule objects), the vet function will throw an error!.