@nxgt/mongo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# @nxgt/mongo
+
+A typed MongoDB collection, from one Zod schema: the schema types every read
+and write, and the same schema becomes the collection's `$jsonSchema`
+validator, applied idempotently. On top of it, a repository with pagination,
+transactions, optimistic locking, soft delete, audit stamps, and MongoDB's
+errors turned into ones you can catch.
+
+It wraps the official `mongodb` driver, which stays a peer dependency: the
+driver's collection is one property away at any time.
+
+## Install
+
+```sh
+bun add @nxgt/mongo mongodb zod
+```
+
+`mongodb` (>=7) and `zod` (>=4.6.5) are peer dependencies, so your application
+decides their versions and there is only ever one copy of each.
+
+## Setup
+
+```ts
+import { MongoClient } from 'mongodb';
+import { defineCollection, id, timestamps, softDelete, optimisticLock, actors } from '@nxgt/mongo';
+import { z } from 'zod';
+
+export const users = defineCollection({
+	name: 'users',
+	schema: z.object({
+		_id: id(),
+		email: z.email(),
+		name: z.string().nullable().default(null),
+		...timestamps(),
+		...softDelete(),
+		...optimisticLock(),
+		...actors(),
+	}),
+	indexes: [{ key: { email: 1 }, unique: true, name: 'users_email_unique' }],
+});
+
+const client = await MongoClient.connect(process.env.MONGO_URL);
+const db = client.db('app');
+```
+
+## Definition
+
+`defineCollection` takes the collection's name, the Zod schema of its
+documents, its indexes as the driver describes them, and how its validator is
+applied.
+
+The schema is the one source of truth. `z.output` is what a read gives back,
+`z.input` what a write takes: a field with a default — `_id`, `createdAt`,
+`version` — is optional to write and always there once read.
+
+The field helpers are ordinary Zod schemas, so a collection can take some of
+them, all of them, or none:
+
+| helper | fields | what the repository does with them |
+| --- | --- | --- |
+| `id()` | `_id` | a fresh `ObjectId` on create |
+| `objectId()` | — | an `ObjectId`, declared as `bsonType: 'objectId'` |
+| `timestamps()` | `createdAt`, `updatedAt` | sets `updatedAt` on every update |
+| `softDelete()` | `deletedAt` | `delete` sets it, reads leave those documents out |
+| `optimisticLock()` | `version` | raised on every update; `expectedVersion` checks it |
+| `actors(schema?)` | `createdBy`, `updatedBy`, `deletedBy` | stamped from `repository.as(actor)` |
+
+## Sync
+
+`sync` creates the collection with its validator, writes the validator when it
+changed, creates the indexes that are missing, and rebuilds those whose options
+changed. Run it twice and the second run sends nothing.
+
+```ts
+import { syncCollections } from '@nxgt/mongo';
+
+const reports = await syncCollections(db, [users, teams]);
+// [{ name: 'users', created: true, validator: 'created',
+//    indexes: { created: ['users_email_unique'], recreated: [], dropped: [], unchanged: [] } }]
+
+// What a deploy would do, without doing it:
+await syncCollections(db, [users, teams], { dryRun: true });
+```
+
+It is a deployment step, not a request-time one: writing a validator runs
+`collMod`, which needs the `dbAdmin` role that an application's own user does
+not have, and neither it nor an index build may run inside a transaction.
+
+`validation: { level: 'off' }` writes no validator at all, and removes one that
+is already there. `{ action: 'warn' }` logs a document that fails instead of
+refusing it, which is how a validator is rolled out onto a collection that is
+already full.
+
+## Documents
+
+```ts
+import { createRepository } from '@nxgt/mongo';
+
+const repo = createRepository(db, users);
+
+const ada = await repo.create({ email: 'ada@example.com' });
+// → { _id: ObjectId, email, name: null, createdAt: Date, version: 0, … }
+
+await repo.findById(ada._id);            // the document, or undefined
+await repo.getById(ada._id);             // or NotFoundError
+await repo.findFirst({ email: 'ada@example.com' });
+await repo.findMany({ filter: { name: null }, sort: { createdAt: -1 }, limit: 10 });
+await repo.count({ name: null });
+await repo.exists({ email: 'ada@example.com' });
+
+await repo.update(ada._id, { name: 'Ada' });          // checked field by field
+await repo.update(ada._id, { $inc: { logins: 1 } });  // MongoDB's operators too
+await repo.updateMany({ name: null }, { name: 'unknown' });
+
+await repo.delete(ada._id);       // soft, on a schema with deletedAt
+await repo.restore(ada._id);
+await repo.hardDelete(ada._id);   // really gone
+```
+
+`create` checks the document against the schema before sending it, which is
+also what fills its defaults. `update` checks each field of a patch — the
+driver's own `UpdateFilter` is intersected with `Document` and accepts any key
+whatsoever, including a typo.
+
+## Pagination
+
+```ts
+const page = await repo.paginate({ filter: { name: null }, page: 2, pageSize: 20 });
+// { items, total, page, pageSize, pageCount }
+
+let after: string | null = null;
+do {
+	const page = await repo.paginateByCursor({ after, limit: 100, orderBy: 'createdAt', direction: 'desc' });
+	send(page.items);
+	after = page.nextCursor;
+} while (after);
+```
+
+The cursor is a keyset on the field and `_id`, which breaks its ties: no
+document is repeated or skipped while the collection is written to, where
+`skip` would do both. It is opaque and URL-safe, and it survives `ObjectId`,
+`Date` and `bigint` values. It is encoded, not signed.
+
+## Transactions
+
+```ts
+import { withTransaction } from '@nxgt/mongo';
+
+await withTransaction(client, async (session) => {
+	const team = await teams.with(session).create({ name: 'Core' });
+	await users.with(session).update(userId, { teamId: team._id });
+});
+```
+
+**Every operation has to be given the session.** MongoDB has no ambient
+session: a write that was not given one runs outside the transaction and is not
+rolled back with it. `repository.with(session)` is how a repository takes it,
+and it returns a new repository rather than changing the one you have.
+
+Given a session that is already in a transaction, `withTransaction` joins it.
+MongoDB has no savepoints, so an inner failure takes the whole transaction
+down.
+
+## Optimistic locking
+
+On a schema with `optimisticLock()`, every update raises `version`. Pass the
+version you read and the update only applies while the document is still that
+one:
+
+```ts
+const user = await repo.getById(id);
+try {
+	await repo.update(id, { name: 'Ada' }, { expectedVersion: user.version });
+} catch (error) {
+	if (error instanceof OptimisticLockError) {
+		// error.expectedVersion, error.actualVersion: someone else wrote first
+	}
+}
+```
+
+## Errors
+
+Every method turns a MongoDB error into one of this package's, so an
+application never reads a numeric code:
+
+| error | `code` | when |
+| --- | --- | --- |
+| `NotFoundError` | `NOT_FOUND` | a method by `_id` matched nothing |
+| `ConflictError` | `CONFLICT` | a unique index refused the write (`E11000`) |
+| `ValidationError` | `VALIDATION` | the collection's validator refused it (121) |
+| `OptimisticLockError` | `OPTIMISTIC_LOCK` | `expectedVersion` no longer matches |
+| `InvalidCursorError` | `INVALID_CURSOR` | a cursor this package did not write |
+| `DataError` | `DATABASE` | any other server error, with its `serverCode` |
+
+`ConflictError` carries `index`, `keys` and, when the server gives them,
+`values`. `ValidationError` carries `issues`, MongoDB's `errInfo` flattened
+into `{ path, reason, specifiedAs, consideredValue }`. Anything that is not a
+server error reaches you untouched.
+
+## Not included
+
+- **No aggregation helpers.** `repository.collection` is the driver's
+  collection: `.aggregate()`, `.watch()` and the rest are there.
+- **No migrations.** `sync` brings the schema and the indexes in line; it never
+  rewrites a document.
+- **No connection management.** The client is yours to open and close.
+
+## API
+
+| export | what it is |
+| --- | --- |
+| `defineCollection(config)` | a collection: name, schema, indexes, validation |
+| `id`, `objectId`, `timestamps`, `softDelete`, `optimisticLock`, `actors` | the field helpers |
+| `createRepository(db, definition, options?)` | the typed repository |
+| `syncCollection`, `syncCollections` | create and bring in line, with `dryRun` |
+| `withTransaction(clientOrSession, fn, options?)` | a transaction, joined when nested |
+| `toMongoJsonSchema(schema)` | a Zod schema as a MongoDB `$jsonSchema` |
+| `encodeCursor`, `decodeCursor`, `pageWindow`, `toPage` | the pagination pieces |
+| `DataError` and its subclasses, `toDataError` | the errors |
+| `diffIndexes`, `normalizeIndex`, `validationMatches` | what `sync` compares with |
+
+`RepositoryOptions` turns the behaviours off one by one: `softDelete`,
+`touchUpdatedAt`, `optimisticLock`, `validate: 'off'`, `maxPageSize`.
+
+## Traps
+
+- **There is no ambient session.** An operation inside `withTransaction` that
+  was not given the session is not part of the transaction. Use
+  `repository.with(session)` for every one of them.
+- **`$jsonSchema` is not JSON Schema.** MongoDB rejects `$ref`, `$schema`,
+  `default`, `format` and `id`, has no `integer` type, and treats a keyword it
+  does not know as an error rather than ignoring it. `toMongoJsonSchema`
+  inlines every `$ref` and keeps only what MongoDB knows — so **a recursive
+  schema cannot be a validator**, and it throws rather than writing one that
+  would be refused.
+- **A whole number is not an `int` past 32 bits.** `z.int()` becomes
+  `bsonType: ['int', 'long', 'double']` with `multipleOf: 1`, because the
+  driver sends a large integer as a double. A validator that asked for `int`
+  alone would refuse a number your own schema accepts.
+- **The validator is strict about unknown fields.** `z.object()` gives
+  `additionalProperties: false`, so a field that is written but not in the
+  schema is refused. `z.looseObject()` is the way out.
+- **Existing documents are never checked** until they are modified: adding a
+  validator to a full collection refuses nothing retroactively, and
+  `validationLevel: 'moderate'` keeps it that way for updates too.
+- **Writing a validator needs `dbAdmin`.** `collMod` is not granted by
+  `readWrite`. Sync with a deployment credential, not the application's.
+- **A duplicate key from a bulk write carries no values.** MongoDB puts
+  `keyPattern` and `keyValue` on a single write's error only; for
+  `createMany`, `ConflictError.keys` is parsed out of the message and `values`
+  is `undefined`.
+- **`updateMany` and `deleteMany` refuse an empty filter.** Pass
+  `{ _id: { $exists: true } }` to mean every document, so that a filter built
+  from a variable that came out empty cannot rewrite the collection.
+- **Rebuilding an index drops it first.** MongoDB cannot alter an index in
+  place, so `sync` drops and recreates one whose options changed: there is a
+  window with no index, and on a large collection the rebuild is not free.
+- **`validate: 'off'` also turns the defaults off.** Nothing fills `_id`,
+  `createdAt` or `version` any more, because filling them is what parsing does.
+- **The driver retries a transaction's callback** on a transient error, for up
+  to 120 seconds, so `fn` must be safe to run twice — and must not swallow
+  errors, or the driver cannot tell whether the transaction was aborted.
+- **`session.abortTransaction()` inside the callback resolves.**
+  `withTransaction` returns the callback's value; it does not throw.
+
+## Testing against a real MongoDB
+
+Transactions need a replica set, which a standalone `mongod` is not. This
+package's own specs run against a single-node replica set from
+`mongodb-memory-server-core`, with no Docker; the same works in any consumer's
+test suite.
+
+## License
+
+MIT

