# MongoZod

> MongoDB with a Zod schema as the single source of truth for each document: it validates every write, types every read and defines what each endpoint accepts. The Mongoose alternative built on Zod and the official MongoDB driver.

Install it with `npm install mongozod` (zod, mongodb and bson are peer dependencies). Each page below is Markdown, and the same pages ship in the package, in `node_modules/mongozod/dist/docs/`, at the installed version. All of them in one file: https://mongozod.dev/llms-full.txt.

MongoZod is an independent open-source project. It is not affiliated with, endorsed by or sponsored by MongoDB, Inc. MongoDB® is a registered trademark of MongoDB, Inc.

- [Introduction](https://mongozod.dev/docs.md): MongoZod is a TypeScript library for MongoDB where one Zod schema validates every write, types every read and defines what each endpoint accepts.

## Getting started

- [Why MongoZod](https://mongozod.dev/docs/getting-started/why-mongozod.md): MongoZod as a Mongoose alternative for TypeScript, compared with Mongoose, Typegoose, the driver and Zod by hand and other libraries, the Mongoose issues it solves and when not to use it.
- [Installation](https://mongozod.dev/docs/getting-started/installation.md): Install MongoZod, and the versions of Node.js, TypeScript, Zod and the MongoDB driver it needs.
- [Quick start](https://mongozod.dev/docs/getting-started/quick-start.md): Use Zod with MongoDB in one file, from a model defined by a Zod schema to writes, reads and the queries a client sends.
- [Connection](https://mongozod.dev/docs/getting-started/connection.md): What to set on the MongoClient, on the database user and on the server for an app that uses MongoZod.
- [AI agents](https://mongozod.dev/docs/getting-started/ai-agents.md): Point a coding agent at the docs installed with MongoZod, at the installed version, and the mistakes agents trained on Mongoose tend to make.

## Guides

- [Schemas](https://mongozod.dev/docs/guides/schemas.md): Describe a MongoDB document with a Zod schema, the one source for MongoDB, TypeScript and the API, from its _id and defaults to the types a model takes and returns.
- [Models](https://mongozod.dev/docs/guides/models.md): Define a model with mongozod(), connect it to a database, and reach the driver for what the model does not wrap.
- [Operations](https://mongozod.dev/docs/guides/operations.md): The driver's collection methods as a model wraps them, with their options, results and cursors.
- [Validation](https://mongozod.dev/docs/guides/validation.md): How MongoZod validates MongoDB inserts, updates and upserts with Zod, and the ZodError it throws when a write does not fit.
- [TypeScript](https://mongozod.dev/docs/guides/typescript.md): Type-safe MongoDB queries in TypeScript, with filters, updates, projections and sorts typed by the Zod schema, and the types to pass them through services and repositories.
- [BSON types](https://mongozod.dev/docs/guides/bson-types.md): Zod schemas for MongoDB ObjectId, Decimal128, binary data, UUIDs, dates, sets and GeoJSON, which take them as JSON from clients.
- [Endpoint inputs](https://mongozod.dev/docs/guides/endpoint-inputs.md): Accept MongoDB filters, updates, sorts, projections, populate and search terms from clients safely, limited to what each endpoint declares.
- [Security](https://mongozod.dev/docs/guides/security.md): How the endpoint inputs of MongoZod keep NoSQL operator injection out when an endpoint takes a MongoDB query from a client, and what stays with your application.
- [Pagination](https://mongozod.dev/docs/guides/pagination.md): Keyset pagination of a MongoDB collection with mz.after, built from the Zod schema and the sort, or offset pagination with skip and limit.
- [Populate](https://mongozod.dev/docs/guides/populate.md): Declare the references between MongoDB models and replace the stored ids with the documents they point to, with a typed populate.
- [Virtuals](https://mongozod.dev/docs/guides/virtuals.md): Compute fields from the stored ones when you read, without storing them.
- [Timestamps](https://mongozod.dev/docs/guides/timestamps.md): Fill createdAt when a document is created and updatedAt on every write with the timestamps option.
- [Document types](https://mongozod.dev/docs/guides/document-types.md): Store several types of document in one MongoDB collection with a z.discriminatedUnion, the discriminators of Mongoose, with subtypes up to three levels.
- [Aggregation](https://mongozod.dev/docs/guides/aggregation.md): Run aggregation pipelines, validate and type their results with a schema, and check the leading $match stages.
- [Sync](https://mongozod.dev/docs/guides/sync.md): Create the indexes a model declares and apply a MongoDB $jsonSchema validator generated from its Zod schema, with sync().
- [Transactions](https://mongozod.dev/docs/guides/transactions.md): Run several operations atomically with the driver's withSession and withTransaction, passing the session to each operation.
- [Plugins](https://mongozod.dev/docs/guides/plugins.md): Add plugins to a model, pass the options and the context they take, and call the methods they add.

## Plugins

- [Soft delete](https://mongozod.dev/docs/plugins/soft-delete.md): Soft delete for MongoDB, which marks documents as deleted instead of removing them and hides them from reads and updates, with the softDelete plugin.
- [Auto index](https://mongozod.dev/docs/plugins/auto-index.md): Create the indexes a model declares on its first operation, with the autoIndex plugin, for development, tests and serverless platforms.
- [Writing plugins](https://mongozod.dev/docs/plugins/writing-plugins.md): Write a plugin with definePlugin, with its fields, fills, options, context, hooks, middleware and methods.

## Migrating from Mongoose

- [Migrating from Mongoose](https://mongozod.dev/docs/mongoose.md): Move a Mongoose app to MongoZod one model at a time, on the connection Mongoose already opened, with a prompt for your coding agent.
- [Mongoose cheatsheet](https://mongozod.dev/docs/mongoose/cheatsheet.md): Each Mongoose feature with its MongoZod equivalent, from schema types and options to queries, populate, virtuals, timestamps, middleware and indexes.
- [Differences from Mongoose](https://mongozod.dev/docs/mongoose/differences.md): What works another way than in Mongoose, such as explicit writes instead of save(), filters without casting, __v and an explicit sync().

## Recipes

- [IDs](https://mongozod.dev/docs/recipes/ids.md): Choose how the _id of each document is generated, compare ObjectIds, and add the id virtual that Mongoose had.
- [Multi-tenant](https://mongozod.dev/docs/recipes/multi-tenant.md): Give each tenant its own database, with db as a function that returns the database of the current request.
- [Repositories](https://mongozod.dev/docs/recipes/repositories.md): Write generic helpers, such as paginate, and services per model, typed with ReadOf, FilterOf and InsertOf.
- [Transforms](https://mongozod.dev/docs/recipes/transforms.md): Hash a password before it is stored, compute a field from others, and check the database inside a transaction.
- [Schema migrations](https://mongozod.dev/docs/recipes/schema-migrations.md): Add a field or a virtual to a collection that already has documents, and list the documents that don't fit first.
- [HTTP APIs](https://mongozod.dev/docs/recipes/http-apis.md): Take a filter in a GET request, read an id from the route, turn errors into responses and log them readably.
- [Search](https://mongozod.dev/docs/recipes/search.md): Search a term in several fields, with MongoDB's text search, MongoDB Search, or mz.term for a search box without either.
- [Streams](https://mongozod.dev/docs/recipes/streams.md): Read many documents batch by batch with for await and Node.js streams, and follow changes with change streams.
- [Dates and money](https://mongozod.dev/docs/recipes/dates-and-money.md): Store a date without a time as a string, store money as Decimal128, and compare decimals in filters.
- [Schema patterns](https://mongozod.dev/docs/recipes/schema-patterns.md): Model a tree with a recursive schema, and write to a key of a record that is only known at runtime.

## API reference

- [mongozod](https://mongozod.dev/docs/api/mongozod.md): The reference of the `mongozod` entry point, with mongozod(), the model, its operations and cursors, definePlugin and the types.
- [mongozod/mzod](https://mongozod.dev/docs/api/mzod.md): The reference of mongozod/mzod, the builders of endpoint inputs and the BSON field types of a document schema.