@nxgt/mongo 0.1.0 → 0.3.0

package/README.md

@@ -2,12 +2,13 @@
 
 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,
+validator, applied idempotently. On top of it, a collection 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.
+It wraps the official `mongodb` driver, which stays a peer dependency — and it
+does not hide it: the driver's own methods are on the very same object, so
+`aggregate`, `watch` and `bulkWrite` are always at hand.
 
 ## Install
 
@@ -31,6 +32,7 @@ export const users = defineCollection({
 		_id: id(),
 		email: z.email(),
 		name: z.string().nullable().default(null),
+		loginCount: z.int().default(0),
 		...timestamps(),
 		...softDelete(),
 		...optimisticLock(),
@@ -46,8 +48,23 @@ 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.
+documents, its indexes, and how its validator is applied.
+
+An index is keyed on the schema's own fields, so an editor completes them and a
+typo does not compile. A path into a field is allowed too, since that is how
+MongoDB indexes a nested key. Everything else is the driver's own
+`IndexDescription` — `unique`, `name`, `collation`, `expireAfterSeconds`,
+`partialFilterExpression`:
+
+```ts
+indexes: [
+	{ key: { email: 1 }, unique: true, name: 'users_email_unique' },
+	{ key: { createdAt: -1 } },
+	{ key: { 'address.city': 1 } },
+	// @ts-expect-error there is no such field
+	{ key: { emial: 1 } },
+]
+```
 
 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`,
@@ -94,34 +111,87 @@ already full.
 ## Documents
 
 ```ts
-import { createRepository } from '@nxgt/mongo';
+import { getCollection } from '@nxgt/mongo';
 
-const repo = createRepository(db, users);
+const collection = getCollection(db, users);   // a Db, or a MongoClient
 
-const ada = await repo.create({ email: 'ada@example.com' });
-// → { _id: ObjectId, email, name: null, createdAt: Date, version: 0, … }
+const ada = await collection.create({ email: 'ada@example.com' });
+// → { _id: ObjectId, id: '507f…', 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 collection.findById(ada._id);            // the document, or undefined
+await collection.getById(ada._id);             // or NotFoundError
+await collection.findFirst({ email: 'ada@example.com' });
+await collection.findMany({ filter: { name: null }, sort: { createdAt: -1 }, limit: 10 });
+await collection.count({ name: null });
+await collection.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 collection.update(ada._id, { name: 'Ada' });             // checked field by field
+await collection.update(ada._id, { $inc: { loginCount: 1 } }); // MongoDB's operators too
+await collection.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
+await collection.delete(ada._id);       // soft, on a schema with deletedAt
+await collection.restore(ada._id);
+await collection.hardDelete(ada._id);   // really gone
+```
+
+**The driver's collection is the same object.** Everything this package does
+not wrap is on it directly — no `.collection` to go through:
+
+```ts
+await collection.aggregate([{ $group: { _id: '$teamId', n: { $sum: 1 } } }]).toArray();
+collection.watch();
+await collection.distinct('email');
+await collection.bulkWrite([…]);
+collection.collectionName;   // 'users'
 ```
 
+Three names are defined by both, and this package's win, because a filter that
+came out empty must not rewrite a collection: `count`, `updateMany` and
+`deleteMany` return a number and require a filter. The driver's own are on
+`raw`, which is its `Collection`, untouched:
+
+```ts
+await collection.updateMany({ name: null }, { name: 'x' });      // → number
+await collection.raw.updateMany({}, { $set: { name: 'x' } });    // → UpdateResult
+```
+
+`raw` is also the way out for an update operator this package does not name.
+
 `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.
 
+## Ids
+
+Every document a repository gives back carries `id`: its `_id` as a string. It
+is computed, never stored — the collection holds `_id` alone — and it is an
+ordinary enumerable property, so `JSON.stringify` and a spread carry it and a
+handler can return the document as it is.
+
+Because it is not a stored field, nothing can be filtered or patched on it: the
+server would match nothing, and TypeScript refuses it. To go the other way,
+from a string that arrived over HTTP:
+
+```ts
+import { toObjectId, tryObjectId, isValidObjectId, objectIdParam } from '@nxgt/mongo';
+
+await repo.getById(toObjectId(params.id));   // an ObjectId, or InvalidIdError
+tryObjectId(params.id);                      // an ObjectId, or undefined
+isValidObjectId(params.id);                  // a boolean
+toObjectIds(query.ids);                      // for a `$in` filter
+
+// Or as part of a schema, where the parameters are parsed:
+const route = z.object({ id: objectIdParam() });
+const { id } = route.parse(params);          // ObjectId
+```
+
+**Do not call `new ObjectId(value)` on input you did not produce.** Given
+`null` or `undefined` the driver does not throw: it invents a fresh id, so a
+parameter that never arrived becomes a perfectly valid id that matches nothing.
+`toObjectId` throws `InvalidIdError`, which a handler can turn into a 400 or a
+404.
+
 ## Pagination
 
 ```ts
@@ -147,15 +217,20 @@ document is repeated or skipped while the collection is written to, where
 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 });
+	const team = await teams.withSession(session).create({ name: 'Core' });
+	await users.withSession(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.
+rolled back with it. `collection.withSession(session)` is how a collection
+takes it, and it returns a new collection rather than changing the one you
+have.
+
+`withSession` binds **this package's** methods. A driver method on the same
+object — `aggregate`, `bulkWrite`, `countDocuments` — takes its session the
+driver's way, in its options: `collection.aggregate(pipeline, { session })`.
 
 Given a session that is already in a transaction, `withTransaction` joins it.
 MongoDB has no savepoints, so an inner failure takes the whole transaction
@@ -190,6 +265,7 @@ application never reads a numeric code:
 | `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 |
+| `InvalidIdError` | `INVALID_ID` | a value that is no `ObjectId`, nor the string of one |
 | `DataError` | `DATABASE` | any other server error, with its `serverCode` |
 
 `ConflictError` carries `index`, `keys` and, when the server gives them,
@@ -211,7 +287,9 @@ server error reaches you untouched.
 | --- | --- |
 | `defineCollection(config)` | a collection: name, schema, indexes, validation |
 | `id`, `objectId`, `timestamps`, `softDelete`, `optimisticLock`, `actors` | the field helpers |
-| `createRepository(db, definition, options?)` | the typed repository |
+| `toObjectId`, `toObjectIds`, `tryObjectId`, `objectIdParam` | a string from outside as an `ObjectId` |
+| `isValidObjectId`, `isObjectIdString`, `isObjectId` | the checks behind them |
+| `getCollection(dbOrClient, definition, options?)` | the typed collection, driver methods included |
 | `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` |
@@ -219,14 +297,47 @@ server error reaches you untouched.
 | `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`.
+`CollectionOptions` turns the behaviours off one by one: `softDelete`,
+`touchUpdatedAt`, `optimisticLock`, `validate: 'off'`, `maxPageSize`, and it
+names the database with `db` when you pass a client.
+
+## What does not compile
+
+The schema types more than the documents. These are compile errors, each one
+kept as a test in `test/types/strictness.ts`:
+
+```ts
+await collection.findMany({ sort: { nope: 1 } });        // no such field
+await collection.findMany({ sort: { email: 'up' } });    // not a direction
+await collection.findMany({ projection: { nope: 1 } });  // no such field
+await collection.findMany({ projection: { email: 2 } }); // 0, 1 or an operator
+await collection.update(id, { $set: { nope: 1 } });      // no such field
+await collection.update(id, { $set: { email: 1 } });     // email is a string
+await collection.update(id, { $inc: { email: 1 } });     // not a numeric field
+await collection.update(id, { $push: { title: 'x' } });  // not an array field
+await collection.update(id, { id: 'abc' });              // id is computed
+collection.as('not-an-object-id');                       // the schema types the actor
+posts.as(someone);                                       // posts stamp no actor
+```
+
+What is **not** checked: the tail of a dotted path, and a `filter`, which stays
+the driver's `Filter` — rebuilding it would mean reimplementing every query
+operator, and getting it subtly wrong is worse than being honest about it.
 
 ## 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.
+  `collection.withSession(session)` for every one of them.
+- **A driver method does not take the collection's session.** `withSession`
+  binds this package's methods; `collection.aggregate(…)` is the driver's own,
+  so it wants `{ session }` in its options like anywhere else. The session is
+  on the collection as `collection.session` when you need to pass it along.
+- **`estimatedDocumentCount` counts writes that have not committed.** It reads
+  the storage engine's metadata rather than the documents, so it is not
+  transactional and it is not exact — a document inserted by an open
+  transaction is already in its answer. `count` queries, and is the one to
+  assert on.
 - **`$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`
@@ -255,6 +366,15 @@ server error reaches you untouched.
 - **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.
+- **`new ObjectId(undefined)` is a fresh id, not an error.** So is
+  `new ObjectId(null)`. A missing route parameter turns into a valid id that
+  matches nothing, and the bug surfaces as an empty result rather than as a
+  failure. Use `toObjectId`, which throws, or `tryObjectId`, which answers
+  `undefined`.
+- **`id` is computed, not stored.** It is on every document a repository
+  returns, and on none in the collection: a filter or a patch keyed on it would
+  match nothing, so both are compile errors. Query on `_id`. A schema that
+  declares an `id` field of its own keeps it, untouched.
 - **`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

package/dist/collection/get-collection.d.ts

@@ -0,0 +1,26 @@
+import type { Db, MongoClient } from 'mongodb';
+import type { z } from 'zod';
+import { type CollectionDefinition } from '../definition/define-collection';
+import type { CollectionOptions, TypedCollection } from './types';
+/** What a collection can be reached through: a database, or a client. */
+export type CollectionSource = Db | MongoClient;
+/**
+ * A collection: this package's methods and the driver's own, on one object.
+ *
+ * ```ts
+ * const users = getCollection(db, usersDefinition);
+ *
+ * const ada = await users.create({ email: 'ada@example.com' });
+ * await users.update(ada._id, { name: 'Ada' }, { expectedVersion: ada.version });
+ * await users.aggregate([{ $group: { _id: '$teamId', n: { $sum: 1 } } }]);
+ * ```
+ *
+ * It takes a `Db`, or a `MongoClient` — then the database is the URI's, or the
+ * one named in `{ db }`.
+ *
+ * Every operation runs in the collection's session, which `withSession` sets:
+ * MongoDB has no ambient session, so a write inside a transaction that was not
+ * given one is not part of it and is not rolled back.
+ */
+export declare function getCollection<Schema extends z.ZodObject>(source: CollectionSource, definition: CollectionDefinition<Schema>, options?: CollectionOptions<CollectionDefinition<Schema>>): TypedCollection<CollectionDefinition<Schema>>;
+//# sourceMappingURL=get-collection.d.ts.map

package/dist/collection/get-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-collection.d.ts","sourceRoot":"","sources":["../../src/collection/get-collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,EAAE,EAAY,WAAW,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAEN,KAAK,oBAAoB,EAEzB,MAAM,iCAAiC,CAAC;AAiBzC,OAAO,KAAK,EACX,iBAAiB,EAEjB,eAAe,EACf,MAAM,SAAS,CAAC;AAsBjB,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,EAAE,GAAG,WAAW,CAAC;AAmBhD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,EACvD,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACxC,OAAO,GAAE,iBAAiB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAM,GAC3D,eAAe,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAG/C"}

package/dist/collection/types.d.ts

@@ -0,0 +1,270 @@
+import type { ClientSession, Db, Collection as DriverCollection, Filter } from 'mongodb';
+import type { DocumentOf, FieldOf, IdOf, NewDocumentOf, ReadDocumentOf } from '../definition/define-collection';
+import type { CursorPage, Page, PageOptions } from '../pagination/page';
+import type { SyncOptions, SyncReport } from '../sync/sync-collection';
+export type OrderDirection = 'asc' | 'desc';
+/**
+ * A field of the documents, or a path into one. The tail of a path cannot be
+ * checked — a schema says nothing about what is under an arbitrary key — but
+ * its head must be a field, which is what catches a misspelt name.
+ */
+export type FieldPath<Def> = FieldOf<Def> | `${FieldOf<Def>}.${string}`;
+/** The fields whose type is a number, for `$inc` and `$mul`. */
+type NumericFieldsOf<Doc> = {
+    [K in keyof Doc]: NonNullable<Doc[K]> extends number ? K : never;
+}[keyof Doc] & string;
+/** The fields whose type is an array, for `$push` and `$addToSet`. */
+type ArrayFieldsOf<Doc> = {
+    [K in keyof Doc]: NonNullable<Doc[K]> extends readonly unknown[] ? K : never;
+}[keyof Doc] & string;
+type ElementOf<T> = NonNullable<T> extends readonly (infer Element)[] ? Element : never;
+/** A sort, keyed on the schema's fields. */
+export type SortOf<Def> = {
+    [Field in FieldPath<Def>]?: 1 | -1 | 'asc' | 'desc';
+};
+/** What a projection may hold beside `0` and `1`. */
+export type ProjectionOperator = {
+    $slice: number | [number, number];
+} | {
+    $elemMatch: Record<string, unknown>;
+} | {
+    $meta: string;
+};
+/**
+ * A projection, keyed on the schema's fields. It says what is sent over the
+ * wire; it does not narrow the type of the documents, because the driver
+ * cannot either — a projected read is typed as the whole document.
+ */
+export type ProjectionOf<Def> = {
+    [Field in FieldPath<Def>]?: 0 | 1 | boolean | ProjectionOperator;
+};
+/**
+ * Who is writing: the type the schema gives `createdBy`, or `updatedBy`, or
+ * `deletedBy`. A collection with none of them has no actor to stamp, so `as`
+ * cannot be called on it at all.
+ */
+export type ActorOf<Def> = 'createdBy' extends keyof DocumentOf<Def> ? NonNullable<DocumentOf<Def>['createdBy']> : 'updatedBy' extends keyof DocumentOf<Def> ? NonNullable<DocumentOf<Def>['updatedBy']> : 'deletedBy' extends keyof DocumentOf<Def> ? NonNullable<DocumentOf<Def>['deletedBy']> : never;
+/** What `$set` takes: a field's own type, or anything under a path. */
+export type SetOf<Def> = {
+    [Field in FieldPath<Def>]?: Field extends keyof DocumentOf<Def> ? DocumentOf<Def>[Field] : unknown;
+};
+/**
+ * MongoDB's update operators, keyed on the schema.
+ *
+ * The driver's own `UpdateFilter` is intersected with `Document`, whose index
+ * signature accepts every key — `$set: { nope: 1 }` included — and `Omit`
+ * cannot take that back, since omitting a literal key from an index signature
+ * leaves the index signature. So the operators are declared here instead. One
+ * this does not name is a reason to reach for `raw`, which is the driver's own
+ * collection, untouched.
+ */
+export interface UpdateOperators<Def> {
+    $set?: SetOf<Def>;
+    $setOnInsert?: SetOf<Def>;
+    $unset?: {
+        [Field in FieldPath<Def>]?: '' | 1 | true;
+    };
+    $inc?: {
+        [Field in NumericFieldsOf<DocumentOf<Def>> | `${FieldOf<Def>}.${string}`]?: number;
+    };
+    $mul?: {
+        [Field in NumericFieldsOf<DocumentOf<Def>> | `${FieldOf<Def>}.${string}`]?: number;
+    };
+    $min?: SetOf<Def>;
+    $max?: SetOf<Def>;
+    $rename?: {
+        [Field in FieldPath<Def>]?: string;
+    };
+    $currentDate?: {
+        [Field in FieldPath<Def>]?: true | {
+            $type: 'date' | 'timestamp';
+        };
+    };
+    $push?: PushOf<Def>;
+    $addToSet?: PushOf<Def>;
+    $pull?: {
+        [Field in FieldPath<Def>]?: unknown;
+    };
+    $pullAll?: {
+        [Field in FieldPath<Def>]?: readonly unknown[];
+    };
+    $pop?: {
+        [Field in FieldPath<Def>]?: 1 | -1;
+    };
+}
+/** What `$push` and `$addToSet` take: an element of the array, or `$each`. */
+export type PushOf<Def> = {
+    [Field in ArrayFieldsOf<DocumentOf<Def>>]?: ElementOf<DocumentOf<Def>[Field]> | {
+        $each: readonly ElementOf<DocumentOf<Def>[Field]>[];
+        $position?: number;
+        $slice?: number;
+        $sort?: 1 | -1 | Record<string, 1 | -1>;
+    };
+} & {
+    [Path in `${string}.${string}`]?: unknown;
+};
+/**
+ * What an update writes: the document's own fields, checked against the
+ * schema, or MongoDB's operators for what they cannot say.
+ */
+export type Patch<Def> = Partial<DocumentOf<Def>> | (UpdateOperators<Def> & {
+    [K in keyof DocumentOf<Def>]?: never;
+} & {
+    id?: never;
+});
+export interface ReadOptions {
+    /** Include soft-deleted documents. Ignored without a `deletedAt` field. */
+    withDeleted?: boolean;
+}
+export interface FindFirstOptions<Def> extends ReadOptions {
+    sort?: SortOf<Def>;
+    projection?: ProjectionOf<Def>;
+}
+export interface FindManyOptions<Def> extends FindFirstOptions<Def> {
+    filter?: Filter<DocumentOf<Def>>;
+    limit?: number;
+    skip?: number;
+}
+export interface PaginateOptions<Def> extends PageOptions, ReadOptions {
+    filter?: Filter<DocumentOf<Def>>;
+    /** Default `{ _id: 1 }`, so that pages are stable. */
+    sort?: SortOf<Def>;
+}
+export interface CursorPaginateOptions<Def> extends ReadOptions {
+    /** The `nextCursor` of the previous page. Omit it for the first page. */
+    after?: string | null | undefined;
+    /** Documents per page. Default `20`, at most `maxPageSize`. */
+    limit?: number;
+    filter?: Filter<DocumentOf<Def>>;
+    /**
+     * The field to page along. Default `_id`. Any other is followed by `_id`,
+     * which breaks its ties, and must be set on every document.
+     */
+    orderBy?: FieldOf<Def>;
+    /** Default `'asc'`. */
+    direction?: OrderDirection;
+}
+export interface UpdateOptions {
+    /**
+     * Only update the document while its `version` is still this one. When it
+     * is not, nothing is written and `OptimisticLockError` is thrown with the
+     * version the document has now.
+     */
+    expectedVersion?: number;
+}
+export interface CollectionOptions<Def> {
+    /**
+     * Soft delete through the `deletedAt` field. Default: on when the schema
+     * has one. `false` makes `delete` a real delete.
+     */
+    softDelete?: boolean;
+    /**
+     * Set `updatedAt` on every update that does not set it. Default: on when
+     * the schema has the field.
+     */
+    touchUpdatedAt?: boolean;
+    /**
+     * Raise `version` by one on every update. Default: on when the schema has
+     * the field. `expectedVersion` needs it.
+     */
+    optimisticLock?: boolean;
+    /**
+     * Check documents against the schema before writing them, which is also
+     * what fills their defaults. Default `'parse'`. `'off'` sends them as they
+     * are — and then nothing fills `_id`, `createdAt` or `version`.
+     */
+    validate?: 'parse' | 'off';
+    /** The largest `pageSize` or `limit` a page may ask for. Default `100`. */
+    maxPageSize?: number;
+    /** The session every operation runs in. `withSession` is how it is set. */
+    session?: ClientSession;
+    /** Who is writing, stamped into `createdBy`, `updatedBy` and `deletedBy`. */
+    actor?: ActorOf<Def>;
+    /** Which database, when `getCollection` is given a client rather than a `Db`. */
+    db?: string;
+}
+/**
+ * What this package adds to a collection. The collection you are handed is
+ * this **and** the driver's own `Collection`, so `aggregate`, `watch`,
+ * `bulkWrite` and the rest are on it directly.
+ */
+export interface CollectionApi<Def> {
+    readonly definition: Def;
+    readonly db: Db;
+    /**
+     * The driver's collection, untouched. It is where the three methods this
+     * one redefines still live — `raw.updateMany`, `raw.deleteMany` and
+     * `raw.count` — and where an update operator this package does not name
+     * can still be sent.
+     */
+    readonly raw: DriverCollection<DocumentOf<Def>>;
+    /** The session every operation of this collection runs in, if any. */
+    readonly session: ClientSession | undefined;
+    /**
+     * The same collection, bound to a session. MongoDB has no ambient session:
+     * without this, an operation inside a transaction runs outside it.
+     *
+     * It binds **this package's** methods. A driver method reached through the
+     * collection takes its session the driver's way, in its options.
+     */
+    withSession(session: ClientSession | undefined): TypedCollection<Def>;
+    /** The same collection, stamping this actor into the `*By` fields. */
+    as(actor: ActorOf<Def>): TypedCollection<Def>;
+    /** Creates the collection, its validator and its indexes. See `syncCollection`. */
+    sync(options?: SyncOptions): Promise<SyncReport>;
+    /** The document with this `_id`, or `undefined`. */
+    findById(id: IdOf<Def>, options?: ReadOptions): Promise<ReadDocumentOf<Def> | undefined>;
+    /** The document with this `_id`. Throws `NotFoundError`. */
+    getById(id: IdOf<Def>, options?: ReadOptions): Promise<ReadDocumentOf<Def>>;
+    /** The first document that matches, or `undefined`. */
+    findFirst(filter?: Filter<DocumentOf<Def>>, options?: FindFirstOptions<Def>): Promise<ReadDocumentOf<Def> | undefined>;
+    /** Every document that matches. */
+    findMany(options?: FindManyOptions<Def>): Promise<ReadDocumentOf<Def>[]>;
+    /** Checks the document against the schema, fills its defaults, inserts it. */
+    create(values: NewDocumentOf<Def>): Promise<ReadDocumentOf<Def>>;
+    /** The same, in one insert. `[]` sends nothing. */
+    createMany(values: readonly NewDocumentOf<Def>[]): Promise<ReadDocumentOf<Def>[]>;
+    /** Updates the document with this `_id` and returns it. Throws `NotFoundError`. */
+    update(id: IdOf<Def>, patch: Patch<Def>, options?: UpdateOptions): Promise<ReadDocumentOf<Def>>;
+    /**
+     * Updates every document that matches, and returns how many changed. The
+     * driver's own `updateMany`, which returns an `UpdateResult` and takes no
+     * filter for granted, is `raw.updateMany`.
+     */
+    updateMany(filter: Filter<DocumentOf<Def>>, patch: Patch<Def>): Promise<number>;
+    /**
+     * Deletes the document with this `_id` and returns it: a soft delete on a
+     * collection with `deletedAt`. Throws `NotFoundError`.
+     */
+    delete(id: IdOf<Def>): Promise<ReadDocumentOf<Def>>;
+    /** Deletes every document that matches, and returns how many. `raw.deleteMany` is the driver's. */
+    deleteMany(filter: Filter<DocumentOf<Def>>): Promise<number>;
+    /** A real delete, of a live or a soft-deleted document. */
+    hardDelete(id: IdOf<Def>): Promise<ReadDocumentOf<Def>>;
+    /** A real delete of every document that matches, soft-deleted ones included. */
+    hardDeleteMany(filter: Filter<DocumentOf<Def>>): Promise<number>;
+    /** Clears `deletedAt` and returns the document. Throws `NotFoundError`. */
+    restore(id: IdOf<Def>): Promise<ReadDocumentOf<Def>>;
+    /**
+     * How many documents match, soft-deleted ones left out. The driver's
+     * `count` is `raw.count`, and `estimatedDocumentCount` is on this
+     * collection directly.
+     */
+    count(filter?: Filter<DocumentOf<Def>>, options?: ReadOptions): Promise<number>;
+    /** Whether any document matches. */
+    exists(filter: Filter<DocumentOf<Def>>, options?: ReadOptions): Promise<boolean>;
+    /** One page of the documents that match, and how many there are. */
+    paginate(options?: PaginateOptions<Def>): Promise<Page<ReadDocumentOf<Def>>>;
+    /** One page of the documents that match, after a cursor. */
+    paginateByCursor(options?: CursorPaginateOptions<Def>): Promise<CursorPage<ReadDocumentOf<Def>>>;
+}
+/**
+ * A collection: this package's methods, plus every method of the driver's own
+ * `Collection` that they do not redefine.
+ *
+ * Three names are defined by both, and this package's win: `count`,
+ * `updateMany` and `deleteMany`. The driver's are on `raw`.
+ */
+export type TypedCollection<Def> = CollectionApi<Def> & Omit<DriverCollection<DocumentOf<Def>>, keyof CollectionApi<Def>>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/collection/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/collection/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,aAAa,EACb,EAAE,EACF,UAAU,IAAI,gBAAgB,EAC9B,MAAM,EACN,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EACX,UAAU,EACV,OAAO,EACP,IAAI,EACJ,aAAa,EACb,cAAc,EACd,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;AAExE,gEAAgE;AAChE,KAAK,eAAe,CAAC,GAAG,IAAI;KAC1B,CAAC,IAAI,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK;CAChE,CAAC,MAAM,GAAG,CAAC,GACX,MAAM,CAAC;AAER,sEAAsE;AACtE,KAAK,aAAa,CAAC,GAAG,IAAI;KACxB,CAAC,IAAI,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,GAAG,CAAC,GAAG,KAAK;CAC5E,CAAC,MAAM,GAAG,CAAC,GACX,MAAM,CAAC;AAER,KAAK,SAAS,CAAC,CAAC,IACf,WAAW,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,OAAO,CAAC,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI;KACxB,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM;CACnD,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAC3B;IAAE,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACrC;IAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,GAAG,IAAI;KAC9B,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,OAAO,GAAG,kBAAkB;CAChE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,WAAW,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,GACjE,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,GACzC,WAAW,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,GACxC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,GACzC,WAAW,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,GACxC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,GACzC,KAAK,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,KAAK,CAAC,GAAG,IAAI;KACvB,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,GAC5D,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GACtB,OAAO;CACV,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,GAAG;IACnC,IAAI,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,YAAY,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,CAAC,EAAE;SAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI;KAAE,CAAC;IACvD,IAAI,CAAC,EAAE;SACL,KAAK,IACH,eAAe,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAChC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;KACxC,CAAC;IACF,IAAI,CAAC,EAAE;SACL,KAAK,IACH,eAAe,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAChC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;KACxC,CAAC;IACF,IAAI,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,IAAI,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,OAAO,CAAC,EAAE;SAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM;KAAE,CAAC;IACjD,YAAY,CAAC,EAAE;SACb,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG;YAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAA;SAAE;KAClE,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,KAAK,CAAC,EAAE;SAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO;KAAE,CAAC;IAChD,QAAQ,CAAC,EAAE;SAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,OAAO,EAAE;KAAE,CAAC;IAC9D,IAAI,CAAC,EAAE;SAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;KAAE,CAAC;CAC9C;AAED,8EAA8E;AAC9E,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI;KACxB,KAAK,IAAI,aAAa,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACvC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GACjC;QACA,KAAK,EAAE,SAAS,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KACvC;CAEJ,GAAG;KAAG,IAAI,IAAI,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO;CAAE,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,GAAG,IAClB,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAGxB,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG;KACvB,CAAC,IAAI,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;CACnC,GAAG;IAIJ,EAAE,CAAC,EAAE,KAAK,CAAC;CACV,CAAC,CAAC;AAEN,MAAM,WAAW,WAAW;IAC3B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB,CAAC,GAAG,CAAE,SAAQ,WAAW;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACnB,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe,CAAC,GAAG,CAAE,SAAQ,gBAAgB,CAAC,GAAG,CAAC;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe,CAAC,GAAG,CAAE,SAAQ,WAAW,EAAE,WAAW;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB,CAAC,GAAG,CAAE,SAAQ,WAAW;IAC9D,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,uBAAuB;IACvB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB,CAAC,GAAG;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,iFAAiF;IACjF,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG;IACjC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAE5C;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACtE,sEAAsE;IACtE,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAC9C,mFAAmF;IACnF,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEjD,oDAAoD;IACpD,QAAQ,CACP,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EACb,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,4DAA4D;IAC5D,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5E,uDAAuD;IACvD,SAAS,CACR,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAC7B,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,mCAAmC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEzE,8EAA8E;IAC9E,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,mDAAmD;IACnD,UAAU,CACT,MAAM,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,GACnC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClC,mFAAmF;IACnF,MAAM,CACL,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EACb,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,OAAO,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC;;;;OAIG;IACH,UAAU,CACT,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GACf,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,mGAAmG;IACnG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,2DAA2D;IAC3D,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,2EAA2E;IAC3E,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD;;;;OAIG;IACH,KAAK,CACJ,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,oCAAoC;IACpC,MAAM,CACL,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAC/B,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC7E,4DAA4D;IAC5D,gBAAgB,CACf,OAAO,CAAC,EAAE,qBAAqB,CAAC,GAAG,CAAC,GAClC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,GACpD,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC"}

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

@@ -1,4 +1,4 @@
-import type { IndexDescription, ObjectId } from 'mongodb';
+import type { IndexDescription, IndexDirection, ObjectId } from 'mongodb';
 import type { z } from 'zod';
 /** What MongoDB does with a document that fails the validator. */
 export type ValidationAction = 'error' | 'warn';
@@ -13,6 +13,23 @@ export interface ValidationConfig {
     /** Default `'error'`. `'warn'` logs and lets the write through. */
     action?: ValidationAction;
 }
+/**
+ * What an index may be keyed on: a field of the documents, which an editor
+ * completes, or a path into one — `{ 'address.city': 1 }` is how MongoDB
+ * indexes a nested field, and there is no way to check the tail of a path
+ * against a schema without rejecting the paths Mongo allows.
+ */
+export type IndexKey<Doc> = {
+    [Field in (keyof Doc & string) | `${keyof Doc & string}.${string}`]?: IndexDirection;
+} | Map<string, IndexDirection>;
+/**
+ * An index, keyed on the schema's own fields. Everything else — `unique`,
+ * `name`, `collation`, `partialFilterExpression`, the TTL — is the driver's
+ * `IndexDescription`, unchanged.
+ */
+export interface CollectionIndex<Doc> extends Omit<IndexDescription, 'key'> {
+    key: IndexKey<Doc>;
+}
 /** What `defineCollection` takes. */
 export interface CollectionConfig<Schema extends z.ZodObject> {
     /** The collection's name on the server. */
@@ -22,13 +39,16 @@ export interface CollectionConfig<Schema extends z.ZodObject> {
      * `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 indexes `sync` creates, keyed on the schema's fields. */
+    indexes?: readonly CollectionIndex<z.output<Schema>>[];
     /** 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>> {
+export interface CollectionDefinition<Schema extends z.ZodObject = z.ZodObject> {
+    readonly name: string;
+    readonly schema: Schema;
+    /** As the driver takes them: `sync` hands these straight to MongoDB. */
     readonly indexes: readonly IndexDescription[];
     readonly validation: Required<ValidationConfig>;
 }
@@ -38,6 +58,18 @@ export type AnyCollectionDefinition = CollectionDefinition<any>;
 export type DocumentOf<Def> = Def extends {
     schema: infer Schema;
 } ? Schema extends z.ZodType ? z.output<Schema> : never : never;
+/**
+ * A document as a collection gives it back: the stored document, plus `id`.
+ *
+ * `id` is `_id` as a string, computed rather than stored — the collection
+ * holds `_id` alone. It is enumerable, so `JSON.stringify` and a spread carry
+ * it, which is what makes a document ready to return from an API; it is not
+ * part of `DocumentOf`, so a filter or a patch cannot be keyed on it, because
+ * the server would match nothing.
+ */
+export type ReadDocumentOf<Def> = DocumentOf<Def> & {
+    readonly id: string;
+};
 /** What a write takes: the documents before their defaults are filled. */
 export type NewDocumentOf<Def> = Def extends {
     schema: infer Schema;
@@ -69,7 +101,7 @@ export type FieldOf<Def> = keyof DocumentOf<Def> & string;
  * ```
  */
 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. */
+/** Which of the fields the collection knows about a definition's schema has. */
 export declare function stampsOf(definition: AnyCollectionDefinition): {
     createdAt: boolean;
     updatedAt: boolean;