package/dist/definition/define-collection.d.ts

@@ -0,0 +1,82 @@
+import type { IndexDescription, ObjectId } from 'mongodb';
+import type { z } from 'zod';
+/** What MongoDB does with a document that fails the validator. */
+export type ValidationAction = 'error' | 'warn';
+/**
+ * Which documents the validator applies to. `off` writes no validator at all;
+ * `moderate` exempts documents that were already invalid from updates.
+ */
+export type ValidationLevel = 'off' | 'moderate' | 'strict';
+export interface ValidationConfig {
+    /** Default `'strict'`. */
+    level?: ValidationLevel;
+    /** Default `'error'`. `'warn'` logs and lets the write through. */
+    action?: ValidationAction;
+}
+/** What `defineCollection` takes. */
+export interface CollectionConfig<Schema extends z.ZodObject> {
+    /** The collection's name on the server. */
+    name: string;
+    /**
+     * The documents, as they are stored: `z.output` is what a read gives back,
+     * `z.input` what a write takes. It must have an `_id`.
+     */
+    schema: Schema;
+    /** The indexes `sync` creates, as the driver describes them. */
+    indexes?: readonly IndexDescription[];
+    /** The `$jsonSchema` validator `sync` writes from the schema. */
+    validation?: ValidationConfig;
+}
+/** A collection, as `defineCollection` returns it: frozen, with its defaults. */
+export interface CollectionDefinition<Schema extends z.ZodObject = z.ZodObject> extends Readonly<CollectionConfig<Schema>> {
+    readonly indexes: readonly IndexDescription[];
+    readonly validation: Required<ValidationConfig>;
+}
+/** Any definition, whatever its documents. */
+export type AnyCollectionDefinition = CollectionDefinition<any>;
+/** The documents of a definition, as they are read back. */
+export type DocumentOf<Def> = Def extends {
+    schema: infer Schema;
+} ? Schema extends z.ZodType ? z.output<Schema> : never : never;
+/** What a write takes: the documents before their defaults are filled. */
+export type NewDocumentOf<Def> = Def extends {
+    schema: infer Schema;
+} ? Schema extends z.ZodType ? z.input<Schema> : never : never;
+/** The type of `_id`. */
+export type IdOf<Def> = DocumentOf<Def> extends {
+    _id: infer Id;
+} ? Id : ObjectId;
+/** A field of the documents, as a top-level key. */
+export type FieldOf<Def> = keyof DocumentOf<Def> & string;
+/**
+ * Defines a collection: its name, the Zod schema of its documents, its
+ * indexes, and how its validator is applied.
+ *
+ * The schema is the one source: it types every read and write, and `sync`
+ * derives the collection's `$jsonSchema` validator from it.
+ *
+ * ```ts
+ * export const users = defineCollection({
+ * 	name: 'users',
+ * 	schema: z.object({
+ * 		_id: id(),
+ * 		email: z.email(),
+ * 		...timestamps(),
+ * 		...softDelete(),
+ * 	}),
+ * 	indexes: [{ key: { email: 1 }, unique: true, name: 'users_email_unique' }],
+ * });
+ * ```
+ */
+export declare function defineCollection<Schema extends z.ZodObject>(config: CollectionConfig<Schema>): CollectionDefinition<Schema>;
+/** Which of the fields the repository knows about a definition's schema has. */
+export declare function stampsOf(definition: AnyCollectionDefinition): {
+    createdAt: boolean;
+    updatedAt: boolean;
+    deletedAt: boolean;
+    version: boolean;
+    createdBy: boolean;
+    updatedBy: boolean;
+    deletedBy: boolean;
+};
+//# sourceMappingURL=define-collection.d.ts.map

