xType

Simple object type checking

xType is just a simple way to quickly validate that an object is of a certain structure. It's goal is to be lightweight and fast.

Notes:

• You currently can't inherit required properties using a check function.

Usage

xType exposes the following functions:

• define
• get
• defineFn
• getFn
• guard
• undefine

xtype.define(<name>, <type>, <options>)

• name: name of the definition. Can only be used once.
• type: the raw type of the object, such as 'object' or 'array'
• options: an object or function that is used for validation

xtype.undefine(<name>)

• name: name of the function to remove

xtype.defineFn(<name>, <types...>)

• name: name of the function.
• types: each argument of the function is given one argument

xtype.get(<name>)

• name: name of the function

xtype.getFn(<name>)

• name: name of the

xtype.guard(<name>, <fn>)

• name: name of the function definition
• fn: function to run if validation passes

Definitions

You use xType by creating 'definitions' that document what an object should consist of.

xtype.define('address', 'object', {
    keys: {
        street: 'string',
        city: 'string'
    }
});

var test = define('user', 'object', {
    keys: {
        id: 'number',
        name: 'string',
        address: 'address'
    }
});

test({
    id: 10,
    name: 'John',
    address: {
        number: 27,
        street: 'Road'
    }
});

Options

Keys

Keys allow you to specify what keys an object can have to be valid. If the type does not match, or if an object has a key that is not in 'keys', then it will return false.

var test = define('special_object', 'object', {
    keys: {
        id: 'number'
        name: 'string'
    }
});

test({ id: 10, name: 'word' }); // true
test({ id: 'word', name: 10 }); // false

test = define('special_array', 'array', {
    keys: {
        0: 'number',
        1: 'string'
    }
});

test([10, 'word']); // true
test(['word', 10]); // false

Required Keys

By default, all keys are optional. However, if you need to specify that an object is valid if it contains a key, you can set it as required.

Do this by prefixing the type with an asterisk.

var test = define('required', 'object', {
    keys: {
        id: '*number'
    }
});

test({id: 20}); // true
test({}); // false

Other

Other makes the test more flexible - meaning that it will ignore any properties on an object that

test = define('standard', 'object', {
    keys: {
        id: 'number'
    }
});

test({ id: 20, name: 'word' }); // false

test = define('flexible', 'object', {
    other: true,
    keys: {
        id: 'number'
    }
});

test({ id: 20, name: 'word' }); // true

All

Setting options.all means that all properties of the object must be that type.

This can only be used by itself, and cannot be used with 'keys', 'other' or 'inheritance'.

test = define('array_of_strings', 'array', {
    all: 'string'
});

test(['an', 'array', 'of', 'strings']); // true
test([1, 2, 3, 4, 5]); // false

Primitive Types

xType is very flexible about what types are. So you can easily use it with other type validation libraries.

If you supply a type and a function, they will be used to create a function that firsts check that an object is of that type, and if so will then check it against your function.

var email = define('email', 'string', function (str) {
    return !! str.match(/.+@.+\..+/);
});

email('[email protected]'); // true
email('johnsmitcom');    // false
email(30);               // false
email({{}});             // false


var validator = require('validator');
var uppercase = define('uppercase', 'string', validator.isUppercase);
uppercase('TRUE');
uppercase('FaLsE');
uppercase('false');

You can just have a completly raw function that will do all the checking. This is particulary useful for combining it with other libraries that already do type checking for you.

var array = define('array', function (obj) {
    Object.prototype.toString.call(obj) === '[object Array]';
});

Inheritance

xType allows you to split definitions in multiple sections, so you don't have to repeat yourself all the time.

xtype.define('model', 'object', {
    keys: {
        id: 'number',
        name: 'string'
    }
});

xtype.define('task', 'object', {
    inherit: 'model',
    keys: {
        completed: 'boolean',
        notes: 'string'
    }
});

xtype.define('taskArray', 'array', {
    all: 'task'
});

xtype.define('list', 'object', {
    inherit: 'model',
    keys: {
        tasks: 'taskArray'
    }
});

var task = xtype.get('task');
var list = xtype.get('list');

task({
    id: 20,
    name: 'Just a task',
    completed: true,
    notes: 'Finish xType'
}); // true

list({
    id: 10,
    tasks: [
        {
            id: 1,
            name: 'a task in a list',
            completed: false,
            notes: ''
        },
        {
            id: 2,
            name: 'another task',
            completed: false,
            notes: 'with some notes'
        }
    ]
}); // true

Fancy Inheritance

I haven't thought of a good name for this yet.

Basically you can choose which definition to inherit, based on the object.

To use it you set inherit as an possible definitions to inherit, as well as setting check to a function that accepts a single argument: object.

inherit can be an object or an array, but whatever the check function returns will be used to try and access the property from it.

xtype.define('a', 'object', {
    keys: {
        model: 'string'
    }
});

xtype.define('b', 'object', {
    keys: {
        model: 'number'
    }
});

xtype.define('c', 'object', {
    keys: {
        model: 'boolean'
    }
});


xtype.define('thing', 'object', {
    inherit: ['a', 'b', 'c'],
    check: function (obj) {
        switch (obj.type) {
            case 'a': return 0;
            case 'b': return 1;
            case 'c': return 2;
        }
    }
});

var thing = xtype.get('thing');

thing({
    type: 'a',
    model: 'string'
}); // true

thing({
    type: 'b',
    model: 30
}); // true

thing({
    type: 'c',
    model: true
}); // true

thing({
    type: 'd',
    model: true
}); // false - type d doesn't exist

Function Definitions

This is used to create definitions for function arguments.

defineFn

The first argument is the name of the function. The rest are the types of each argument. Every argument is required by default.

xtype.defineFn('my_fn', 'string', 'number');

Optional Properties

Prefix type with a ~ symbol.

It is best to use this only the last argument, as xType won't do anything special if you make the first argument optional.

var test = xtype.defineFn('my_fn', 'string', 'number', '~function');

test('word', 30); // true
test('word', 30, function () {}); // true

test = xtype.defineFn('my_fn_2', '~string', '~number');

test(); // true
test('word'); // true
test(undefined, 30); // true
test(30); // false

getFn

Use this to get a function definition by it's name.

Will throw an error if the definition doesn't exist.

var test = xtype.getFn('my_fn');

guard

Use this to 'guard' a function, that will only run if validation passes.

xtype.defineFn('my_fn', 'string', 'number');

var fn = function (string, number) {
    // can assume that string is actually a string
    // and that number is really a number
};

// Guard fn
var guard = xtype.guard('my_fn', fn);

// will call fn
guard('word', 30);

// will not call fn
guard();
guard('word');
guard(undefined, 30);