Express Joi Validations

Common errors

• JoiValidationError: "body" is not allowed to be empty

  cause An empty request body was sent, but the Joi schema for `body` marked all fields as required, or didn't allow for an empty object.
  fix Ensure that the client sends a non-empty request body if required by the schema, or update the Joi schema to allow optional fields or an empty object using `.optional()` or `.allow({})`.

• TypeError: Cannot read properties of undefined (reading 'isJoi')

  cause This typically occurs if the error handling middleware expects a Joi error structure but receives a different type of error, often because `throwErrors` was not set to `true`.
  fix Verify that `throwErrors: true` is configured where validation is performed, allowing the `express-joi-validations` middleware to throw Joi-specific errors that your error handler can then catch and process.

• Error: Invalid Joi Schema

  cause The Joi schema object passed to a validation helper (e.g., `validateBody`) is not a valid Joi schema instance.
  fix Ensure that the schema is correctly defined using `Joi.object({})`, `Joi.string()`, etc., and is a valid Joi schema object before passing it to the validation middleware.

Warnings

• gotcha By default, validation errors are not thrown. Instead, they are attached to `request.validationErrors`. To throw errors for standard Express error handling, you must set the `throwErrors: true` option during middleware initialization or per helper function.
  Fix: Initialize `expressJoiValidations({ throwErrors: true })` globally or pass `{ throwErrors: true }` as a Joi option to individual validation helper functions. Consider using `express-async-errors` alongside this if using asynchronous routes.
• gotcha The package can optionally overwrite the original `req.body`, `req.query`, etc., with the validated data. If `overwriteRequest` is `false` (default), validated data is available in `request.validationValues`, requiring explicit access or type assertions in TypeScript.
  Fix: Either set `overwriteRequest: true` in the middleware configuration if you want the original request properties to be mutated, or consistently access validated data from `req.validationValues`.
• gotcha This package is at version 0.1.0 and has not been updated in over two years (as of May 2024). Compatibility with newer versions of Joi or Express, especially those introducing breaking changes, might not be actively maintained, potentially leading to unexpected behavior or security vulnerabilities with future dependency updates.
  Fix: Exercise caution when upgrading `express` or `joi` dependencies. Thoroughly test existing validations after dependency updates. Consider alternative, more actively maintained Joi-Express validation libraries if long-term stability with latest versions is critical.

Install

• npm install express-joi-validations npm
• yarn add express-joi-validations yarn
• pnpm add express-joi-validations pnpm

Imports

• validate
  wrong:

  const validate = require('express-joi-validations');

  correct:

  import validate from 'express-joi-validations';

  This is the default export for the 'out of the box' combined validation middleware.
• expressJoiValidations
  wrong:

  const { expressJoiValidations } = require('express-joi-validations');

  correct:

  import { expressJoiValidations } from 'express-joi-validations';

  Used to initialize the middleware with custom global configurations like `throwErrors` or `overwriteRequest`.
• validateBody
  wrong:

  import validateBody from 'express-joi-validations/validateBody';

  correct:

  import { validateBody } from 'express-joi-validations';

  Specific helper functions like `validateBody`, `validateParams`, `validateQuery`, `validateHeaders` are named exports. `Joi` itself is also exported from the package for convenience.
• Joi
  wrong:

  import Joi from 'joi';

  correct:

  import { Joi } from 'express-joi-validations';

  The package re-exports the Joi instance it uses, ensuring consistency. It's generally recommended to import Joi directly from the 'joi' package for flexibility with versions, but this is provided as a convenience.

Quickstart

This quickstart demonstrates setting up an Express server with multiple Joi validations for a PUT request, including headers, parameters, and body, and integrates a basic error handling middleware.

import express, { Request, Response, NextFunction } from 'express';
import { Joi, validateHeaders, validateParams, validateBody, expressJoiValidations } from 'express-joi-validations';

const app = express();
app.use(express.json()); // Required to parse JSON request bodies

// Optionally configure global settings for all validations
app.use(expressJoiValidations({ throwErrors: true, overwriteRequest: false }));

const userToken = Joi.object({
  authorization: Joi.string().regex(/^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_.+/=]*$/).required(),
});

const postId = Joi.object({
  id: Joi.string().hex().length(24).required(),
});

const postBody = Joi.object({
  title: Joi.string().required().trim().min(5),
  content: Joi.string().required().trim().min(10),
  tags: Joi.array().items(Joi.string()).optional()
});

// Example route with chained validations
app.put(
  '/posts/:id',
  validateHeaders(userToken),
  validateParams(postId),
  validateBody(postBody, { allowUnknown: false }), // Joi options can be passed per validator
  (req: Request, res: Response) => {
    // If throwErrors is true, an error handler middleware will catch validation errors.
    // Otherwise, validation results (errors, values) are on req.validationErrors and req.validationValues
    const validatedData = (req as any).validationValues; // Cast to 'any' or extend Request type if not using `overwriteRequest`
    res.status(200).json({ message: 'Post updated successfully', data: validatedData });
  }
);

// Global error handler for thrown validation errors (if throwErrors: true)
app.use((err: any, req: Request, res: Response, next: NextFunction) => {
  if (err && err.error && err.error.isJoi) {
    // A Joi validation error
    return res.status(400).json({ type: err.type, message: err.error.toString() });
  }
  next(err); // Pass on to other error handlers
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));