package/dist/definition/define-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-collection.d.ts","sourceRoot":"","sources":["../../src/definition/define-collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAChC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,mEAAmE;IACnE,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS;IAC3D,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,iEAAiE;IACjE,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAC7E,SAAQ,QAAQ,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CAChD;AAED,8CAA8C;AAC9C,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;AAEhE,4DAA4D;AAC5D,MAAM,MAAM,UAAU,CAAC,GAAG,IAAI,GAAG,SAAS;IAAE,MAAM,EAAE,MAAM,MAAM,CAAA;CAAE,GAC/D,MAAM,SAAS,CAAC,CAAC,OAAO,GACvB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAChB,KAAK,GACN,KAAK,CAAC;AAET,0EAA0E;AAC1E,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS;IAAE,MAAM,EAAE,MAAM,MAAM,CAAA;CAAE,GAClE,MAAM,SAAS,CAAC,CAAC,OAAO,GACvB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GACf,KAAK,GACN,KAAK,CAAC;AAET,yBAAyB;AACzB,MAAM,MAAM,IAAI,CAAC,GAAG,IACnB,UAAU,CAAC,GAAG,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,EAAE,GAAG,QAAQ,CAAC;AAE3D,oDAAoD;AACpD,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,MAAM,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,EAC1D,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAC9B,oBAAoB,CAAC,MAAM,CAAC,CAgB9B;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,UAAU,EAAE,uBAAuB,GAAG;IAC9D,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACnB,CAYA"}

