1.1.0 • Public • Published

    npm Coveralls Travis CI Dependency Status devDependency Status peerDependency Status node License


    Simple, opinionated request validation middleware for koa-router.

    This module currently supports Koa 1 only.


    const Joi = require('joi');
    const router = require('koa-router')();
    const validate = require('koa-joiful-validation');
    router.get('/posts', validate({
        query: {
            offset: Joi.number().integer().positive().default(0).optional()
            limit: Joi.number().integer().positive().default(100).optional()
        body: { /* ... */ },   // for the request body
        params: { /* ... */ }, // for route parameters
    }), function* () {
        // your code here
        this.request.query // contains the original, unmodified query
        this.state.query   // the modified query with defaults applied, etc.

    Why is the result assigned to this.state?

    Koa's request wrapper object automatically serializes all values assigned to its query property. This means that its values can not actually be coerced to other types, e.g. to numbers or booleans. To resolve this the modified data (conversions and defaults applied) are assigned to this.state.body, this.state.query and this.state.params instead.


    Install as usual:

    npm install --save koa-joiful-validation

    Please note that this module has Joi as a peer dependency (practically any version will do).

    In order for the request body validation to work correctly you will want to use koa-bodyparser.


    This module is quite opinionated. If it doesn't suit your needs, feel free to open an issue, create a pull request or just fork the project. In particular, keep the following things in mind:

    • If a validation fails, so does the request with a 422 Unprocessable Entity error.
    • All parameters are required by default (presence: 'required').
    • Additional parameters, i.e. parameters not specified in the schemas, are forbidden by default.
    • When no schema is given, the empty schema is assumed. This means that router.post('/', validate(), ...) will not accept any query, body or url parameters.
    • By default, query and url parameters are converted (e.g., cast to numbers as necessary), but body parameters are not.


    Route Parameters

    If you have route parameters, you need to add them to your validation config in order to work:

    router.get('/entity/:id', validate(), function* () {
        // this won't work because params.id will be rejected

    So instead, do it like this:

    router.get('/entity/:id', validate({
        params: {
            id: Joi.number().integer().min(1)
    }), function* () {
        // now this.state.params.id is guaranteed to be a positive integer

    If you do not want to actually validate the parameter, simply use Joi.any().

    Custom validation functions

    You can pass a list of custom validation functions as a second parameter:

    router.get('/equalsTen', validate({
        x: Joi.number(),
        y: Joi.number()
    }, [
        function () {
            // 'this' is the regular koa context
            const { x, y } = this.state.params;
            if (+ y !== 10) {
                // Joi already converted the parameters from strings to numbers
                return 'x plus y must equal ten!';
    ]), function* () {
        // ...

    These functions are run in sequence after the schema validations (and only if those succeed). If a function returns a string, that validation is considered to have failed and the string becomes the error message. Any other return value is interpreted as a success.

    The functions are executed in the same context as the middleware itself so you have access to this.request, this.state etc.

    If your validation is asynchronous, simply use a generator:

    router.get('/:id', validate({
        params: { id: Joi.number() }
    }, [
        function* () {
            const entity = yield this.db.findOne(this.state.params.id);
            return entity.isSpecial ? 'too special!' : entity;
    ]), function* () {
        // ...

    Please note that throwing an error from a validation function will abort the request with a 500 Internal Server Error.


    The values given in the configuration object are automatically passed to Joi.object().keys() if they are not already Joi schemas. In other words, the following two statements are equivalent:

    validate({ query: { x: Joi.number() } });
    validate({ query: Joi.object().keys({ x: Joi.number() }) });


    npm i koa-joiful-validation

    DownloadsWeekly Downloads






    Last publish


    • pigulla