mongoose-zod-error-formatter/README.md

A powerful error formatter utility for Mongoose and Zod validation errors, designed for Express.js applications. Simplify and unify your API error handling with structured, user-friendly error messages.

# mongoose-zod-error-formatter

[![npm version](https://img.shields.io/npm/v/mongoose-zod-error-formatter.svg)](https://www.npmjs.com/package/mongoose-zod-error-formatter)  
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

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

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

---

## Usage

### 1. Format Mongoose Validation Error

```ts
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)

```ts
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

```ts
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

```ts
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

```ts
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