package/dist/definition/fields.d.ts

@@ -0,0 +1,57 @@
+import { ObjectId } from 'mongodb';
+import { z } from 'zod';
+/**
+ * An `ObjectId`, declared to MongoDB as `bsonType: 'objectId'`. JSON Schema
+ * has no type for one, so the metadata is how the validator learns of it.
+ */
+export declare function objectId(): z.ZodCustom<ObjectId, ObjectId>;
+/**
+ * `_id`, filled with a new `ObjectId` when a document is created: optional to
+ * write, always there once read.
+ */
+export declare function id(): z.ZodDefault<z.ZodCustom<ObjectId, ObjectId>>;
+/**
+ * `createdAt` and `updatedAt`, filled on create. A repository sets `updatedAt`
+ * on every update.
+ */
+export declare function timestamps(): {
+    createdAt: z.ZodDefault<z.ZodDate>;
+    updatedAt: z.ZodDefault<z.ZodDate>;
+};
+/**
+ * `deletedAt`, `null` while the document is live. A repository on a collection
+ * with it soft-deletes, and leaves deleted documents out of every read.
+ */
+export declare function softDelete(): {
+    deletedAt: z.ZodDefault<z.ZodNullable<z.ZodDate>>;
+};
+/**
+ * `version`, raised by one on every update. A repository with it takes
+ * `expectedVersion` and throws `OptimisticLockError` when it no longer
+ * matches.
+ */
+export declare function optimisticLock(): {
+    version: z.ZodDefault<z.ZodInt>;
+};
+/**
+ * `createdBy`, `updatedBy` and `deletedBy`, stamped from the actor a
+ * repository was given with `as(actor)`. The actor's own type is the schema
+ * passed in, an `ObjectId` by default.
+ */
+export declare function actors<Actor extends z.ZodType = ReturnType<typeof objectId>>(actor?: Actor): {
+    createdBy: z.ZodDefault<z.ZodNullable<Actor>>;
+    updatedBy: z.ZodDefault<z.ZodNullable<Actor>>;
+    deletedBy: z.ZodDefault<z.ZodNullable<Actor>>;
+};
+/** The fields the repository gives a meaning to, by name. */
+export declare const STAMP_FIELDS: {
+    readonly id: "_id";
+    readonly createdAt: "createdAt";
+    readonly updatedAt: "updatedAt";
+    readonly deletedAt: "deletedAt";
+    readonly version: "version";
+    readonly createdBy: "createdBy";
+    readonly updatedBy: "updatedBy";
+    readonly deletedBy: "deletedBy";
+};
+//# sourceMappingURL=fields.d.ts.map

