express-joi-validation

A middleware for validating express inputs using Joi schemas. Features include:

TypeScript support.
Specify the order in which request inputs are validated.
Replaces the incoming req.body, req.query, etc and with the validated result
Retains the original req.body inside a new property named req.originalBody. . The same applies for headers, query, and params using the original prefix, e.g req.originalQuery
Chooses sensible default Joi options for headers, params, query, and body.
Uses peerDependencies to get a Joi instance of your choosing instead of using a fixed version.

Install

You need to install joi with this module since it relies on it in peerDependencies.

npm i express-joi-validation joi --save

Example

A JavaScript and TypeScript example can be found in the example/ folder of this repository.

Usage (JavaScript)

const Joi = require('joi')
const app = require('express')()
const validator = require('express-joi-validation').createValidator({})

const querySchema = Joi.object({
  name: Joi.string().required()
})

app.get('/orders', validator.query(querySchema), (req, res) => {
  // If we're in here then the query was valid!  
  res.end(`Hello ${req.query.name}!`)
})

Usage (TypeScript)

For TypeScript a helper ValidatedRequest and ValidatedRequestWithRawInputsAndFields type is provided. This extends the express.Request type and allows you to pass a schema using generics to ensure type safety in your handler function.

import * as Joi from 'joi'
import * as express from 'express'
import {
  ContainerTypes,
  // Use this as a replacement for express.Request
  ValidatedRequest,
  // Extend from this to define a valid schema type/interface
  ValidatedRequestSchema,
  // Creates a validator that generates middlewares
  createValidator
} from 'express-joi-validation'

const app = express()
const validator = createValidator()

const querySchema = Joi.object({
  name: Joi.string().required()
})

interface HelloRequestSchema extends ValidatedRequestSchema {
  [ContainerTypes.Query]: {
    name: string
  }
}

app.get(
  '/hello',
  validator.query(querySchema),
  (req: ValidatedRequest<HelloRequestSchema>, res) => {
    // Woohoo, type safety and intellisense for req.query!
    res.end(`Hello ${req.query.name}!`)
  }
)

You can minimise some duplication by using joi-extract-type.

NOTE: this does not work with Joi v16+ at the moment. See this issue.

import * as Joi from 'joi'
import * as express from 'express'
import {
  // Use this as a replacement for express.Request
  ValidatedRequest,
  // Extend from this to define a valid schema type/interface
  ValidatedRequestSchema,
  // Creates a validator that generates middlewares
  createValidator
} from 'express-joi-validation'

// This is optional, but without it you need to manually generate
// a type or interface for ValidatedRequestSchema members
import 'joi-extract-type'

const app = express()
const validator = createValidator()

const querySchema = Joi.object({
  name: Joi.string().required()
})

interface HelloRequestSchema extends ValidatedRequestSchema {
  [ContainerTypes.Query]: Joi.extractType<typeof querySchema>

  // Without Joi.extractType you would do this:
  // query: {
  //   name: string
  // }
}

app.get(
  '/hello',
  validator.query(querySchema),
  (req: ValidatedRequest<HelloRequestSchema>, res) => {
    // Woohoo, type safety and intellisense for req.query!
    res.end(`Hello ${req.query.name}!`)
  }
)

API

Structure

module (express-joi-validation)
- createValidator(config)

createValidator(config)

Creates a validator. Supports the following options:

passError (default: false) - Passes validation errors to the express error hander using next(err) when true
statusCode (default: 400) - The status code used when validation fails and passError is false.

validator.query(schema, [options])

Creates a middleware instance that will validate the req.query for an incoming request. Can be passed options that override the config passed when the validator was created.

Supported options are:

joi - Custom options to pass to Joi.validate.
passError - Same as above.
statusCode - Same as above.

validator.body(schema, [options])

Creates a middleware instance that will validate the req.body for an incoming request. Can be passed options that override the options passed when the validator was created.