@nxgt/mongo-kit 0.1.3 → 0.1.5

package/README.md

@@ -268,6 +268,21 @@ Each is a `@ts-expect-error` case in this package's type tests.
 - **`kit.db` throws on a kit with several databases**, where its type is
   already `never`: the message names the databases to read instead.
 
+## Documentation
+
+- [Guide index](docs/README.md) — every page, and when to read it.
+- [Configuration](docs/guide/configuration.md) — the databases, the
+  collections, and the options each is built with.
+- [The `db` scope](docs/guide/db-scope.md) — the collections on the driver's
+  `Db`, and the kit in a request.
+- [The actor, sessions and transactions](docs/guide/actor-and-transactions.md)
+  — `as`, `withSession` and `transaction`.
+- [Syncing](docs/guide/sync.md) — the deployment step, and `dryRun`.
+- [`discoverCollections`](docs/guide/discover-collections.md) — definitions
+  from a glob, for scripts.
+- [Troubleshooting](docs/troubleshooting.md) — the errors, by their message.
+- [Roadmap](docs/roadmap.md) — what is next, and what is not planned.
+
 ## License
 
 MIT

package/docs/README.md

@@ -0,0 +1,14 @@
+# `@nxgt/mongo-kit` documentation
+
+The [README](../README.md) is the short version: what the package is, and one
+example per area. These pages are the long one.
+
+| Page | Read it when |
+| --- | --- |
+| [Configuration](guide/configuration.md) | you are describing the databases and the collections of an application, one database or several |
+| [The `db` scope](guide/db-scope.md) | you are reading `kit.db.users`, reaching for something only the driver's `Db` has, or wondering when a collection is built |
+| [The actor, sessions and transactions](guide/actor-and-transactions.md) | a write has to be stamped with who made it, or several writes have to commit together |
+| [Syncing](guide/sync.md) | the collections, their validators and their indexes have to exist on the server |
+| [`discoverCollections`](guide/discover-collections.md) | a script has to find the definitions of a repository without importing each one |
+| [Troubleshooting](troubleshooting.md) | something threw, and you have the message |
+| [Roadmap](roadmap.md) | you want to know what is coming, and what will not |

package/docs/guide/actor-and-transactions.md

