Skip to content

Latest commit

 

History

History
235 lines (185 loc) · 7.19 KB

API.md

File metadata and controls

235 lines (185 loc) · 7.19 KB
Raw

API Reference

Creation

vlad(schema) -> function(value)

Create a synchronous validation function. This function will take in a value and throw a ValidationError or return the validated value. This is the function you should use for nested validation.

vlad.sync(schema) -> function(value)

The same as vlad(schema).

vlad.promise(schema) -> function(value)

An alias for vlad(schema)

vlad.callback(schema) -> function(value, callback)

Create a new validation function. This function will take in a value to validate and a node-style callback that must accept an error as the first argument and the validated value as the second arguments.

vlad.middleware([prop,] schema) -> function(req, res, next)

Create a new middleware styled function to validate a certain property on a request. By default the prop field will be "query".

This can be useful when parsing and normalizing basic queries in express, especially since vlad will automatically attempt to parse "true", "false", and numeric strings to their actual values.

Validation

The 4 basic types of validation are by sync, promise, callback, or middleware.

// sync
var validator = vlad(schema); // or vlad.sync(schema)
try {
  const value = validate(object);
  // handle value
} catch (e) {
  // handle error
}

// promise
var validator = vlad.promise(schema);
validator(object)
    .then(/* handle value */)
    .catch(/* or handle error */);

// callback
var validator = vlad.callback(schema);
validator(object, function(err, value) {
    if (err) {
        // handle error
    } else {
        // handle value
    }
});

// middleware
var validator = vlad.middleware('query', {
    limit: vlad.integer.default(10).within(5, 15),
    offset: vlad.integer.default(0).min(0)
});

router.get('/', validator, function(req, res, next) {
    // GET /?limit=7
    req.query.limit === 7;
    req.query.offset === 0;
});

router.use(function(err, req, res, next) {
    // handle 'err'
});

Schema

The vlad function can parse several types of schema when creating validation functions. Invalid types should automatically throw a vlad.SchemaFormatError.

Property

The most common type of schema is a property. More information about them can be found below.

Function

You can pass in your own custom validation function to vlad. Through it, you must synchronously throw an error or return a value.

// wrong
var validator = vlad(function(value) {
    if (isNotValid(value)) throw vlad.FieldValidationError("Value is bad.");
    // no value returned!
});

// right
var validator = vlad(function(value) {
    if (isNotValid(value)) throw vlad.FieldValidationError("Value is bad.");

    return value;
});
Object

To validate object values, you can pass in a plain object.

Note: you can only use properties or functions as the values, not other objects. To nest objects wrap the subobject in a validation function.

var validator = vlad({
    a: vlad.string,
    nested: vlad({
        a: vlad.string
    })
});

Property Types

Base Property

All property types extends this base property.

  • property.default(value) - value to default to (default value skips validation)
  • property.required - force this value to not be undefined. Will fallback to default value if default value is set.
  • property.catch - catch all validation errors by making value equal to default (even if undefined)
  • property.is, property.has, property.and - filler words
vlad.string
  • vlad.string.maxLength(length) (or .max(length))
  • vlad.string.minLength(length) (or .min(length))
  • vlad.string.within(min, max)
  • vlad.string.pattern(regex)
  • vlad.string.format(format) - from added formats
vlad.addFormat(name, handler)

Lets you add in special string formats using more complex validation than regexes. The handler function gets the current value and returns the error string if there was an error.

vlad.number
  • will attempt to automatically parse strings to numbers
  • vlad.number.multipleOf(value)
  • vlad.number.max(max)
  • vlad.number.min(min)
  • vlad.number.within(min, max)
vlad.integer
  • extends vlad.number
  • will attempt to automatically parse strings to integers
  • only accepts integer values.
vlad.boolean
  • no special options
  • will automatically parse "true" and "false"
vlad.date
  • Will attempt to convert all values to a Date object
vlad.array
  • vlad.array.min(length) (or .minLength(length))
  • vlad.array.max(length) (or .maxLength(length))
  • vlad.array.of(validator)
var subType = vlad(vlad.string); // or just `vlad.string`
var validator = vlad(vlad.array.of(subType));
vlad.enum(options)
  • options - array of possible values
vlad.equals(value [, message])
  • value - value it must equal
  • message - optional error message
vlad.any
  • Matches any data type.
vlad.or([])
  • Tries each validator passed to it.
vlad(vlad.or([
  vlad.string, //supports properties
  val => {     // or functions
    if (val === null) throw new Error('invalid');
    return val;
  }
]))

Errors

vlad.ValidationError(message)
  • err.message
  • err.toJSON() - returns a nice JSON representation of error.
vlad.FieldValidationError(message)
  • extends ValidationError
  • err.message
vlad.GroupValidationError(message, fields)
  • extends ValidationError
  • err.message
  • err.fields - object of ValidationErrors
vlad.ArrayValidationError(message, fields)
  • extends GroupValidationError
  • err.message
  • err.fields - array of ValidationErrors
vlad.SchemaFormatError(message)
  • err.message