@nxgt/mongo 0.2.0 → 0.3.1

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(),
@@ -109,29 +111,52 @@ 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' });
+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
@@ -192,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
@@ -259,7 +289,7 @@ server error reaches you untouched.
 | `id`, `objectId`, `timestamps`, `softDelete`, `optimisticLock`, `actors` | the field helpers |
 | `toObjectId`, `toObjectIds`, `tryObjectId`, `objectIdParam` | a string from outside as an `ObjectId` |
 | `isValidObjectId`, `isObjectIdString`, `isObjectId` | the checks behind them |
-| `createRepository(db, definition, options?)` | the typed repository |
+| `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` |
@@ -267,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`

package/dist/collection/context.d.ts

@@ -0,0 +1,64 @@
+import type { ClientSession, Db, Collection as DriverCollection } from 'mongodb';
+import type { z } from 'zod';
+import { type AnyCollectionDefinition, stampsOf } from '../definition/define-collection';
+import { NotFoundError } from '../errors/data-error';
+import type { CollectionOptions } from './types';
+/** Which of the fields the collection knows about a schema has. */
+type Stamps = ReturnType<typeof stampsOf>;
+/**
+ * What every method of a collection works from, resolved once: the
+ * definition, the driver's collection, and the options once they have been
+ * read against the schema.
+ *
+ * It holds **data only**. The operations are plain functions that take it as
+ * their first argument, in `filters.ts`, `documents.ts`, `reads.ts`,
+ * `writes.ts` and `paginate.ts` — a context of closures would only be the
+ * factory this package split up, one size down.
+ *
+ * `withSession` and `as` build another one, cheaply: they are the same
+ * collection with a single option changed.
+ */
+export interface CollectionContext {
+    readonly definition: AnyCollectionDefinition;
+    readonly db: Db;
+    /**
+     * The driver's collection, typed loosely on purpose: this layer works on
+     * any documents, and the public type is what callers see.
+     */
+    readonly collection: DriverCollection<any>;
+    readonly name: string;
+    readonly shape: Record<string, z.ZodType>;
+    readonly stamps: Stamps;
+    /** Who is writing, stamped into the `*By` fields. */
+    readonly actor: unknown;
+    readonly session: ClientSession | undefined;
+    /** `{ session }` when there is one, to spread into the driver's options. */
+    readonly sessionOption: {
+        session?: ClientSession;
+    };
+    readonly maxPageSize: number;
+    /**
+     * Whether the schema declares an `id` field of its own. Then `id` is that
+     * field's, and this package neither computes it nor drops it.
+     */
+    readonly hasOwnId: boolean;
+    /** Whether a write is checked against the schema, which fills its defaults. */
+    readonly parses: boolean;
+    /** Whether `delete` writes `deletedAt` rather than removing the document. */
+    readonly softDeletes: boolean;
+    /** Whether an update that does not set `updatedAt` gets it set. */
+    readonly touches: boolean;
+    /** Whether an update raises `version`. */
+    readonly locks: boolean;
+}
+/**
+ * Resolves a collection's options against its schema, and refuses the two
+ * that cannot be honoured: a soft delete without `deletedAt`, and an
+ * optimistic lock without `version`.
+ */
+export declare function createContext(db: Db, definition: AnyCollectionDefinition, options: CollectionOptions<never>): CollectionContext;
+/** Runs an operation, turning a MongoDB error into a `DataError`. */
+export declare function run<T>(ctx: CollectionContext, fn: () => Promise<T>): Promise<T>;
+export declare function notFound(ctx: CollectionContext, id: unknown): NotFoundError;
+export {};
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/collection/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,aAAa,EACb,EAAE,EACF,UAAU,IAAI,gBAAgB,EAC9B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EACN,KAAK,uBAAuB,EAC5B,QAAQ,EACR,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,mEAAmE;AACnE,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE;QAAE,OAAO,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,EAAE,EAAE,EAAE,EACN,UAAU,EAAE,uBAAuB,EACnC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC/B,iBAAiB,CAkCnB;AAED,qEAAqE;AACrE,wBAAsB,GAAG,CAAC,CAAC,EAC1B,GAAG,EAAE,iBAAiB,EACtB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,OAAO,GAAG,aAAa,CAK3E"}

package/dist/collection/documents.d.ts

@@ -0,0 +1,21 @@
+import type { CollectionContext } from './context';
+import { type Fields } from './filters';
+/**
+ * `id` on a document a collection gives back: `_id` as a string, computed
+ * rather than stored — the collection holds `_id` alone.
+ *
+ * It is enumerable, so `JSON.stringify` and a spread carry it and a handler
+ * can return the document as it is. `toDocument` drops it again on a write,
+ * and it is no part of `DocumentOf`, so nothing can filter on it: the server
+ * would match nothing.
+ */
+export declare function withId<T>(ctx: CollectionContext, document: T): T;
+/** The document to insert: checked against the schema, defaults filled. */
+export declare function toDocument(ctx: CollectionContext, values: unknown): Fields;
+/**
+ * The update to send: a patch of fields becomes `$set`, checked field by
+ * field against the schema, with the stamps this collection keeps. A patch
+ * that already speaks in operators is sent as it is, with the stamps added.
+ */
+export declare function toUpdate(ctx: CollectionContext, patch: unknown): Fields;
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/collection/documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,MAAM,EAA4B,MAAM,WAAW,CAAC;AAElE;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAehE;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAkB1E;AAkBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CA6BvE"}

package/dist/collection/filters.d.ts

@@ -0,0 +1,15 @@
+import type { CollectionContext } from './context';
+/** A document as this package handles one internally: keys it cannot know. */
+export type Fields = Record<string, unknown>;
+export declare function isRecord(value: unknown): value is Fields;
+/** Does this patch speak in MongoDB's operators rather than in fields? */
+export declare function isUpdateFilter(patch: Fields): boolean;
+/** `a` and `b`, without letting one's `$or` swallow the other's. */
+export declare function mergeFilters(a: Fields | undefined, b: Fields | undefined): Fields;
+/** The filter that leaves soft-deleted documents out. */
+export declare function live(ctx: CollectionContext, withDeleted?: boolean): Fields | undefined;
+/** A caller's filter, narrowed to the documents this collection shows. */
+export declare function scoped(ctx: CollectionContext, filter: unknown, withDeleted?: boolean): Fields;
+/** Refuses a call that would otherwise run on the whole collection. */
+export declare function requireFilter(ctx: CollectionContext, method: string, filter: unknown): void;
+//# sourceMappingURL=filters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/collection/filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAC3B,CAAC,EAAE,MAAM,GAAG,SAAS,EACrB,CAAC,EAAE,MAAM,GAAG,SAAS,GACnB,MAAM,CAMR;AAED,yDAAyD;AACzD,wBAAgB,IAAI,CACnB,GAAG,EAAE,iBAAiB,EACtB,WAAW,CAAC,EAAE,OAAO,GACnB,MAAM,GAAG,SAAS,CAEpB;AAED,0EAA0E;AAC1E,wBAAgB,MAAM,CACrB,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,OAAO,GACnB,MAAM,CAKR;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAC5B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GACb,IAAI,CAMN"}

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,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAEX,oBAAoB,EACpB,MAAM,iCAAiC,CAAC;AAazC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAalE,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/paginate.d.ts

@@ -0,0 +1,6 @@
+import { type CursorPage, type Page } from '../pagination/page';
+import type { CollectionContext } from './context';
+import { type Fields } from './filters';
+export declare function paginate(ctx: CollectionContext, opts?: Fields): Promise<Page<Fields>>;
+export declare function paginateByCursor(ctx: CollectionContext, opts?: Fields): Promise<CursorPage<Fields>>;
+//# sourceMappingURL=paginate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../../src/collection/paginate.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,UAAU,EAEf,KAAK,IAAI,EAGT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,MAAM,EAA0B,MAAM,WAAW,CAAC;AAIhE,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE,MAAW,GACf,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAevB;AAED,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE,MAAW,GACf,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CA+D7B"}

package/dist/collection/reads.d.ts

@@ -0,0 +1,19 @@
+import { type CollectionContext } from './context';
+import { type Fields } from './filters';
+/** One document, straight from the driver, carrying its computed `id`. */
+export declare function findOne(ctx: CollectionContext, filter: Fields, projection?: unknown): Promise<Fields | null>;
+export declare function findById(ctx: CollectionContext, id: unknown, opts?: {
+    withDeleted?: boolean;
+}): Promise<Fields | undefined>;
+export declare function getById(ctx: CollectionContext, id: unknown, opts?: {
+    withDeleted?: boolean;
+}): Promise<Fields>;
+export declare function findMany(ctx: CollectionContext, opts?: Fields): Promise<Fields[]>;
+export declare function findFirst(ctx: CollectionContext, filter?: unknown, opts?: Fields): Promise<Fields | undefined>;
+export declare function countDocuments(ctx: CollectionContext, filter?: unknown, opts?: {
+    withDeleted?: boolean;
+}): Promise<number>;
+export declare function exists(ctx: CollectionContext, filter: unknown, opts?: {
+    withDeleted?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=reads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/collection/reads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAiB,MAAM,WAAW,CAAC;AAElE,OAAO,EAAE,KAAK,MAAM,EAAU,MAAM,WAAW,CAAC;AAEhD,0EAA0E;AAC1E,wBAAgB,OAAO,CACtB,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,iBAAiB,EACtB,EAAE,EAAE,OAAO,EACX,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAED,wBAAsB,OAAO,CAC5B,GAAG,EAAE,iBAAiB,EACtB,EAAE,EAAE,OAAO,EACX,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE,MAAW,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAenB;AAED,wBAAsB,SAAS,CAC9B,GAAG,EAAE,iBAAiB,EACtB,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAW,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAED,wBAAsB,cAAc,CACnC,GAAG,EAAE,iBAAiB,EACtB,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,wBAAsB,MAAM,CAC3B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,OAAO,EACf,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,OAAO,CAAC,CAKlB"}

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