koa-req-validator

koa-req-validator

A node-validator based request validation middleware for Koa. Unlike other libraries, this middleware provides a declarative API and enables access to the full power of node-validator. Here is a taste of it:

router.post('/users', validate({
    email: ['require', 'isEmail', 'Invalid email address'],
    password: ['require', 'isLength(6, 32)', 'Password must be between 6 and 32 characters']
  }), function *(next) {
     ...
  }
)

// To validate properties of an object
router.post('/users', validate({
    'user.name': ['require', 'Name is required'],
    'user.address.state': ['require', 'State is required']
  }), function *(next) {
    ...
  }
)

Usage

Basic

import validate from 'koa-req-validator'

router.post(path, validate(opts), ...)

Options

opts is an object specifying the fields and their validation rules.

• Each key is a field name in the post data (e.g. 'name', 'user.name') with optional search scopes: header (alias headers), query, body and params. Field name and scopes are separated by :. If no scope is specified, all scopes are searched.

• Value is a rule array with the last element being an error message. A rule can be any of the supported methods of node-validator or a custom validator function(value: *, ...args: Array<*>, ctx: KoaContext): Promise<boolean>|boolean. value is the value to be validated from one of the scopes. args are additional arguments that can be declared for the validator (see the isLength example above). ctx is the Koa context.

If a field has no value, it won't be validated. To make a field required, add the special required rule (or its alias isRequired). If there are validation failures, the middleware invokes ctx.throw() with status code 400 and all error messages.

Examples

import validator from 'validator'

// Add custom validator
validator['validateUserName'] = async (username, group, ctx) => {
  // 1st arg: username is the value to be validate
  // 2nd...2nd to last args: group is the extra value passed to isNewUserName
  // last arg: ctx Koa context
  return boolean | Promise<boolean>
}

validate({
  // Find email from request.body and validate
  'email:body': ['require', 'isEmail', 'Invalid email address'],

  // Find password in all scopes, use the first non-empty value to validate
  'password': ['require', 'Password is required'],

  // Find birthday from request.query or request.body
  'birthday:query:body': ['isDate', 'Invalid birthday'],

  // Find username in all scopes
  'username': ['validateUserName', 'Invalid username'],
})

Route decorators

You can combine this middleware with route decorators, for example:

import validate from 'koa-req-validator'
import bodyParser from 'koa-bodyparser'

@controller('/users', convert(bodyParser()))
export default class extends Ctrl {

  @post('', validate(opts))
  async register(ctx, next) {
    ...
  }
}

Test

npm install
npm test