\n\n---\n\nMongoat is a thin, extensible, and type-safe ODM (Object Document Mapper) for MongoDB in Node.js/TypeScript. It sits on top of the official `mongodb` driver **without hiding it**: full CRUD on typed models, schemas as plain objects or decorators, server-side JSON Schema validation, pre/post transformation hooks, versioned migrations with a CI-ready CLI, and Proxy-based method gating — productivity of an ODM while keeping full control of the native driver.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n - [Connecting to MongoDB](#connecting-to-mongodb)\n - [Defining a Model](#defining-a-model)\n - [Basic CRUD Usage](#basic-crud-usage)\n- [Migrations](#migrations)\n- [Full Documentation](#full-documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Features\n\n- **Thin ODM** — a typed layer over the official `mongodb` driver, not a replacement for it\n- **Full CRUD** on typed models: `insert`/`insertMany`, `find`/`findById`/`findMany`, `update`/`updateMany`, `delete`/`deleteMany`, `total`, `aggregate`, `bulkWrite`\n- **Schemas as objects or decorators** — a plain `$jsonSchema`-shaped object, or a class with `@Schema`/`@Prop`; both compile to the same server-side validator\n- **Pre/post hooks** for transforming documents and reacting to operation results\n- **Server-side validation** via MongoDB `$jsonSchema` — enforced by the database, not just at the app layer\n- **Production-ready migrations** — versioned `up`/`down` files, transactional runs, a distributed lock, and a CLI built for CI (`--dry-run`, `status --json`, tiered exit codes)\n- **Injection-safe by design** — an always-on `$where` guard, opt-in `sanitizeFilter` for untrusted input, sanitized error hierarchy (`MongoatError` and subclasses)\n- **Native escape hatch** — `getCollection()`/`getClient()`/`getDb()` for direct, unrestricted access to the native driver whenever you need it\n- **Type-safe** end to end, with generics tied to your document schema\n- **Dual CJS/ESM** package, zero required runtime dependencies beyond `mongodb`/`bson`\n\n## Installation\n\n```bash\nnpm install @iamcalegari/mongoat\n\nyarn add @iamcalegari/mongoat\n\npnpm add @iamcalegari/mongoat\n```\n\nRequires Node.js `^20.19.0 || >=22.12.0`. The `mongodb` v7 driver comes along as a regular dependency — no separate install.\n\n## Quick Start\n\n### Connecting to MongoDB\n\n```ts\nimport { Database } from '@iamcalegari/mongoat';\n\nexport const database = new Database({\n dbName: 'mongoat-example',\n});\n\nawait database.connect();\n```\n\n`DatabaseConfig` extends the driver's own `MongoClientOptions`, so anything the\n`MongoClient` accepts can be set here and is forwarded on `connect()`. Mongoat\nsupplies defaults and your config overrides them; the only default is\n`ignoreUndefined: true`.\n\nMongoat does **not** configure MongoDB's [Stable\nAPI](https://www.mongodb.com/docs/manual/reference/stable-api/) for you — that\nis the application's call, made explicitly:\n\n```ts\nimport { Database, ServerApiVersion } from '@iamcalegari/mongoat';\n\nexport const database = new Database({\n dbName: 'mongoat-example',\n serverApi: { version: ServerApiVersion.v1, strict: true },\n});\n```\n\n`strict: true` makes the server reject every command outside Stable API v1.\n`$vectorSearch`, `createSearchIndex` and `listSearchIndexes` are all outside it,\nso an application using Atlas Vector Search must leave `strict` off:\n\n```\nMongoServerError: $vectorSearch is not allowed with 'apiStrict: true' in API Version 1\ncode: 323, codeName: APIStrictError\n```\n\n### Defining a Model\n\n```ts\nimport { Model, METHODS } from '@iamcalegari/mongoat';\nimport type {\n CreateIndexProps,\n ModelValidationSchema,\n SchemaWithDefaults,\n} from '@iamcalegari/mongoat';\n\ninterface UserSchema {\n username: string;\n password: string;\n mail: string;\n firstName: string;\n lastName: string;\n}\n\nconst schema: ModelValidationSchema> = {\n bsonType: 'object',\n properties: {\n username: { bsonType: 'string', description: 'Username of the user' },\n password: { bsonType: 'string', description: 'Password of the user' },\n mail: {\n bsonType: 'string',\n description: 'Mail of the user',\n pattern: '^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\\\.[a-zA-Z0-9-.]+$',\n },\n firstName: { bsonType: 'string', description: 'First name of the user' },\n lastName: { bsonType: 'string', description: 'Last name of the user' },\n insertedAt: { bsonType: 'date', description: 'Date of the user creation' },\n updatedAt: {\n bsonType: 'date',\n description: 'Date of last update of the user',\n },\n },\n required: ['firstName', 'lastName', 'mail', 'password', 'username'],\n};\n\nconst indexes: CreateIndexProps[] = [\n { key: { username: 1, mail: 1 }, name: 'unique_username_mail', unique: true },\n];\n\nexport const User = new Model({\n collectionName: 'users',\n schema,\n indexes,\n validity: true,\n});\n\n// Pre-hook: runs before every insert — a fresh timestamp per document.\nUser.pre(METHODS.INSERT, (ctx) => {\n ctx.document.password = 'hashedPassword';\n (ctx.document as SchemaWithDefaults).insertedAt = new Date();\n});\n```\n\nPrefer decorators? The same schema can be a class — every `@Prop` field is required unless marked `@Optional()`, and `@Schema('users')` supplies the collection name:\n\n```ts\nimport { Model, Optional, Prop, Schema } from '@iamcalegari/mongoat';\n\n@Schema('users')\nclass UserSchema {\n @Prop({ bsonType: 'string', description: 'Username of the user' })\n username!: string;\n\n @Prop({\n bsonType: 'string',\n pattern: '^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\\\.[a-zA-Z0-9-.]+$',\n })\n mail!: string;\n\n @Optional()\n @Prop({ bsonType: ['int', 'null'] })\n age?: number;\n}\n\nexport const User = new Model({\n schema: UserSchema,\n validity: true,\n});\n```\n\nSee [Define a schema with decorators](https://iamcalegari.github.io/mongoat/how-to/decorators) for the full mapping between the two forms.\n\n### Basic CRUD Usage\n\n```ts\nawait database.setupCollections();\n\nconst user = await User.insert({\n username: 'foobar',\n mail: 'foo@bar.com',\n password: 'strongPassword',\n firstName: 'Foo',\n lastName: 'Bar',\n});\n\nawait User.update({ _id: user._id }, { $set: { firstName: 'John' } });\n\nconst users = await User.findMany();\n\nawait User.delete({ username: 'foobar' });\n\nawait database.disconnect();\n```\n\n## Migrations\n\nThe package ships a `mongoat` CLI for versioned, transactional migrations:\n\n```bash\nnpx mongoat create backfill-user-status # scaffold migrations/_backfill-user-status.ts\nnpx mongoat up # apply pending migrations, in order\nnpx mongoat status # applied/pending overview\n```\n\nEvery run executes inside a MongoDB transaction (replica set required) under a distributed lock, so concurrent deploys can't double-apply. For CI there are `--dry-run`, `status --json`, and tiered exit codes. Migrations written in TypeScript need [`tsx`](https://github.com/privatenumber/tsx) as an optional peer dependency; `.js` migrations need nothing extra.\n\n- [Your first migration](https://iamcalegari.github.io/mongoat/tutorials/first-migration) — guided walkthrough\n- [Write and run migrations](https://iamcalegari.github.io/mongoat/how-to/migrations) — the full workflow, including failure modes\n- [CLI reference](https://iamcalegari.github.io/mongoat/cli/) — every command, flag, env var, and exit code\n\n## Full Documentation\n\n**Full documentation → [https://iamcalegari.github.io/mongoat/](https://iamcalegari.github.io/mongoat/)**\n\nThe site is the source of truth for guides, API reference, and the migration guide — this README only covers the essentials to get started:\n\n- [Tutorials](https://iamcalegari.github.io/mongoat/tutorials/getting-started) — guided quick start and your first migration\n- [How-to guides](https://iamcalegari.github.io/mongoat/how-to/hooks) — decorators, hooks, migrations, sanitizing untrusted filters, error handling, the native escape hatch, indexes & validation\n- [Reference](https://iamcalegari.github.io/mongoat/api/) — full public API, generated from source\n- [CLI reference](https://iamcalegari.github.io/mongoat/cli/) — the `mongoat` migration CLI\n- [Explanation](https://iamcalegari.github.io/mongoat/explanation/thin-odm-philosophy) — design philosophy, Proxy gating, server-side validation, the migration lock\n- [Benchmarks](https://iamcalegari.github.io/mongoat/explanation/benchmarks) — measured against the native driver, Mongoose, and Papr\n- [Stability & versioning](https://iamcalegari.github.io/mongoat/explanation/versioning) — semver policy, what's covered by the public API contract\n- [Migration guide](https://iamcalegari.github.io/mongoat/migration) — upgrading from the alpha line to v1.0\n\n## Contributing\n\nIssues and pull requests are welcome — see [open issues](https://github.com/iamcalegari/mongoat/issues) or open a new one before starting significant work.\n\n## License\n\n[MIT](https://github.com/iamcalegari/mongoat/blob/main/LICENSE)\n","readmeFilename":"README.md"}
![\"Mongoat\"](\"https://raw.githubusercontent.com/iamcalegari/mongoat/main/graphics/mongoat-cover-4_1.png\")
\n![\"NPM](\"https://img.shields.io/npm/v/@iamcalegari/mongoat.svg\")
\n \n