@smallwins/validate

Parameter validation for builtins and custom types. Accepts params and a schema and returns an array of Errors or false.

var validate = require('@smallwins/validate')

function hi(params, callback) {
  var schema = {
    'name':       {required:true,  type:Object},
    'name.first': {required:true,  type:String},
    'name.last':  {required:false, type:String}
  }
  var errors = validate(params, schema)
  if (errors) {
    callback(errors)
  }
  else {
    callback(null, 'hi ' + params.first)
  }
}

// logs: null, hi brian
hi({name:{first:'brian', last:'leroux'}}, console.log)

// logs: [ [ReferenceError: missing required param name.first] ]
hi({name:{}}, console.log)

:dizzy: considerations

• For testing an Object that presumably came from a JSON payload
• Thusly, primarily concerned with JSON value types: Object, String, Number, Array and Boolean
• Custom types are easily supported
• Extra custom types bundled: Email, ISO, DateRange and UUID
• Designed to test keys and nested keys
• Optionally validate required
• Optionally validate min and max for String, Number and Array builtin types (and easily implement for custom types / see DateRange for an example)

things it does not do :thumbsdown:

• Mutate things with: serialization, formatting or defaults
• Nested subtypes (eg. the things in an array)
• Localized error messages

:punch::two_hearts: further justifications

There are a tonne of libraries that do things like this but also do a whole lot more. This library deliberately limits its scope:

• Make errback style param contract validation super clean and simple
• Work primarily with builtins but easily extend
• Provide a nice API for usage (hence returning a falsy null instead of a truthy empty array [] for the return value of validate and making the schema type validation minimalist without sacrificing capability.)

terse style example :point_left::eyes::point_left:

var validate = require('@smallwins/validate')

function sum(params, callback) {
  // define our assumed params
  var errors = validate(params, {
    x: {required:true, type:Number},
    y: {required:true, type:Number}
  })
  // err first! it'll be null w/ good input
  callback(errors, errors? null : params.x + params.y)
}

sum({}, console.log)
// logs
// [[ReferenceError: missing required param x], [ReferenceError: missing required param y]] null

sum({x:1, y:2}, console.log)
// logs
// null 2

:love_letter: api :thought_balloon::star2:

validate(params, schema)

• params a plain Object that we assume came from JSON
• schema a plain Object for describing the shape of the data
• callback (optional) Node style errback function(err, params) {}

:key: schema

• required either true or false (or leave it out completely)
• type can be one of Object, String, Number, Array and Boolean
• min any Number (or anything allowed by a custom type)
• max any Number (or anything allowed by a custom type)

:package: bundled custom types

• UUID
• Email
• ISO
• DateRange

Example usage of custom types:

var validate = require('@smallwins/validate')
var lambda = require('@smallwins/lambda')
// pull in the custom types
var UUID = require('@smallwins/validate/uuid')
var Email = require('@smallwins/validate/email')
var ISO = require('@smallwins/validate/iso')
var DateRange = require('@smallwins/validate/daterange')

// use the schema per builtins
function valid(event, callback) {
  var schema = {
    'params.id': {required:true, type:UUID},
    'body.email': {required:true, type:Email},
    'body.created': {required:true, type:ISO},
    'body.duration': {required:true, type:DateRange, min:'2016/01/01', max:'2017/01/01'}
  }
  validate(event, schema, callback)
}

function save(event, callback) {
  // performs save
  callback(null, event)
}

exports.handler = lambda(valid, save)

Check out the examples for more on custom types and ranges (and the tests).