ajv-request-validator

Validates the request object of popular Node.js web frameworks with Ajv.

Installation

npm install ajv-request-validator --save
# or
yarn add ajv-request-validator

Usage

Example with Express:

const RequestValidator = require('ajv-request-validator');
const express = require('express');

const app = express();
const reqValidator = new RequestValidator();

app.post(
  '/user',
  reqValidator.compile({
    body: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }
      }
    }
  }),
  function handler(req, res, next) {
    // Will only be called if `req.body` matches the schema
  }
);

Example with Medley (works exactly the same with Fastify):

const RequestValidator = require('ajv-request-validator');
const medley = require('@medley/medley');

const app = medley();
const reqValidator = new RequestValidator();

app.route({
  method: 'POST',
  path: '/user',
  preHandler: reqValidator.compile({
    body: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }
      }
    }
  }),
  handler: function(req, res) {
    // Will only be called if `req.body` matches the schema
  }
});

API

• new RequestValidator([options])
  • reqValidator.ajv
  • reqValidator.compile(schema[, options])

new RequestValidator([options])

The ajv-request-validator module exports a class. The class constructor can optionally be passed either an Ajv options object or an existing ajv instance.

const RequestValidator = require('ajv-request-validator');

// No options (use Ajv defaults)
const reqValidator = new RequestValidator();

// With Ajv options
const reqValidator = new RequestValidator({
  removeAdditional: true,
  useDefaults: true,
  coerceTypes: true,
});

// With an existing AjV instance
const Ajv = require('ajv');
const ajv = new Ajv();

const reqValidator = new RequestValidator(ajv);

console.log(reqValidator.ajv === ajv); // true

reqValidator.ajv

The ajv instance that the reqValidator will use to compile validation functions.

reqValidator.ajv.addSchema({
  $id: 'user',
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  }
});

reqValidator.ajv.addFormat('userID', /[0-9]{9,16}/);

reqValidator.compile(schema[, options])

• schema - And Object mapping request properties to an Ajv schema.
• options - Optional options Object.
  • options.middleware - If false, a function that directly validates the request object will be returned. Defaults to true.

Compiles a middleware function that validates the req object and then calls next() with the result (either a validation error or null on success). The keys of the schema object correspond with the names of the properties on the req object to validate (usually body or query).

const middleware = reqValidator.compile({
  body: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  }
});

// Use in Express
app.post('/user', middleware, (req, res, next) => {
  // This middleware is only called if `req.body` matches the schema
});

The middleware function is an Express-style middleware function with the signature:

function middleware(req, res, next) { }

When the middleware option is false, .compile() returns a function that directly validates the request object.

function validate(req) { } // Returns `null` or an Error

const validate = reqValidator.compile({
  body: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  }
}, {middleware: false});

app.post('/user', (req, res, next) => {
  const result = validate(req);
  // `result` will be `null` or an Error
});

This is useful when using this module with frameworks that do not have Express-like middleware (see below for more info).

Usage with other frameworks

Since the .compile() method returns an Express-style middleware function, it is not initially compatible with frameworks that have a different middleware signature.

If a different form of middleware is needed, the RequestValidator class can be subclassed to override the .compile() method to return a function compatible with a specific framework.

Here's an example of extending RequestValidator to work with Koa:

const RequestValidator = require('ajv-request-validator');

class KoaRequestValidator extends RequestValidator {
  compile(schema) {
    const validate = super.compile(schema, {middleware: false});

    return async function koaMiddleware(ctx, next) {
      const err = validate(ctx.request);
      if (err !== null) {
        throw err;
      }
      await next();
    };
  }
}

const reqValidator = new KoaRequestValidator();