@nxgt/mongo-kit 0.1.3 → 0.1.5

package/docs/guide/discover-collections.md

@@ -0,0 +1,83 @@
+# `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 `TypeError`:
+
+- `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/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,62 @@
+# 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
+
+- **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.