mongoose-zod-error-formatter

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