@nxgt/mongo-kit 0.1.4 → 0.2.0

package/docs/guide/configuration.md

@@ -0,0 +1,230 @@
+# 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 [`KitError`](errors.md) with `code: 'CONFIG'`, thrown from
+`defineConfig`, before anything connects. The message names the database it
+is about, and so does `error.database`:
+
+```ts
+defineConfig({ collections });
+// KitError: 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,174 @@
+# 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 [`KitError`](errors.md) with
+`code: 'SEVERAL_DATABASES'`, 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).

package/docs/guide/discover-collections.md

@@ -0,0 +1,85 @@
+# `discoverCollections`
+
+Reads the collection definitions a glob matches, for a **script** that has no
+kit to work from — a sync, a migration, a one-off run from the repository.
+
+```ts
+import { connectMongo, syncCollections } from '@nxgt/mongo';
+import { discoverCollections } from '@nxgt/mongo-kit';
+
+const mongo = await connectMongo(process.env.MONGO_URI!);
+const definitions = await discoverCollections({ glob: 'src/**/*.model.ts' });
+await syncCollections(mongo.db, definitions);
+await mongo.close();
+```
+
+It gives `@nxgt/mongo`'s `AnyCollectionDefinition[]`, sorted by path and with
+each definition appearing once.
+
+## It is for scripts, and for nothing else
+
+- **It produces no types.** A glob is read at run time, so the compiler sees
+  nothing: everything it returns is an `AnyCollectionDefinition`.
+- **It does not survive bundling.** A bundler cannot follow a glob, so the
+  matched files are not in the bundle and nothing is found.
+- **It needs the Bun runtime**: the glob is `Bun.Glob`. A Node script gets
+  `ReferenceError: Bun is not defined`.
+- **It imports every file it matches**, so their top level runs — and a model
+  file's top level registers its definition.
+
+An application wires its collections with
+`import * as collections from './models'`, which a bundler follows and the
+compiler sees. See [Configuration](configuration.md).
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `glob` | `string` | — | Relative to `cwd`: `'src/models/*.model.ts'`. Required |
+| `cwd` | `string` | `process.cwd()` | Where the glob starts |
+| `export` | `string` | — | Read one export by name in each file. Without it, every export that is a definition is taken |
+
+```ts
+// every definition each file exports
+await discoverCollections({ glob: 'test/models/*.model.ts', cwd });
+
+// only the export called `definition`, in each matched file
+await discoverCollections({
+	glob: 'test/models/*.model.ts',
+	cwd,
+	export: 'definition',
+});
+```
+
+A glob that matches nothing gives `[]`.
+
+## What it throws
+
+All three are a [`KitError`](errors.md) with `code: 'DISCOVERY'`. The two
+that are about a file carry its path on `key`; the missing-glob one has no
+path yet, so its `key` is `undefined`:
+
+- `discoverCollections: a glob is required` — `glob` missing or empty.
+- `discoverCollections: <path> exports no definition named "<name>"` — with
+  `export`, a matched file that has no definition under that name. Without
+  `export`, such a file simply contributes nothing.
+- `discoverCollections: <a> and <b> both define the collection "<name>"` —
+  two files describing one server collection.
+
+## Signatures
+
+```ts
+interface DiscoverOptions {
+	glob: string;
+	cwd?: string;
+	export?: string;
+}
+
+function discoverCollections(
+	options: DiscoverOptions,
+): Promise<AnyCollectionDefinition[]>;
+```
+
+## Next
+
+- [Syncing](sync.md) — the same step for an application that has a kit.

package/docs/guide/errors.md

@@ -0,0 +1,198 @@
+# Errors
+
+`KitError` is what this package refuses — a configuration, a name or a call
+that cannot work — with a `code` beside the sentence, so nothing has to match
+the message text.
+
+```ts
+import { defineConfig, KitError } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+try {
+	defineConfig({ uri: process.env.MONGO_URI!, collections });
+} catch (error) {
+	if (error instanceof KitError) {
+		error.code;      // 'CONFIG'
+		error.database;  // 'default' — the database it is about, when one is named
+		error.key;       // the config key, collection key or path, when one is
+	}
+	throw error;
+}
+```
+
+Errors from the collections themselves — a duplicate key, a failed
+validation, a missing document — are `@nxgt/mongo`'s `DataError` and its
+subclasses, unchanged: `kit.db.users` *is* one of its collections. `KitError`
+is only about the wiring.
+
+## The codes
+
+| `code` | Thrown by | When |
+| --- | --- | --- |
+| `CONFIG` | `defineConfig` | the configuration cannot work: no `uri` and no `client`, both at once, `clientOptions` beside a `client`, a `collections` with no definition in it, two keys on one server collection, `optionsFor` under a key nothing is wired under, or one of the four options the kit decides |
+| `COLLISION` | `createKit` | a collection is wired under a name the driver's `Db` already has — `command`, `watch`, `collection`… — so it would be unreachable |
+| `NO_DATABASE` | `transaction(fn, { on: '<name>' })` | this kit holds no database under that name; the message lists the ones it has. Reading `kit.databases.<name>` does **not** throw — an unknown key is plain `undefined` |
+| `SEVERAL_DATABASES` | reading `kit.db` | the kit holds more than one database, so there is no "the" database to give |
+| `TRANSACTION` | `transaction` | the kit holds several clients and the call named none, or it is already in a session and still passed `{ on }` |
+| `DERIVED` | `close` | the kit came from `as`, `withSession` or a transaction: the clients are the root kit's |
+| `DISCOVERY` | `discoverCollections` | the glob is missing, a matched file has no definition under the `export` asked for, or two files define the same server collection |
+
+`code` is the field to switch on: it survives a build that ends up with two
+copies of the package, which `instanceof` does not.
+
+## What it carries
+
+```ts
+class KitError extends TypeError {
+	readonly code: KitErrorCode;
+	/** The database it is about, when one is named. */
+	readonly database: string | undefined;
+	/** The config key, the collection key or the path it is about. */
+	readonly key: string | undefined;
+
+	constructor(code: KitErrorCode, message: string, options?: KitErrorOptions);
+}
+
+type KitErrorCode =
+	| 'CONFIG'
+	| 'COLLISION'
+	| 'NO_DATABASE'
+	| 'SEVERAL_DATABASES'
+	| 'TRANSACTION'
+	| 'DERIVED'
+	| 'DISCOVERY';
+
+interface KitErrorOptions {
+	database?: string | undefined;
+	key?: string | undefined;
+	cause?: unknown;
+}
+```
+
+`database` is the key the database is named by in the configuration —
+`default` for a lone one — and `key` is the collection key, the config key or
+the file path the refusal is about. Neither is ever a URI: a connection
+string holds the password, and this package prints none.
+
+```ts
+import { createKit, KitError } from '@nxgt/mongo-kit';
+
+try {
+	await createKit(config);
+} catch (error) {
+	if (error instanceof KitError && error.code === 'COLLISION') {
+		error.database; // 'main'
+		error.key;      // 'command' — the export to rename
+	}
+	throw error;
+}
+```
+
+## It is a `TypeError`
+
+`KitError` extends **`TypeError`**, not `Error`, unlike `@nxgt/mongo`'s
+`DataError` or `@nxgt/redis`'s `RedisError`. Every one of these is a call or
+a configuration written wrong, which is what `TypeError` means — and this
+package threw bare `TypeError`s before the class existed, so nothing that
+already catches one stopped matching:
+
+```ts
+try {
+	defineConfig({ databases: {} } as never);
+} catch (error) {
+	error instanceof KitError;   // true
+	error instanceof TypeError;  // true — still what it always was
+}
+```
+
+What is new is the `code`, which a `catch` can switch on instead of reading
+the sentence.
+
+## Where each one comes from
+
+Nothing below reaches a request handler in a working application: they are
+start-up and wiring failures, and `defineConfig` is deliberately the earliest
+of them.
+
+```ts
+import { createKit, defineConfig, KitError } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+// CONFIG — before anything connects.
+defineConfig({ collections } as never);
+// KitError: defineConfig: database "default" has neither a uri nor a client
+
+// COLLISION — at createKit, against the driver's own Db.
+await createKit(
+	defineConfig({ uri: process.env.MONGO_URI!, collections: { command: users } as never }),
+);
+// KitError: createKit: database "default" wires a collection under "command", …
+
+// NO_DATABASE — a transaction named on a database this kit does not hold.
+// The types refuse the name, so this is the call that came through an `any`,
+// or from JavaScript. Reading `kit.databases.nowhere` gives `undefined`
+// instead: only `on` looks a name up.
+await kit.transaction(async () => {}, { on: 'nowhere' as never });
+// KitError: This kit has no database "nowhere": it has "main", "analytics".
+
+// SEVERAL_DATABASES — `kit.db` with more than one. Its type is `never`.
+kit.db;
+// KitError: kit.db: this kit has several databases. Read the one you mean, as `kit.databases.main`.
+
+// TRANSACTION — several clients, and no `{ on }`.
+await kit.transaction(async (tx) => { /* … */ });
+// KitError: transaction: this kit holds more than one client, …
+
+// DERIVED — closing a kit that `as` derived.
+await kit.as(userId).close();
+// KitError: close: this kit came from `as`, `withSession` or a transaction. …
+```
+
+A name no database has, and `{ on: 'nowhere' }` with it, do not compile
+either: the types refuse them where they are written. The run-time refusal is
+what catches the call that arrived through an `any`, or from JavaScript — and
+`kit.db` on a kit with several databases, whose type is already `never`.
+
+## A start-up that reports instead of crashing
+
+The useful thing to do with a `KitError` is to say which database and which
+key, because that is what the fix needs:
+
+```ts
+import { createKit, defineConfig, KitError } from '@nxgt/mongo-kit';
+import * as collections from './models';
+
+export async function startDatabase() {
+	try {
+		return await createKit(
+			defineConfig({ uri: process.env.MONGO_URI!, collections }),
+		);
+	} catch (error) {
+		if (error instanceof KitError) {
+			console.error(
+				`mongo: ${error.code}` +
+					(error.database ? ` on "${error.database}"` : '') +
+					(error.key ? ` at "${error.key}"` : ''),
+				error.message,
+			);
+			process.exit(1);
+		}
+		throw error; // a driver error: a host that does not answer, a bad password
+	}
+}
+```
+
+MongoDB's own refusal to connect is **not** a `KitError`: a host that does not
+answer, a wrong password, a replica set with no primary are the driver's
+errors, and they reach the caller unchanged from `createKit`. A database that
+fails to open gives back every connection opened before it.
+
+## Next
+
+- [Configuration](configuration.md) — what `defineConfig` checks, key by key.
+- [The `db` scope](db-scope.md) — `kit.db`, `kit.databases` and the names
+  that are refused.
+- [The actor, sessions and transactions](actor-and-transactions.md) — `{ on }`,
+  and the kits that cannot be closed.
+- [Troubleshooting](../troubleshooting.md) — the same errors, indexed by the
+  message you are staring at.