package/dist/definition/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/definition/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;GAGG;AACH,wBAAgB,QAAQ,oCAIvB;AAED;;;GAGG;AACH,wBAAgB,EAAE,kDAEjB;AAED;;;GAGG;AACH,wBAAgB,UAAU;;;EAKzB;AAED;;;GAGG;AACH,wBAAgB,UAAU;;EAEzB;AAED;;;;GAIG;AACH,wBAAgB,cAAc;;EAE7B;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,EAC3E,KAAK,GAAE,KAAsC;;;;EAO7C;AAED,6DAA6D;AAC7D,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAC"}

package/dist/definition/json-schema.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Every keyword MongoDB's `$jsonSchema` knows. It **rejects** a document that
+ * uses any other, rather than ignoring it, so anything not in here is dropped
+ * on the way out.
+ */
+export declare const MONGO_JSON_SCHEMA_KEYWORDS: ReadonlySet<string>;
+/**
+ * A Zod schema as a MongoDB `$jsonSchema`, ready for a collection's validator.
+ *
+ * `z.toJSONSchema` alone is not one: MongoDB rejects `$schema`, `$ref`,
+ * `definitions`, `default`, `format` and `id`, has no `integer` type, and
+ * treats a keyword it does not know as an error rather than ignoring it. This
+ * resolves every `$ref` by inlining it, keeps only the keywords MongoDB
+ * knows, and maps `integer`.
+ *
+ * `Date` and `ObjectId` have no JSON Schema type: they are declared with
+ * `bsonType`, which `date()` and `objectId()` already carry in their metadata.
+ * Any schema can do the same with `.meta({ bsonType: 'decimal' })`.
+ *
+ * ```ts
+ * toMongoJsonSchema(z.object({ _id: objectId(), email: z.string() }));
+ * // { type: 'object', properties: { … }, required: ['_id', 'email'], … }
+ * ```
+ */
+export declare function toMongoJsonSchema(schema: z.ZodType): Record<string, unknown>;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/definition/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/definition/json-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CA8BzD,CAAC;AA4FH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB5E"}