@@ -0,0 +1,196 @@
+# The actor, sessions and transactions
+
+Who a write is stamped as, and which writes commit together. Both are kits of
+their own: `as`, `withSession` and `transaction` give back **another kit**
+over the same clients, and leave the one they came from alone.
+
+```ts
+import { ObjectId } from 'mongodb';
+import { kit } from './db'; // the kit `createKit` returned
+
+const actor = new ObjectId();
+
+const post = await kit.as(actor).db.posts.create({ title: 'a' });
+post.createdBy; // the actor
+
+const plain = await kit.db.posts.create({ title: 'b' });
+plain.createdBy; // null — the kit it came from never changed
+```
+
+## `as(actor)`
+
+One call stamps every collection of the kit: `createdBy` on a create,
+`updatedBy` on an update, `deletedBy` on a soft delete — whichever stamps the
+definition asked for.
+
+```ts
+const writer = kit.as(actor);
+await writer.db.users.create({ email: 'ada@example.com' }); // createdBy
+await writer.db.posts.create({ title: 'a' });               // createdBy
+writer.actor;                    // the actor
+writer.clients.default === kit.clients.default; // the same client
+writer.db.users !== kit.db.users;               // its own collections
+```
+
+The actor's **type** is the one the collections agree on: a kit whose
+collections all stamp an `ObjectId` takes an `ObjectId`. A kit whose
+collections stamp no actor has no `as` to call — its type is `never` — and so
+does one whose collections stamp actors of different types, since a single
+call could not stamp both.
+
+```ts
+type KitActor<C>; // the intersection of every wired definition's ActorOf
+```
+
+## `withSession(session)`
+
+The kit's collections all run in that session; `undefined` takes it away
+again.
+
+```ts
+const session = kit.clients.default.startSession();
+try {
+	const inSession = kit.withSession(session);
+	await inSession.db.users.create({ email: 'ada@example.com' });
+	inSession.withSession(undefined).session; // undefined
+} finally {
+	await session.endSession();
+}
+```
+
+`as` and `withSession` compose, in either order, and each keeps what the
+other set.
+
+## `transaction(fn, options?)`
+
+The body is given a kit whose collections are **all** in the transaction:
+nothing has to be threaded through.
+
+```ts
+const written = await kit.as(actor).transaction(async (tx) => {
+	const team = await tx.db.teams.create({ name: 'Core' });
+	await tx.db.users.update(userId, { teamId: team._id });
+	return team;
+});
+```
+
+If the body throws, everything it wrote is rolled back and the error comes
+back out:
+
+```ts
+await kit.transaction(async (tx) => {
+	await tx.db.users.create({ email: 'ada@example.com' });
+	throw new Error('no');
+});
+// rejects with 'no'; the user is not there
+await kit.db.users.count(); // 0
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `on` | `DbName<C>` | the only client | Which database's client carries the transaction. Required once the kit holds more than one **client** |
+| `readConcern`, `writeConcern`, `readPreference`, `maxCommitTimeMS` | the driver's `TransactionOptions` | the client's | Passed to the driver as they are |
+
+```ts
+await kit.transaction(
+	(tx) => tx.db.users.create({ email: 'ada@example.com' }),
+	{ readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } },
+);
+```
+
+### What the body must accept
+
+- **It may run twice.** The driver retries it from the start on a transient
+  error, so it must hold nothing MongoDB would not roll back — no email sent,
+  no counter raised in Redis, no file written.
+- **A transaction inside a transaction joins the outer one**, and takes no
+  `on`: the session has already decided. MongoDB has no savepoints, so an
+  inner failure takes the whole transaction with it.
+- **It reaches one client's databases.** With `{ on: 'main' }`, an operation
+  on a database of another client carries a session that client does not own,
+  and the driver refuses it.
+- **A replica set is required**, which is MongoDB's own rule for
+  transactions, not this package's.
+
+```ts
+await kit.transaction(async (outer) => {
+	await outer.db.users.create({ email: 'ada@example.com' });
+	await outer.transaction(async (inner) => {
+		inner.session === outer.session; // true: it joined
+		await inner.db.posts.create({ title: 'a' });
+	});
+});
+```
+
+`{ on }` is required at **run time**, not by the types, and cannot be: two
+databases on one URI share a client and need none, so what decides is the
+number of clients. A kit holding two without it throws a `TypeError` naming
+what to write.
+
+## In a request
+
+The kit is built once; each request derives the kit that stamps its user, and
+a handler is handed services built on it rather than the kit itself.
+
+```ts
+import { tryObjectId } from '@nxgt/mongo';
+import { createMiddleware } from 'hono/factory';
+import type { Kit } from '../db';
+import { buildServices } from '../context';
+
+export const provideServices = (kit: Kit) =>
+	createMiddleware(async (c, next) => {
+		const actor = tryObjectId(c.req.header('x-user-id'));
+		if (!actor) return c.json({ message: 'errors.unauthenticated' }, 401);
+		c.set('services', buildServices(kit.as(actor)));
+		await next();
+	});
+```
+
+```ts
+export class TeamService {
+	constructor(private readonly kit: Kit) {}
+
+	/** Two collections, one commit — and both writes stamped with the request's user. */
+	createWithOwner(name: string, ownerId: ObjectId) {
+		return this.kit.transaction(async (tx) => {
+			const team = await tx.db.teams.create({ name });
+			await tx.db.users.update(ownerId, { teamId: team._id });
+			return team;
+		});
+	}
+}
+```
+
+The service holds the request's kit, so `this.kit.transaction` already stamps
+the right actor: the transaction inherits it.
+
+## Closing a derived kit
+
+`close()` on a kit from `as`, `withSession` or a transaction throws — the
+clients belong to the kit `createKit` returned, and that is the one to close.
+
+## Signatures
+
+```ts
+type KitActor<C> = [ActorOf<WiredDefinition<C>>] extends [never]
+	? never
+	: UnionToIntersection<ActorOf<WiredDefinition<C>>>;
+
+type KitTransactionOptions<C> = TransactionOptions & { on?: DbName<C> };
+
+interface MongoKit<C> {
+	as(actor: KitActor<C>): MongoKit<C>;
+	withSession(session: ClientSession | undefined): MongoKit<C>;
+	transaction<T>(
+		fn: (kit: MongoKit<C>) => Promise<T>,
+		options?: KitTransactionOptions<C>,
+	): Promise<T>;
+}
+```
+
+## Next
+
+- [The `db` scope](db-scope.md) — what a derived kit shares, and what it
+  builds again.
+- [Troubleshooting](../troubleshooting.md) — the messages these refusals use.

package/docs/guide/configuration.md

@@ -0,0 +1,229 @@
+# Configuration
+
+`defineConfig` describes an application's MongoDB — where each database is,
+and which collections live on it — and checks that description before
+anything connects.
+
+```ts
+import { defineConfig } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+export const config = defineConfig({
+	uri: process.env.MONGO_URI!,
+	collections,
+});
+```
+
+It opens no socket and reads no environment variable of its own: the
+application reads `process.env`, and what is wrong with the configuration
+throws here, where the application starts, rather than at the first query.
+[`createKit`](db-scope.md) is what connects.
+
+## The collections
+
+`collections` is a module object, the one `import * as` gives:
+
+```ts
+// src/models/index.ts
+export * from './users.model';
+export * from './posts.model';
+```
+
+```ts
+// src/models/users.model.ts
+import { defineCollection, id, objectId } from '@nxgt/mongo';
+import { z } from 'zod';
+
+export const users = defineCollection({
+	name: 'users',
+	schema: z.object({
+		_id: id(),
+		email: z.string(),
+		name: z.string().optional(),
+	}),
+	timestamps: true,
+	actors: { type: objectId() },
+	indexes: [{ key: { email: 1 }, unique: true, name: 'users_email_unique' }],
+});
+```
+
+Every export that is a `defineCollection` becomes a key on the scope, under
+the name it is **exported** by; a function, a constant or a type in the same
+module is left where it is. The key is what the application reads
+(`kit.db.users`) and the definition's own `name` is what the server holds, so
+`export const users = defineCollection({ name: 'app_users', … })` is
+`kit.db.users` here and `app_users` there.
+
+Two exports pointing at one server collection are refused, and so is a key
+the driver's `Db` already answers to (`command`, `watch`, `collection`, …):
+it would be unreachable on the scope. Both are compile errors, and both are
+checked again against the object at `createKit`.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `uri` | `string` | — | Where to connect. One of `uri` and `client`, never both |
+| `client` | `MongoClient` | — | A client the application opened. The kit uses it and never closes it |
+| `clientOptions` | `MongoClientOptions` | `{}` | Passed to the driver with `uri`. Refused beside `client`, which has its own |
+| `database` | `string` | the URI's, else `test` | The database's name |
+| `collections` | module object | — | `import * as collections from './models'` |
+| `options` | `KitCollectionOptions<AnyCollectionDefinition>` | `{}` | `@nxgt/mongo`'s collection options, for every collection of this database |
+| `optionsFor` | `{ [key]?: KitCollectionOptions<Def> }` | `{}` | The same, per key, merged **over** `options` |
+| `autoSync` | `boolean` | `false` | Sync each collection before its first operation |
+
+`options` and `optionsFor` take `@nxgt/mongo`'s own collection options —
+`maxPageSize`, `coerce`, `validate`, `softDelete`, `touchUpdatedAt`,
+`optimisticLock`, `hooks` — minus the four the kit decides itself:
+
+```ts
+defineConfig({
+	uri: process.env.MONGO_URI!,
+	collections,
+	options: { maxPageSize: 50 },
+	optionsFor: { posts: { softDelete: false } },
+});
+```
+
+`db`, `session`, `actor` and `autoSync` are **not** collection options here.
+The database is named by its key, [`as` and `withSession`](actor-and-transactions.md)
+carry the actor and the session, and `autoSync` is the database's. One of
+them under `options` does not compile; under `optionsFor` the types cannot
+see that deep, and `defineConfig` throws instead.
+
+`optionsFor` under a key no collection is wired under does not compile
+either, and the message names the key.
+
+### `autoSync`
+
+```ts
+defineConfig({ uri: server.uri, collections, autoSync: true });
+```
+
+Each collection is synced before its first operation, once per database — for
+tests and for local development. In production [`kit.sync()`](sync.md) is a
+deployment step: `collMod` needs the `dbAdmin` role, and an index build runs
+outside any transaction.
+
+## Several databases
+
+They name themselves, and the names are the keys on `kit.databases` and on
+the sync report:
+
+```ts
+import { defineConfig } from '@nxgt/mongo-kit';
+import * as collections from './models';
+import * as events from './events';
+
+export const config = defineConfig({
+	databases: {
+		main: { uri: process.env.MONGO_URI!, collections },
+		analytics: {
+			uri: process.env.ANALYTICS_URI!,
+			database: 'analytics',
+			collections: events,
+		},
+	},
+});
+```
+
+Each entry takes the same keys as a lone database. A config that names none
+is held under `default`, so `kit.databases.default` is the long way of
+writing `kit.db`.
+
+Two databases on one URI **share one client** — that is what `connectMongo`
+already does — and must then be configured with the same `clientOptions`: a
+second hold on a client opened with other options is refused.
+
+## The kit's type
+
+`KitOf<typeof config>` is the type of the kit this config produces, for a
+service or a module that declares it rather than reading it off
+`await createKit(…)`:
+
+```ts
+import { defineConfig, type KitOf } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+export const config = defineConfig({
+	uri: process.env.MONGO_URI!,
+	collections,
+	options: { maxPageSize: 50 },
+});
+
+/** This application's kit, read from the configuration rather than written twice. */
+export type Kit = KitOf<typeof config>;
+```
+
+```ts
+import type { Kit } from './db';
+
+export class UserService {
+	constructor(private readonly kit: Kit) {}
+
+	create(input: { email: string }) {
+		return this.kit.db.users.create(input);
+	}
+}
+```
+
+## What it throws
+
+Every check is a `TypeError`, thrown from `defineConfig`, before anything
+connects. The message names the database it is about:
+
+```ts
+defineConfig({ collections });
+// TypeError: defineConfig: database "default" has neither a uri nor a client
+```
+
+- a database with both a `uri` and a `client`, or neither;
+- `clientOptions` beside a `client` the kit did not open;
+- a `collections` object with no definition in it — the usual cause is a
+  default export, or an object of schemas rather than of definitions;
+- two keys wiring the same server collection;
+- `optionsFor` under a key the database does not wire;
+- `db`, `session`, `actor` or `autoSync` inside `options` or `optionsFor`.
+
+[Troubleshooting](../troubleshooting.md) has each message with its fix.
+
+## Signatures
+
+```ts
+function defineConfig<const C extends KitConfigInput>(
+	config: C & Checked<C>,
+): KitConfig<C>;
+
+type KitConfigInput =
+	| DatabaseConfig<object>
+	| { databases: Record<string, DatabaseConfig<object>> };
+
+interface DatabaseConfig<C> {
+	uri?: string;
+	client?: MongoClient;
+	clientOptions?: MongoClientOptions;
+	database?: string;
+	collections: C;
+	options?: KitCollectionOptions<AnyCollectionDefinition>;
+	optionsFor?: {
+		[K in keyof CollectionsOf<C>]?: KitCollectionOptions<CollectionsOf<C>[K]>;
+	};
+	autoSync?: boolean;
+}
+
+type KitCollectionOptions<Def> = Omit<
+	CollectionOptions<Def>,
+	'db' | 'session' | 'actor' | 'autoSync'
+>;
+
+type KitOf<Config> = Config extends KitConfig<infer C> ? MongoKit<C> : never;
+```
+
+`CollectionsOf`, `CollectionsIn`, `DbName`, `NoCollision`, `ReservedName` and
+`Unwired` are exported too: they are what the refusals above are written
+with.
+
+## Next
+
+- [The `db` scope](db-scope.md) — what `createKit` gives back.
+- [Syncing](sync.md) — making the server match the definitions.

package/docs/guide/db-scope.md

@@ -0,0 +1,173 @@
+# The `db` scope
+
+`createKit` opens what the [configuration](configuration.md) describes and
+gives back a `MongoKit`, whose `db` is the driver's `Db` with every collection
+typed on it.
+
+```ts
+import { createKit, defineConfig } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+await using kit = await createKit(
+	defineConfig({ uri: process.env.MONGO_URI!, collections }),
+);
+
+const user = await kit.db.users.create({ email: 'ada@example.com' });
+const posts = await kit.db.posts.findMany({ filter: { authorId: user._id } });
+await kit.db.command({ ping: 1 }); // the driver's Db, untouched
+```
+
+`kit.db.users` is exactly what `getCollection(db, users)` gives — the
+driver's `Collection` with `@nxgt/mongo`'s pagination, soft delete,
+optimistic locking and stamps on it — so everything that package documents
+about a collection holds here.
+
+## What the kit holds
+
+| Member | Type | Effect |
+| --- | --- | --- |
+| `db` | `SoleScope<C>` | The only database's scope. `never` when the kit has several, and reading it anyway throws |
+| `databases` | `{ [name]: DbScope }` | Every scope, under the name the config gave it — `default` when it named none |
+| `clients` | `{ [name]: MongoClient }` | The client of each database. Two databases on one URI share one |
+| `actor` | `KitActor<C> \| undefined` | What this kit stamps into the `*By` fields |
+| `session` | `ClientSession \| undefined` | The session every collection of this kit runs in |
+| `as(actor)` | `MongoKit<C>` | [Another kit, stamping that actor](actor-and-transactions.md) |
+| `withSession(session)` | `MongoKit<C>` | [Another kit, in that session](actor-and-transactions.md) |
+| `transaction(fn, options?)` | `Promise<T>` | [`fn` with a kit in a transaction](actor-and-transactions.md) |
+| `sync(options?)` | `Promise<Record<DbName<C>, SyncReport[]>>` | [A deployment step](sync.md) |
+| `close()` | `Promise<void>` | Gives back what the kit opened. Idempotent |
+
+A kit is `AsyncDisposable`, so `await using kit = await createKit(config)`
+closes it at the end of the block.
+
+## The scope is a `Db` underneath
+
+The collections are own properties; everything else is read through to the
+driver's `Db`:
+
+```ts
+Object.keys(kit.db);            // ['users', 'posts'] — not the driver's members
+'users' in kit.db;              // true
+'command' in kit.db;            // true
+
+const { command } = kit.db;     // a driver method read off it is bound
+await command({ ping: 1 });
+kit.db.databaseName;            // 'app'
+```
+
+A collection is built the **first time it is read**, and kept:
+
+```ts
+kit.db.users === kit.db.users;  // true
+```
+
+So a kit derived per request pays for the collections that request touches
+and for no others.
+
+## Several databases
+
+```ts
+await kit.databases.main.users.create({ email: 'ada@example.com' });
+await kit.databases.analytics.events.create({ kind: 'signup' });
+kit.clients.main === kit.clients.analytics; // true when one URI wires both
+```
+
+`kit.db` is then `never`, and reading it anyway — from JavaScript, or across
+an `any` — throws a `TypeError` naming the databases to read instead: with
+two of them there is no "the" database.
+
+## Closing
+
+```ts
+await kit.close();
+```
+
+It gives back the clients it opened, and leaves alone a `client` the config
+handed it: what it did not open is not its to close, `await using` included.
+Only the kit `createKit` returned may be closed — one from `as`,
+`withSession` or a transaction shares those clients and throws.
+
+## In a request
+
+A kit is built once, at startup, and each request derives its own. Nothing
+else has to be wired: no `getCollection` at the call site, no client passed
+around.
+
+```ts
+// src/services/users.service.ts
+import type { Kit } from '../db';
+
+export class UserService {
+	constructor(private readonly kit: Kit) {}
+
+	list(page?: number) {
+		return this.kit.db.users.paginate({ page });
+	}
+
+	create(input: { email: string }) {
+		return this.kit.db.users.create(input);
+	}
+}
+```
+
+```ts
+// src/middlewares/services.ts
+import { tryObjectId } from '@nxgt/mongo';
+import { createMiddleware } from 'hono/factory';
+import type { Kit } from '../db';
+import { UserService } from '../services/users.service';
+
+export const provideServices = (kit: Kit) =>
+	createMiddleware(async (c, next) => {
+		const actor = tryObjectId(c.req.header('x-user-id'));
+		if (!actor) return c.json({ message: 'errors.unauthenticated' }, 401);
+		// One kit per request, stamping that user; the kit it came from is
+		// untouched, so a request's actor never leaks into the next.
+		c.set('services', { users: new UserService(kit.as(actor)) });
+		await next();
+	});
+```
+
+```ts
+// src/index.ts
+import { createKit } from '@nxgt/mongo-kit';
+import { buildApp } from './app';
+import { config } from './db';
+
+const kit = await createKit(config);
+Bun.serve({ fetch: buildApp(kit).fetch });
+```
+
+A handler reads `c.get('services')` and never reaches the kit itself, so it
+cannot write as somebody else and cannot close it.
+
+## Signatures
+
+```ts
+function createKit<C>(config: KitConfig<C>): Promise<MongoKit<C>>;
+
+type DbScope<C> = {
+	readonly [K in keyof CollectionsOf<C>]: TypedCollection<CollectionsOf<C>[K]>;
+} & Db;
+
+interface MongoKit<C> extends AsyncDisposable {
+	readonly db: SoleScope<C>;
+	readonly databases: { readonly [N in DbName<C>]: DbScope<CollectionsIn<C, N>> };
+	readonly clients: { readonly [N in DbName<C>]: MongoClient };
+	readonly actor: KitActor<C> | undefined;
+	readonly session: ClientSession | undefined;
+	as(actor: KitActor<C>): MongoKit<C>;
+	withSession(session: ClientSession | undefined): MongoKit<C>;
+	transaction<T>(
+		fn: (kit: MongoKit<C>) => Promise<T>,
+		options?: KitTransactionOptions<C>,
+	): Promise<T>;
+	sync(options?: SyncOptions): Promise<Record<DbName<C>, SyncReport[]>>;
+	close(): Promise<void>;
+}
+```
+
+## Next
+
+- [The actor, sessions and transactions](actor-and-transactions.md).
+- [Syncing](sync.md).