mongoose-zod-error-formatter

A robust and lightweight utility package to format error objects from Mongoose, Zod, and general errors into consistent, user-friendly responses for Express.js applications written in TypeScript. Perfect for API error handling, validation, and debugging.

Features

• Format Mongoose validation errors with detailed paths and messages
• Format Mongoose cast errors (e.g., invalid ObjectId)
• Format Zod validation errors with clear path and messages
• Format simple/general errors into structured responses
• TypeScript-ready with strict types for error messages and responses
• Easily integrate into any Express middleware or error handler

Installation

npm install mongoose-zod-error-formatter
# or
yarn add mongoose-zod-error-formatter

Usage

1. Format Mongoose Validation Error

import mongoose from "mongoose";
import { formatValidationError } from "mongoose-zod-error-formatter";

try {
  // Some mongoose operation that fails validation
} catch (error) {
  if (error instanceof mongoose.Error.ValidationError) {
    const formatted = formatValidationError(error);
    console.log(formatted);
  }
}

2. Format Mongoose Cast Error (e.g., invalid ObjectId)

import mongoose from "mongoose";
import { formatCastError } from "mongoose-zod-error-formatter";

try {
  // Some mongoose operation that throws CastError
} catch (error) {
  if (error instanceof mongoose.Error.CastError) {
    const formatted = formatCastError(error);
    console.log(formatted);
  }
}

3. Format Zod Validation Error

import { z, ZodError } from "zod";
import { formatZodError } from "mongoose-zod-error-formatter";

const schema = z.object({
  username: z.string().min(3),
  age: z.number().int().positive(),
});

try {
  schema.parse({ username: "ab", age: -1 });
} catch (error) {
  if (error instanceof ZodError) {
    const formatted = formatZodError(error);
    console.log(formatted);
  }
}

4. Format Simple or Custom Error

import { formatSimpleError } from "mongoose-zod-error-formatter";
import { Request } from "express";

const fakeReq = {
  originalUrl: "/api/users",
} as Request;

const error = new Error("Something went wrong");
error.statusCode = 500;

const formatted = formatSimpleError(fakeReq, error);
console.log(formatted);

API Reference

| Function | Description | Input | Output | |------------------------|--------------------------------------------------|----------------------------|----------------------| | formatValidationError| Formats Mongoose validation errors | mongoose.Error.ValidationError | IErrorResponse | | formatCastError | Formats Mongoose cast errors (invalid ObjectId) | mongoose.Error.CastError | IErrorResponse | | formatZodError | Formats Zod validation errors | ZodError | IErrorResponse | | formatSimpleError | Formats simple/general errors with Express Request context | Request, Error & statusCode? | IErrorResponse |

Types

export interface IErrorMessages {
  path?: string | number;
  message: string;
}

export interface IErrorResponse {
  statusCode: number;
  message: string;
  errorMessages: IErrorMessages[];
}

Contributing

Contributions, issues, and feature requests are welcome! Feel free to open issues or submit pull requests.

License

MIT © Nurul Islam Rimon

Made with ❤️ by Nurul Islam Rimon