package/dist/errors/data-error.d.ts

@@ -0,0 +1,92 @@
+/** What went wrong, as a string a caller can switch on. */
+export type DataErrorCode = 'DATABASE' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION' | 'OPTIMISTIC_LOCK' | 'INVALID_CURSOR';
+/** One reason a document failed the collection's `$jsonSchema` validator. */
+export interface ValidationIssue {
+    /** The dotted path of the field, empty for the document itself. */
+    path: string;
+    /** The rule it broke: `bsonType`, `required`, `minimum`… */
+    reason: string;
+    /** What the schema asked for, as MongoDB reports it. */
+    specifiedAs?: unknown;
+    /** The value that was refused, when the server names it. */
+    consideredValue?: unknown;
+    /** Its BSON type, when the server names it: `string`, `int`, `double`… */
+    consideredType?: string;
+    /** The schema's `description` for the field, when it has one. */
+    description?: string;
+}
+export interface DataErrorOptions {
+    collection?: string | undefined;
+    /** The `_id` a method by id was given. */
+    id?: unknown;
+    /** MongoDB's numeric error code: 11000, 121, 26… */
+    serverCode?: number | undefined;
+    /** MongoDB's `codeName`, which write errors do not carry. */
+    serverCodeName?: string | undefined;
+    /** The index a conflict names, when the server names one. */
+    index?: string | undefined;
+    /** The fields the error is about: an index's keys, or a validator's paths. */
+    keys?: string[];
+    /** Those fields' values, when the server gives them. */
+    values?: Record<string, unknown> | undefined;
+    issues?: ValidationIssue[];
+    expectedVersion?: number | undefined;
+    actualVersion?: number | undefined;
+    cause?: unknown;
+}
+/**
+ * What this package throws. Every method turns a driver error into one of
+ * these, so an application catches `ConflictError` instead of reading `11000`
+ * off an error whose shape changes with the operation that produced it.
+ *
+ * A driver error that is none of them reaches the caller as it is.
+ */
+export declare class DataError extends Error {
+    name: string;
+    readonly code: DataErrorCode;
+    readonly collection: string | undefined;
+    readonly id: unknown;
+    readonly serverCode: number | undefined;
+    readonly serverCodeName: string | undefined;
+    readonly index: string | undefined;
+    readonly keys: string[];
+    readonly values: Record<string, unknown> | undefined;
+    readonly issues: ValidationIssue[];
+    readonly expectedVersion: number | undefined;
+    readonly actualVersion: number | undefined;
+    constructor(message?: string, options?: DataErrorOptions);
+}
+/** No document matched, where one was required. */
+export declare class NotFoundError extends DataError {
+    name: string;
+    readonly code: "NOT_FOUND";
+    constructor(message?: string, options?: DataErrorOptions);
+}
+/** A unique index refused the write: MongoDB's `E11000`. */
+export declare class ConflictError extends DataError {
+    name: string;
+    readonly code: "CONFLICT";
+    constructor(message?: string, options?: DataErrorOptions);
+}
+/** The collection's `$jsonSchema` validator refused the document: code 121. */
+export declare class ValidationError extends DataError {
+    name: string;
+    readonly code: "VALIDATION";
+    constructor(message?: string, options?: DataErrorOptions);
+}
+/**
+ * The document changed since it was read: its `version` is no longer the one
+ * the update expected, and nothing was written.
+ */
+export declare class OptimisticLockError extends DataError {
+    name: string;
+    readonly code: "OPTIMISTIC_LOCK";
+    constructor(message?: string, options?: DataErrorOptions);
+}
+/** A cursor this package did not write, or one for another ordering. */
+export declare class InvalidCursorError extends DataError {
+    name: string;
+    readonly code: "INVALID_CURSOR";
+    constructor(message?: string, options?: DataErrorOptions);
+}
+//# sourceMappingURL=data-error.d.ts.map

