express-joi-validation
Advanced tools
validate express application inputs and parameters using joi
A middleware for validating express inputs using Joi schemas. Features include:
req.body, req.query, etc and with the validated resultreq.body inside a new property named req.originalBody.
. The same applies for headers, query, and params using the original prefix,
e.g req.originalQuerypeerDependencies to get a Joi instance of your choosing instead of
using a fixed version.You need to install joi with this module since it relies on it in
peerDependencies.
npm i express-joi-validation joi --save
A JavaScript and TypeScript example can be found in the example/ folder of
this repository.
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}!`)
})
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}!`)
}
)
Creates a validator. Supports the following options:
false) - Passes validation errors to the express error
hander using next(err) when true400) - The status code used when validation fails and
passError is false.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.validate.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.
Supported options are the same as validator.query.
Creates a middleware instance that will validate the req.headers for an
incoming request. Can be passed options that override the options passed
when the validator was created.
Supported options are the same as validator.query.
Creates a middleware instance that will validate the req.params for an
incoming request. Can be passed options that override the options passed
when the validator was created.
Supported options are the same as validator.query.
Creates a middleware instance that will validate the outgoing response.
Can be passed options that override the options passed when the instance was
created.
Supported options are the same as validator.query.
Creates a middleware instance that will validate the fields for an incoming
request. This is designed for use with express-formidable. Can be passed
options that override the options passed when the validator was created.
The instance.params middleware is a little different to the others. It must
be attached directly to the route it is related to. Here's a sample:
const schema = Joi.object({
id: Joi.number().integer().required()
});
// INCORRECT
app.use(validator.params(schema));
app.get('/orders/:id', (req, res, next) => {
// The "id" parameter will NOT have been validated here!
});
// CORRECT
app.get('/orders/:id', validator.params(schema), (req, res, next) => {
// This WILL have a validated "id"
})
Supported options are the same as validator.query.
This module uses peerDependencies for the Joi version being used.
This means whatever joi version is in the dependencies of your
package.json will be used by this module.
Validation can be performed in a specific order using standard express middleware behaviour. Pass the middleware in the desired order.
Here's an example where the order is headers, body, query:
route.get(
'/tickets',
validator.headers(headerSchema),
validator.body(bodySchema),
validator.query(querySchema),
routeHandler
);
When validation fails, this module will default to returning a HTTP 400 with
the Joi validation error as a text/plain response type.
A passError option is supported to override this behaviour. This option
forces the middleware to pass the error to the express error handler using the
standard next function behaviour.
See the Custom Express Error Handler section for an example.
It is possible to pass specific Joi options to each validator like so:
route.get(
'/tickets',
validator.headers(
headerSchema,
{
joi: {convert: true, allowUnknown: true}
}
),
validator.body(
bodySchema,
{
joi: {convert: true, allowUnknown: false}
}
)
routeHandler
);
The following sensible defaults for Joi are applied if none are passed:
const validator = require('express-joi-validation').createValidator({
// This options forces validation to pass any errors the express
// error handler instead of generating a 400 error
passError: true
});
const app = require('express')();
const orders = require('lib/orders');
app.get('/orders', validator.query(require('./query-schema')), (req, res, next) => {
// if we're in here then the query was valid!
orders.getForQuery(req.query)
.then((listOfOrders) => res.json(listOfOrders))
.catch(next);
});
// After your routes add a standard express error handler. This will be passed the Joi
// error, plus an extra "type" field so we can tell what type of validation failed
app.use((err, req, res, next) => {
if (err && err.error && err.error.isJoi) {
// we had a joi error, let's return a custom 400 json response
res.status(400).json({
type: err.type, // will be "query" here, but could be "headers", "body", or "params"
message: err.error.toString()
});
} else {
// pass on to another error handler
next(err);
}
});
In TypeScript environments err.type can be verified against the exported
ContainerTypes:
import { ContainerTypes } from 'express-joi-validation'
app.use((err: any|ExpressJoiError, req: express.Request, res: express.Response, next: express.NextFunction) => {
// ContainerTypes is an enum exported by this module. It contains strings
// such as "body", "headers", "query"...
if (err && err.type in ContainerTypes) {
const e: ExpressJoiError = err
// e.g "you submitted a bad query paramater"
res.status(400).end(`You submitted a bad ${e.type} paramater`)
} else {
res.status(500).end('internal server error')
}
})
6.0.0 (13/10/2020)
FAQs
validate express application inputs and parameters using joi
The npm package express-joi-validation receives a total of 13,937 weekly downloads. As such, express-joi-validation popularity was classified as popular.
We found that express-joi-validation demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.