@nxgt/mongo-kit 0.1.4 → 0.2.0

package/docs/guide/sync.md

@@ -0,0 +1,108 @@
+# Syncing
+
+`kit.sync()` brings the server in line with the definitions the kit wires:
+the collections, their `$jsonSchema` validators, their collection options and
+their indexes, database by database.
+
+```ts
+import { createKit, defineConfig } from '@nxgt/mongo-kit';
+import * as collections from './models'; // every `defineCollection` of the app
+
+await using kit = await createKit(
+	defineConfig({ uri: process.env.MONGO_URI!, collections }),
+);
+
+const reports = await kit.sync();
+// { default: [ { name: 'posts', created: true, … }, { name: 'users', … } ] }
+```
+
+It reports one `SyncReport[]` per database, under the name the config gave it
+— `default` when it named none. Run it twice and the second run sends
+nothing.
+
+## Options
+
+They are `@nxgt/mongo`'s `SyncOptions`, passed through as they are.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `dryRun` | `boolean` | `false` | Compare and report, send nothing. An option MongoDB cannot change is reported instead of thrown, so one run lists everything that is wrong |
+| `dropUnknownIndexes` | `boolean` | `false` | Drop the indexes the server has and no definition names. `_id_` is never dropped |
+| `session` | `ClientSession` | — | A session for the reads. Never one in a transaction: MongoDB allows neither `collMod` nor an index build inside one |
+
+```ts
+const reports = await kit.sync({ dryRun: true });
+reports.default[0]?.created;          // what it would create
+reports.default[0]?.indexes.created;  // the indexes it would build
+```
+
+The first database that throws stops the rest, which is what `dryRun` is
+for: it reports everything at once.
+
+## It is a deployment step
+
+`collMod` needs the `dbAdmin` role, and an index build runs outside any
+transaction — neither belongs in a request. A script of its own, run before
+the new version serves traffic:
+
+```ts
+// src/sync.ts — `bun run src/sync.ts [--dry-run]`
+import { createKit } from '@nxgt/mongo-kit';
+import { config } from './db';
+
+await using kit = await createKit(config);
+
+const reports = await kit.sync({ dryRun: process.argv.includes('--dry-run') });
+for (const [database, collections] of Object.entries(reports)) {
+	for (const report of collections) {
+		console.log(
+			`${database}.${report.name}: ${report.created ? 'created' : 'in place'}, ` +
+				`${report.indexes.created.length} index(es) created`,
+		);
+	}
+}
+```
+
+For tests and local development, `autoSync: true` in the
+[configuration](configuration.md) syncs each collection before its first
+operation instead, and no script is needed.
+
+## Why not `syncAll`
+
+`@nxgt/mongo`'s `syncAll` works from a global registry, which knows no
+database: it cannot tell the collections of one from those of another.
+`kit.sync()` syncs exactly what the kit wires, on the database each one is
+wired to. For a repository that has no kit — a migration script, a one-off —
+[`discoverCollections`](discover-collections.md) with `syncCollections` is
+the other way round.
+
+## Signatures
+
+```ts
+interface MongoKit<C> {
+	sync(options?: SyncOptions): Promise<Record<DbName<C>, SyncReport[]>>;
+}
+
+// both from @nxgt/mongo
+interface SyncOptions {
+	dryRun?: boolean;
+	dropUnknownIndexes?: boolean;
+	session?: ClientSession;
+}
+
+interface SyncReport {
+	name: string;
+	created: boolean;
+	validator: 'unchanged' | 'created' | 'updated' | 'removed';
+	options: { changed: string[]; immutable: OptionMismatch[] };
+	indexes: { created: string[]; recreated: string[]; dropped: string[]; unchanged: string[] };
+	dryRun: boolean;
+}
+```
+
+## Next
+
+- [`discoverCollections`](discover-collections.md) — syncing from a glob,
+  without a kit.
+- [Configuration](configuration.md) — `autoSync`, and the options a
+  collection is built with.

package/docs/roadmap.md

@@ -0,0 +1,68 @@
+# Roadmap
+
+Where `@nxgt/mongo-kit` is going. A direction, not a commitment: the version
+an item shipped in is the only number on this page.
+
+## Now
+
+- **`ping()`** — one call that says whether the databases the kit wires
+  answer, and how long they took, for a health endpoint that does not reach
+  for the driver itself.
+
+## Next
+
+- **Files beside the collections** — a bucket declared in the configuration
+  and reached off the kit the way a collection is today, in the kit's session
+  and under its actor, so a file write joins a transaction with the documents
+  around it.
+
+## Later
+
+_Nothing queued._
+
+## Not planned
+
+- **A typed `discoverCollections`** — it reads the file system under Bun, has
+  no types and does not survive bundling. It is for scripts; an application
+  wires its collections in the configuration, as `import * as collections`,
+  where they stay typed.
+- **Closing a client the configuration handed over** — the kit gives back only
+  the clients it opened, `await using` included. A client you opened is closed
+  where it was opened.
+- **A transaction across two clients** — MongoDB refuses a session a client
+  does not own, so a transaction reaches one client's databases and `{ on }`
+  names which. Two databases on one URI share a client and need no `{ on }`.
+- **`autoSync` as a production setting** — it is for tests and development.
+  In production `sync()` is a deployment step: it needs `dbAdmin`, and an
+  index build does not run in a transaction.
+- **Wiring a collection under a name the driver's `Db` already answers to** —
+  refused by the types where the configuration is written, and again by
+  `createKit` against the object itself, so `kit.db.command(…)` is always the
+  driver's.
+
+## Shipped
+
+- **Every refusal is a `KitError`, with a code** — `CONFIG`, `COLLISION`,
+  `NO_DATABASE`, `SEVERAL_DATABASES`, `TRANSACTION`, `DERIVED` or `DISCOVERY`,
+  beside the database and the key it is about, so a caller switches on the
+  code instead of matching the sentence; it extends `TypeError`, which these
+  were before, so a `catch` written against the old ones still catches them —
+  0.2.0.
+- **Documentation that travels with the package** — a guide page for the
+  configuration, the `db` scope, actor and transactions, and `sync()`, a
+  troubleshooting page whose headings are the exact error text, and this
+  roadmap, installed in `docs/` rather than left on GitHub — 0.1.5.
+- **`@nxgt/mongo` 0.15.0** — a deduplicated file write two callers cannot
+  both win — 0.1.4.
+- **`@nxgt/mongo` 0.14.0** — files under its `./gridfs` subpath — 0.1.3.
+- **`@nxgt/mongo` 0.13.0** — `upsert` in one round trip — 0.1.2.
+- **`@nxgt/mongo` 0.12.0** — strings from outside read from the schema —
+  0.1.1.
+- **First release** — `defineConfig` checking a configuration of one or
+  several databases and freezing it, and `createKit` giving a `db` that is the
+  driver's own with every collection typed on it, plus `as(actor)`,
+  `withSession`, `transaction`, `sync()` and `close()`; `discoverCollections`
+  for scripts — 0.1.0.
+
+Everything released is in [`CHANGELOG.md`](https://github.com/softistx/nxgt-data/blob/develop/packages/mongo-kit/CHANGELOG.md) — it is not in
+the published package, only in the repository.