package/dist/errors/data-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-error.d.ts","sourceRoot":"","sources":["../../src/errors/data-error.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GACtB,UAAU,GACV,WAAW,GACX,UAAU,GACV,YAAY,GACZ,iBAAiB,GACjB,gBAAgB,CAAC;AAEpB,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC/B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,0CAA0C;IAC1C,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAC1B,IAAI,SAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAc;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE/B,OAAO,SAAmB,EAAE,OAAO,GAAE,gBAAqB;CAgBtE;AAED,mDAAmD;AACnD,qBAAa,aAAc,SAAQ,SAAS;IAClC,IAAI,SAAmB;IAChC,SAAkB,IAAI,EAAG,WAAW,CAAU;gBAElC,OAAO,SAAc,EAAE,OAAO,GAAE,gBAAqB;CAGjE;AAED,4DAA4D;AAC5D,qBAAa,aAAc,SAAQ,SAAS;IAClC,IAAI,SAAmB;IAChC,SAAkB,IAAI,EAAG,UAAU,CAAU;gBAEjC,OAAO,SAAkB,EAAE,OAAO,GAAE,gBAAqB;CAGrE;AAED,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,SAAS;IACpC,IAAI,SAAqB;IAClC,SAAkB,IAAI,EAAG,YAAY,CAAU;gBAG9C,OAAO,SAA+B,EACtC,OAAO,GAAE,gBAAqB;CAI/B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACxC,IAAI,SAAyB;IACtC,SAAkB,IAAI,EAAG,iBAAiB,CAAU;gBAExC,OAAO,SAAqB,EAAE,OAAO,GAAE,gBAAqB;CAGxE;AAED,wEAAwE;AACxE,qBAAa,kBAAmB,SAAQ,SAAS;IACvC,IAAI,SAAwB;IACrC,SAAkB,IAAI,EAAG,gBAAgB,CAAU;gBAEvC,OAAO,SAAmB,EAAE,OAAO,GAAE,gBAAqB;CAGtE"}

