koa-context-validator

A robust context validator for koajs. Use Joi behind the scenes.

Installation

$ npm install koa-context-validator joi

Usage

query Validation

import Koa from 'koa';
import validator, { Joi } from 'koa-context-validator';

const app = new Koa();

app.use(
  validator({
    query: Joi.object().keys({
      username: Joi.string().required(),
    }),
  }),
);

body Validation

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import validator, { Joi } from 'koa-context-validator';

const app = new Koa();

app.use(bodyParser());
app.use(
  validator({
    body: Joi.object().keys({
      username: Joi.string().required(),
      age: Joi.number().required(),
    }),
  }),
);

headers Validation

import Koa from 'koa';
import validator, { Joi } from 'koa-context-validator';

const app = new Koa();

app.use(
  validator({
    headers: Joi.object()
      .keys({
        username: Joi.string().required(),
      })
      .unknown(),
  }),
);

With koa-compose

import Koa from 'koa';
import compose from 'koa-compose';
import validator, { Joi } from 'koa-context-validator';

const app = new Koa();

app.use(
  compose([
    validator({
      query: Joi.object().keys({
        username: Joi.string().required(),
      }),
    }),
    async (ctx) => {
      ctx.body = ctx.request.query;
    },
  ]),
);

With koa-mount

import Koa from 'koa';
import mount from 'koa-mount';
import validator, { Joi } from 'koa-context-validator';

const app = new Koa();

app.use(
  mount(
    '/api',
    validator({
      query: Joi.object().keys({
        username: Joi.string().required(),
      }),
    }),
  ),
);

With @koa/router

import Koa from 'koa';
import Router from '@koa/router';
import validator, { Joi } from 'koa-context-validator';

const router = new Router();
router.get(
  '/api/:username',
  validator({
    params: Joi.object().keys({
      username: Joi.string().required(),
    }),
  }),
  async (ctx) => {
    ctx.body = ctx.params;
  },
);

const app = new Koa();
app.use(router.middleware());

With options

import Koa from 'koa';
import validator, { Joi } from 'koa-context-validator';

app.use(
  validator(
    {
      query: Joi.object().keys({
        username: Joi.string().required(),
      }),
    },
    {
      abortEarly: true,
      allowUnknown: false,
      cache: true,
      stripUnknown: true,
      debug: false,
    },
  ),
);

Asynchronous Operations

import Koa from 'koa';
import validator, { Joi } from 'koa-context-validator';

const lookup = async (username) => {
  const user = await db.get('user', username);
  if (!user) {
    throw new Error('Invalid username');
  }
};

app.use(
  validator({
    body: Joi.object().keys({
      username: Joi.string().external(lookup),
    }),
  }),
);

With Joi.ref

import Koa from 'koa';
import validator, { Joi } from 'koa-context-validator';

app.use(
  validator({
    body: Joi.object().keys({
      username: Joi.string().default(Joi.ref('$defaultUsername')),
      age: Joi.number().default(Joi.ref('$defaultAge')),
    }),
  }),
);

Koa 1.x

Use convert.back from koa-convert.

import koa from 'koa'; // koa 1.x
import convert from 'koa-convert';
import validator, { Joi } from 'koa-context-validator';

const app = koa();

app.use(
  convert.back(
    validator({
      query: Joi.object().keys({
        username: Joi.string().required(),
      }),
    }),
  ),
);

API

validator(schema, options?)

schema

Required Type: object

A object which has optional query, body, headers and params schema to validate.

options

Just be passed to Joi's validate function as options:

https://joi.dev/api/?v=17.4.2#anyvalidatevalue-options

Joi

The Joi object from the joi package.

TypeScript

As of version 1.0.0 we've added initial support for TypeScript.

License

MIT © C.T. Lin