kinetic-vision / satin-validation js

Repository URL to install this package:

Details

README.md

About Satin Validation

Adds the ability to better validate Backbone Models with specific rules. You are able to extend this to add your own rules as well

Compatibility and Requirements

Backbone v1.3.3

Adding To Your Project

Install this package: npm install satin-validation --save
Extend your Backbone Models to include the validation mixin (see examples below)

Rules

Common Options

All of the rules below will have the following options:

Option	Default	Description
`if`	`({ value, attributes, resource }) => true`	A function to define a conditional validation rule.
`message`	`_.template('<%=error%>)`	Customize the error message returned from the rule. Available variables: `error`, `name`, `value`, `attributes`, `resource`, and all rule options defined.

Presence

Ensure an attribute is defined

Option	Default	Description
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)

Absense

Ensure an attribute is not defined.

This rule has no options

Confirmation

Ensure an attribute equals another attribute

Option	Default	Description
`otherAttributeName`		The name of the other attribute
`caseSensitive`	`true`	Should the comparision be case sensitive

Email

Ensure an attribute is a valid email address

Option	Default	Description
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)

Exclusion

Ensure an attribute is not a blacklisted value

Option	Default	Description
`in`	`[]`	An array of values this attribute cannot be equal to
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)

Inclusion

Ensure an attribute is a whitelisted value

Option	Default	Description
`in`	`[]`	An array of values this attribute can only be equal to
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)

Format

Ensure an attribute matches a custom RegEx pattern

Option	Default	Description
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)
`with`		Pattern that attribute must match
`without`		Pattern that attribute must not match

Length

Ensure an attribute meets a character count requirement

Option	Default	Description
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)
`maximum`		Attribute length must not exceed this length
`minimum`		Attribute length must not be under this length
`in`		Attribute length must be one of the lengths defined in the array
`is`		Attribute length must equal exactly this value

Numericality

Ensure an attribute's numeric value meets a specific criteria. This rule will attempt to cast a string into a number

Option	Default	Description
`allowEmpty`	`false`	Allow empty values like empty strings, arrays, objects, etc
`allowNull`	`false`	Allow this attribute not to be defined (null or undefined)
`onlyIntegers`	`false`	Attribute must be an integer
`onlyFinite`	`false`	Attribute must be a finite number
`greaterThan`		Attribute must be greater than this value
`greaterThanOrEqualTo`		Attribute must be greater than or equal to this value
`equalTo`		Attribute must equal this value
`lessThan`		Attribute must be less than this value
`lessThanOrEqualTo`		Attribute must be less than or equal to this value
`otherThan`		Attribute must equal anything but this value
`odd`		Attribute must be an odd number
`even`		Attribute must be an even number

Examples

import validationMixin from 'satin-validation';
import _ from 'underscore';

const ValidationModel = Backbone.Model.extend(validationMixin);

// Create a new model type and include validation mixin
const PersonModel = ValidationModel.extend({
	defaults: {
		name: 'Untitiled',
		age: 0
	},
	validates: {
		name: {
			precense: {
				message: _.template('You forgot your name!')
			},
			length: { 
				minimum: 5, 
				maximum: 40 
			},
			inclusion: {
				in: ['Bob', 'Rob']
			}
		},
		adult: {
			precense: {}
		},
		age: {
			numerically: {
				greaterThan: 10
				lessThan: 30,
				if({ attributes }) {
					return !attributes.adult;
				}
			}
		}
	}
});

// Create a new model
var bobModel = new PersonModel({
	name: 'Bob',
	age: 50
});

// you can validate manually and listen to model events
bobModel.on('invalid', (model, errors) => {
	console.log(errors);
});
bobModel.on('valid', function(model, errors) => {
	console.log('no errors found!');
});
bobModel.validate();

// use set to validate for errors
bobModel.set({ age: 2 }, { validate: true });

// you can validate certain attributes too
if (bobModel.validate({ age: 10,	name: 'Robert' }) !== true) {
	console.log('Validation failed!');
}