package/dist/errors/to-data-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A MongoDB error as one of this package's, or the error itself when it is
+ * none of them.
+ *
+ * It reads the error's fields rather than its class: a duplicate key arrives
+ * as a `MongoServerError` with `keyPattern` from `insertOne`, and as a
+ * `MongoBulkWriteError` whose `writeErrors` carry neither `keyPattern` nor
+ * `keyValue` from `insertMany` and `bulkWrite`. Both become a `ConflictError`
+ * with the same fields. Reading fields also survives two copies of the driver
+ * in one tree, where `instanceof` does not.
+ */
+export declare function toDataError(error: unknown, context?: {
+    collection?: string | undefined;
+}): unknown;
+//# sourceMappingURL=to-data-error.d.ts.map

package/dist/errors/to-data-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-data-error.d.ts","sourceRoot":"","sources":["../../src/errors/to-data-error.ts"],"names":[],"mappings":"AA0HA;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAO,GAC/C,OAAO,CAoDT"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { type AnyCollectionDefinition, type CollectionConfig, type CollectionDefinition, type DocumentOf, defineCollection, type FieldOf, type IdOf, type NewDocumentOf, stampsOf, type ValidationAction, type ValidationConfig, type ValidationLevel, } from './definition/define-collection';
+export { actors, id, objectId, optimisticLock, STAMP_FIELDS, softDelete, timestamps, } from './definition/fields';
+export { MONGO_JSON_SCHEMA_KEYWORDS, toMongoJsonSchema, } from './definition/json-schema';
+export { ConflictError, DataError, type DataErrorCode, type DataErrorOptions, InvalidCursorError, NotFoundError, OptimisticLockError, ValidationError, type ValidationIssue, } from './errors/data-error';
+export { toDataError } from './errors/to-data-error';
+export { type CursorPayload, decodeCursor, encodeCursor, } from './pagination/cursor';
+export { type CursorPage, cursorLimit, DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, type Page, type PageOptions, type PageWindow, pageWindow, toPage, } from './pagination/page';
+export { createRepository } from './repository/create-repository';
+export type { CursorPaginateOptions, FindFirstOptions, FindManyOptions, OrderDirection, PaginateOptions, Patch, ReadOptions, Repository, RepositoryOptions, UpdateOptions, } from './repository/types';
+export { diffIndexes, type IndexDiff, indexMatches, indexNameOf, type NormalizedIndex, normalizeIndex, } from './sync/index-diff';
+export { type SyncOptions, type SyncReport, syncCollection, syncCollections, } from './sync/sync-collection';
+export { hasValidator, type LiveValidation, validationMatches, type WantedValidation, } from './sync/validator-diff';
+export { type TransactionHost, withTransaction, } from './transaction/with-transaction';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,OAAO,EACZ,KAAK,IAAI,EACT,KAAK,aAAa,EAClB,QAAQ,EACR,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACN,MAAM,EACN,EAAE,EACF,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACV,UAAU,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,0BAA0B,EAC1B,iBAAiB,GACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,aAAa,EACb,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,KAAK,eAAe,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EACN,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,UAAU,EACV,MAAM,GACN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,YAAY,EACX,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,KAAK,EACL,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,aAAa,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,WAAW,EACX,KAAK,SAAS,EACd,YAAY,EACZ,WAAW,EACX,KAAK,eAAe,EACpB,cAAc,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,cAAc,EACd,eAAe,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,YAAY,EACZ,KAAK,cAAc,EACnB,iBAAiB,EACjB,KAAK,gBAAgB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,KAAK,eAAe,EACpB,eAAe,GACf,MAAM,gCAAgC,CAAC"}