node-vat v0.0.9

vat

vat - Validate and Transform using schemas.

vat is a joi inspired library for data transformation and validation. vat's tiny size (< 2kb gzipped) and extensibility makes it perfect to embed in web pages.

Usage

Simple

A simple single value schema:

let ageSchema = vat.number().min(0).required();
...
let age = getAge();
let result = ageSchema.validate(age);
// result.error is populated with any errors that are returned
// result.value is populated with any transformed values that are returned.

The number schema will accept any number or string that can be converted to a number and return its number equivalent.

If getAge return the string "24", vat will set result.value to the number 24. If getAge returns the number 12, result.value will be the number 12.

If getAge returns a string that cannot be converted into a number, or a string/number that is < 0, result.error will contain a TypeError.

Complex types

Complex schemas can be created too:

let userSchema = {
  user_id: vat.string().len(16).required().as('userId'),
  name: vat.string().required(),
  age: vat.number.min(0).required()
};

let userData = getUserData()
let result = vat.validate(userData, userSchema);
// result.error will contain any errors. If an error occurred, result.error.key
// will contain the name of the field that caused the error.
// result.value will contain an object with the transformed values.

Complex schema are used in conjunction with vat.validate. In this example, the input data should contain 3 fields: user_id, name, and age. If validation succeeds, result.value will contain 3 fields: userId, name, and age. If validation fails, result.error will contain the type of validation error, and result.error.key will contain the name of the field that caused the error.

API

See the API docs.

Extend vat

Add a new type

vat allows new types to be registered with vat.register.

const hexSchema = vat.string().test((val) => {
  return /^[0-9a-f]+$/gI.test(val);
});
vat.register('hex', hexSchema);
...

// use the hex schema from the function shortcut.
let result = vat.hex().validate('deadbeef')

Extend an existing type

vat allows new functions to be added to existing types. This is how plugins should extend existing types so that extensions are available to all callers of the type.

vat.any().extend({
  equal(expected) {
    return this.test((val) => {
      return val === expected;
    });
  }
});
// `equal` is now available to all callers of `vat.any()`

Create a new type by cloning and extending an existing type

vat allows new types to be created by cloning and extending an existing type. This is how plugins should extend an existing type to create a new type with extra functions.

vat.register('assert', vat.any().clone().extend({
  equal(expected) {
    return this.test((val) => {
      return val === expected;
    });
  }
}));
// Unlike the previous example, `equal` is not available to
// callers of `vat.any()`, only to callers of `vat.assert()`.

Installation

bower

bower install vat

vat is available in <bower_directory>/vat/vat.min.js. vat can be used with both CommonJS and AMD module loaders and is available under the window.VAT namespace otherwise.

npm

TBD

Author

• Shane Tomlinson
• shane@shanetomlinson.com
• https://shanetomlinson.com
• http://github.com/shane-tomlinson
• @shane_tomlinson

Get involved

Any and all pull requests will be reviewed and considered.

Specific needs:

• New types packaged as plugins. In particular:
  • email
  • guid
  • dates (esp ISO8601)
  • credit card numbers

Credit

Thanks go to the developers of joi, it's a beautiful library to work with.

Thanks also go to Phil Booth and Vijay Budhram for their extensive feedback when defining the initial API.

License

This software is available under version 2.0 of the MPL:

https://www.mozilla.org/MPL/