# mongoose-guard

> mongoose-guard validates request bodies against your existing Mongoose schemas, with a per-route allowlist of fields, strict type checks without casting, and your schema's own validation rules.

Key facts:

- npm package `mongoose-guard`, MIT licensed, for Node.js 20+ with Mongoose 8 or 9.
- It reads an existing Mongoose model. You do not write a second schema.
- Each route declares an `allow` list of dot paths. Fields outside the list are rejected (or stripped with `unknown: "strip"`).
- Types are checked strictly. `"25"` is not accepted for a Number field.
- Imports: `mongoose-guard` (core), `mongoose-guard/express` (Express 4 and 5 middleware), `mongoose-guard/web` (standard `Request`, for Next.js, Hono, Remix, SvelteKit).
- It does not validate query strings, route params or headers, and it does not run on edge runtimes such as Cloudflare Workers.

Start here:

- [What is mongoose-guard?](https://amritanshurai.github.io/mongoose-guard/introduction/): A beginner-friendly explanation of mongoose-guard, the problem it solves, how it fits next to Mongoose, and the words used throughout these docs.
- [Installation](https://amritanshurai.github.io/mongoose-guard/installation/): How to install mongoose-guard with npm, pnpm, yarn or bun, the supported Node.js, Mongoose and Express versions, and which import path to use.
- [Quick start](https://amritanshurai.github.io/mongoose-guard/quick-start/): Build a working Express signup route protected by mongoose-guard, step by step from an empty folder, and see the exact responses for valid and invalid requests.
- [When to use it (and when not to)](https://amritanshurai.github.io/mongoose-guard/when-to-use/): An honest guide to the projects and routes where mongoose-guard fits well, the ones where Zod or another validator is the better choice, and how to mix them.

Concepts:

- [How validation works](https://amritanshurai.github.io/mongoose-guard/concepts/validation-pipeline/): The five checks mongoose-guard runs on every request body, in order, what each one catches, and why structural problems stop the request before Mongoose rules run.
- [The allow list](https://amritanshurai.github.io/mongoose-guard/concepts/allowlist/): What the allow option is, why every route needs its own, how dot paths reach into nested objects and arrays, and how mongoose-guard catches typos in allow entries at startup.
- [Strict types](https://amritanshurai.github.io/mongoose-guard/concepts/strict-types/): Why mongoose-guard never casts values the way Mongoose does, what that means for numbers, booleans and dates in JSON, and what to do when your input really is strings.
- [Results and issues](https://amritanshurai.github.io/mongoose-guard/concepts/results-and-issues/): The shape of a mongoose-guard result, what each field of an issue means, how paths are written for nested data and arrays, and how to show issues to users.

Guides:

- [Express](https://amritanshurai.github.io/mongoose-guard/guides/express/): Use mongoose-guard as Express 4 or 5 middleware. Middleware order, req.validated, error handling, routers, authentication, role-based allow lists and body size limits.
- [Next.js, Hono, Remix and SvelteKit](https://amritanshurai.github.io/mongoose-guard/guides/web-request/): Use mongoose-guard/web with any framework that gives you a standard Request object, with examples for Next.js route handlers, Hono, Remix or React Router actions, and SvelteKit endpoints.
- [Without a framework](https://amritanshurai.github.io/mongoose-guard/guides/without-a-framework/): Use the framework-free core of mongoose-guard, createGuard and validateBody, in Fastify, Koa, NestJS, queue workers, scripts and tests.
- [Partial updates (PATCH)](https://amritanshurai.github.io/mongoose-guard/guides/partial-updates/): Use partial mode for PATCH routes so only the fields the client sent are validated, and understand how required fields behave in full and partial mode.
- [Strip mode](https://amritanshurai.github.io/mongoose-guard/guides/strip-mode/): Use unknown "strip" to remove unknown and forbidden fields silently instead of rejecting the request, when to choose it over the default reject mode, and what strip mode still rejects.
- [Nested data](https://amritanshurai.github.io/mongoose-guard/guides/nested-data/): How mongoose-guard validates nested objects, sub-schemas, arrays of sub-schemas, arrays of primitives, Maps and Mixed fields, and how to allow only part of a nested object.
- [Custom error responses](https://amritanshurai.github.io/mongoose-guard/guides/custom-errors/): Change the status code and JSON shape mongoose-guard sends for invalid requests, with onInvalid in Express and with your own response in web frameworks, including RFC 9457 problem details.
- [TypeScript](https://amritanshurai.github.io/mongoose-guard/guides/typescript/): Types that ship with mongoose-guard, how req.validated is typed in Express, how to give validated data a precise type with InferSchemaType, and module resolution support.
- [Testing](https://amritanshurai.github.io/mongoose-guard/guides/testing/): Test mongoose-guard allow lists and validation without a database, test Express routes end to end, and catch allow-list typos in CI.

Reference:

- [API reference](https://amritanshurai.github.io/mongoose-guard/reference/api/): Complete reference for every export of mongoose-guard, mongoose-guard/express and mongoose-guard/web, with signatures, parameters, return values and errors.
- [Options](https://amritanshurai.github.io/mongoose-guard/reference/options/): Every option mongoose-guard accepts, allow, partial, unknown and onInvalid, with defaults, allowed values and examples.
- [Issue codes](https://amritanshurai.github.io/mongoose-guard/reference/issue-codes/): The six issue codes mongoose-guard returns, invalid_body, unsafe_key, unknown_field, forbidden_field, invalid_type and invalid_value, with every message, cause and fix.
- [Type rules](https://amritanshurai.github.io/mongoose-guard/reference/type-rules/): The exact values mongoose-guard accepts for every Mongoose schema type, including String, Number, Boolean, Date, ObjectId, Decimal128, BigInt, Int32, Double, UUID, Buffer, Mixed, arrays and Maps.
- [Allow list paths](https://amritanshurai.github.io/mongoose-guard/reference/allowlist-paths/): The exact syntax and resolution rules for entries in mongoose-guard's allow option, including nested objects, sub-schemas, document arrays and the errors thrown for invalid entries.

Understand:

- [mongoose-guard vs Zod, Joi, express-validator and Mongoose](https://amritanshurai.github.io/mongoose-guard/understand/comparison/): An honest comparison of mongoose-guard with Zod, Joi, express-validator and Mongoose's built-in validation, covering defaults, casting, unknown fields, allow lists and when each one is the better choice.
- [Security](https://amritanshurai.github.io/mongoose-guard/understand/security/): What mongoose-guard protects against, mass assignment, prototype pollution, MongoDB operator injection and type confusion, and the threats it does not cover, with what to use instead.
- [How it works](https://amritanshurai.github.io/mongoose-guard/understand/how-it-works/): Inside mongoose-guard. How it compiles allow lists, reads Mongoose schema internals, walks the request body, and runs Mongoose validation on a throwaway document, including the Mongoose quirks it works around.
- [Limitations](https://amritanshurai.github.io/mongoose-guard/understand/limitations/): Everything mongoose-guard does not do or does differently than you might expect, including discriminators, query validation, type coercion, hooks, async validators and runtime support.

Help:

- [FAQ](https://amritanshurai.github.io/mongoose-guard/faq/): Short, direct answers to the most common questions about mongoose-guard, what it is, how it compares to Zod, which frameworks it supports, and how it behaves.
- [Troubleshooting](https://amritanshurai.github.io/mongoose-guard/troubleshooting/): Fixes for common mongoose-guard problems, from every request failing with invalid_body to GuardConfigError at startup, numbers rejected as strings, req.validated being undefined and TypeScript import errors.
- [Changelog](https://amritanshurai.github.io/mongoose-guard/changelog/): Release history of mongoose-guard.

## Documentation Sets

- [Abridged documentation](https://amritanshurai.github.io/mongoose-guard/llms-small.txt): a compact version of the documentation for mongoose-guard, with non-essential content removed
- [Complete documentation](https://amritanshurai.github.io/mongoose-guard/llms-full.txt): the full documentation for mongoose-guard

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation