Koajv

Koa middleware factory to validate, querystring, body payload, route params

You can find examples of how to use this library. You can also look at the tests scenarios in the tests directory to get running examples to use.

Breaking changes :

• v1.0.0 -> v2.0.0 : The validation error format has changed

Minor changes :

• v2.0.0 -> v2.1.0 : Add support for custom keywords

Body validation :

In this example the call can looks like : POST http://host.com/example/body

const koajv = require('koajv')
 
const ajvOptions = {
  allErrors: true,
  useDefaults: true,
  schemaId: 'auto',
  keywords: {
    trim: {
      type: 'string',
      modifying: true,
      compile: function (sch, parentSchema) {
        return function(data, dataPath, parentData, property) {
          if(typeof data === 'string') {
            if(sch) {
              parentData[property] = data.trim()
            }
            return true
          }
          return false
        }
      }
    }
  }
}
 
const schema = {
  id: 'userSchema',
  type: 'object',
  additionalProperties: false,
  properties: {
    id: { type: 'integer' },
    name: { type: 'string' },
    category: { type: 'string', pattern: '^Teacher|Student$' },
  }
}
 
const bodyValidatorMiddleware = koajv.bodyValidator(schema) // Wille check ctx.request.body
 
const validator = koajv.createValidator(schema) // return a method
 
try {
  validator({ invalid: 'test' }) // If the object is not matching the schema an execption is thrown
} catch (err) {
 
}
 
router.post('/example/body', bodyValidatorMiddleware, routeHandler)

Querystring validation :

In this example the call can looks like : GET http://host.com/example/query?name=test&category=Student

const koajv = require('koajv')
 
const ajvOptions = {
  allErrors: true,
  useDefaults: true,
  schemaId: 'auto',
}
 
const schema = {
  id: 'querySchema',
  type: 'object',
  additionalProperties: false,
  properties: {
    name: { type: 'string' },
    category: { type: 'string', pattern: '^Teacher|Student$' },
  }
}
 
const queryValidatorMiddleware = koajv.queryValidator(schema, ajvOptions) // Will check ctx.request.query
 
router.get('/example/query', queryValidatorMiddleware, routeHandler)

Params validation :

In this example the call can looks like : GET http://host.com/example/params/teacher

const koajv = require('koajv')
 
const ajvOptions = {
  allErrors: true,
  useDefaults: true,
  schemaId: 'auto',
}
 
const schema = {
  id: 'paramsSchema',
  type: 'object',
  additionalProperties: false,
  properties: {
    category: { type: 'string', pattern: `^teacher|student$`},
  }
}
 
const paramsValidatorMiddleware = koajv.paramsValidator(schema, ajvOptions) // Will check ctx.params
 
router.get('/example/params/:category', paramsValidatorMiddleware, routeHandler)

Generic validation :

You can also instantiate a validator function by using the facotry method `koajv.createValidator()'

const koajv = require('koajv')
 
const ajvOptions = {
  allErrors: true,
  useDefaults: true,
  schemaId: 'auto',
}
 
const schema = {
  id: 'userSchema',
  type: 'object',
  additionalProperties: false,
  properties: {
    id: { type: 'integer' },
    name: { type: 'string' },
    category: { type: 'string', pattern: '^Teacher|Student$' },
  }
}
 
const validator = koajv.createValidator(schema, ajvOptions) // return a method
 
try {
  validator({ invalid: 'test' }) // If the object is not matching the schema an execption is thrown
} catch (err) {
 
}

Error Handling :

Here is a simple example of middleware to catch koajv errors :

app.use(async(ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.status
    ctx.body = {
      message: err.message,
      code: err.code || 'UNKNOWN_ERROR',
    }
  }
})

Custom keywords :

To add custom keywords you can pass it as an options

const koajv = require('koajv')
 
const ajvOptions = {
  allErrors: true,
  useDefaults: true,
  schemaId: 'auto',
  keywords: {
    trim: {
      type: 'string',
      modifying: true,
      compile: function (sch, parentSchema) {
        return function(data, dataPath, parentData, property) {
          if(typeof data === 'string') {
            if(sch) {
              parentData[property] = data.trim()
            }
            return true
          }
          return false
        }
      }
    }
  }
}
 

Tests

To Launch the tests :

• run : $ npm install
• run : $ npm test
• run : $ npm run watch : It launch test when you change the code

(The tests will run a koa app on port 9000 be sure that this port is available)

Code Coverage

After running $ npm test you can access the code coverage report here : ./coverage/index.html