@nxgt/mongo-kit 0.1.4 → 0.2.0

package/README.md

@@ -218,6 +218,40 @@ definition under it; without `export`, every export that is a definition is
 taken. Two files defining the same server collection are refused. It needs
 the Bun runtime, and it is for scripts.
 
+## Errors
+
+`KitError` is what this package refuses: a configuration, a name or a call
+that cannot work. It carries a `code`, and the `database` and `key` it is
+about — never a URI, which may hold a password.
+
+```ts
+import { KitError } from '@nxgt/mongo-kit';
+
+if (error instanceof KitError && error.code === 'CONFIG') {
+	console.error(`mongo: "${error.database}" is misconfigured`, error.message);
+}
+```
+
+| `KitErrorCode` | |
+| --- | --- |
+| `CONFIG` | `defineConfig` refused the configuration |
+| `COLLISION` | a collection is wired under a name the driver's `Db` has |
+| `NO_DATABASE` | `transaction(fn, { on })` named a database this kit does not hold |
+| `SEVERAL_DATABASES` | `kit.db` was read on a kit that holds more than one |
+| `TRANSACTION` | no client named where one is needed, or `{ on }` inside a session |
+| `DERIVED` | `close()` on a kit `as`, `withSession` or a transaction derived |
+| `DISCOVERY` | `discoverCollections` could not make a set of definitions |
+
+It extends **`TypeError`**, not `Error`: each of these is a call or a
+configuration written wrong, and this package threw bare `TypeError`s before
+the class existed, so a `catch` that tests for `TypeError` still matches.
+
+The collections are `@nxgt/mongo`'s, so what a *query* throws is its
+`DataError` and its subclasses, unchanged. MongoDB's own refusal to connect
+reaches the caller from `createKit` as the driver's error. Every code, with
+the call that raises it, is in
+[docs/guide/errors.md](docs/guide/errors.md).
+
 ## What does not compile
 
 Each is a `@ts-expect-error` case in this package's type tests.
@@ -250,7 +284,7 @@ Each is a `@ts-expect-error` case in this package's type tests.
   deployment step: it needs `dbAdmin`, and an index build is not in a
   transaction.
 - **A kit from `as` or `withSession` cannot be closed**, and `close()` on it
-  throws: the clients are the root kit's.
+  throws `KitError` with the code `DERIVED`: the clients are the root kit's.
 - **`discoverCollections` runs under Bun**, has no types, and does not
   survive bundling. It is for scripts run from the repository; a Node script
   calling it gets `Bun is not defined`.
@@ -258,15 +292,33 @@ Each is a `@ts-expect-error` case in this package's type tests.
   uncallable: one call could not stamp both.
 - **`{ 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*. Without it, a kit holding two throws.
+  number of *clients*. Without it, a kit holding two throws `TRANSACTION`.
 - **A transaction body may run twice.** The driver retries it from the start
   on a transient error, so it must hold nothing that MongoDB would not roll
   back.
 - **A transaction 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.
-- **`kit.db` throws on a kit with several databases**, where its type is
-  already `never`: the message names the databases to read instead.
+- **`kit.db` throws `SEVERAL_DATABASES` 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`.
+- [Errors](docs/guide/errors.md) — `KitError`, its codes, and what each one
+  is thrown by.
+- [`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
 

package/dist/config/checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/config/checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAU7E;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAC5B,WAAW,EAAE,MAAM,GACjB,CAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE,CAKrC;AA6BD,6EAA6E;AAC7E,wBAAgB,aAAa,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,GAC5B,CAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE,CA8DrC"}
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/config/checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAU7E;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAC5B,WAAW,EAAE,MAAM,GACjB,CAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE,CAKrC;AAsCD,6EAA6E;AAC7E,wBAAgB,aAAa,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,GAC5B,CAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE,CA6DrC"}

package/dist/config/define-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,OAAO,EAEP,SAAS,EACT,cAAc,EACd,MAAM,SAAS,CAAC;AAuBjB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAC1D,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACpB,SAAS,CAAC,CAAC,CAAC,CAQd"}
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,OAAO,EAEP,SAAS,EACT,cAAc,EACd,MAAM,SAAS,CAAC;AAmCjB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAC1D,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACpB,SAAS,CAAC,CAAC,CAAC,CAQd"}

package/dist/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAiCpC"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAI3D,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAqCpC"}

package/dist/errors/kit-error.d.ts

@@ -0,0 +1,41 @@
+/** What the kit refused, as a string a caller can switch on. */
+export type KitErrorCode = 
+/** The configuration object itself is wrong, and nothing connected. */
+'CONFIG'
+/** A collection is wired under a name that is a member of the driver's `Db`. */
+ | 'COLLISION'
+/** A database was read by a name this kit does not hold. */
+ | 'NO_DATABASE'
+/** `kit.db` was read on a kit that holds more than one database. */
+ | 'SEVERAL_DATABASES'
+/** A transaction that cannot be opened: no client named, or already in one. */
+ | 'TRANSACTION'
+/** `close()` on a kit that `as`, `withSession` or a transaction derived. */
+ | 'DERIVED'
+/** `discoverCollections` could not make a set of definitions from a glob. */
+ | 'DISCOVERY';
+export interface KitErrorOptions {
+    /** The database it is about, when one is named. */
+    database?: string | undefined;
+    /** The config key, the collection key or the path it is about. */
+    key?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * What this package refuses, with a code beside the sentence.
+ *
+ * It extends `TypeError` rather than `Error`, unlike `DataError`,
+ * `RedisError` and `S3Error`: 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 it existed. Extending one keeps
+ * every `catch` that tests for `TypeError` working, and adds a `code` to
+ * switch on instead of matching the message text.
+ */
+export declare class KitError extends TypeError {
+    name: string;
+    readonly code: KitErrorCode;
+    readonly database: string | undefined;
+    readonly key: string | undefined;
+    constructor(code: KitErrorCode, message: string, options?: KitErrorOptions);
+}
+//# sourceMappingURL=kit-error.d.ts.map

package/dist/errors/kit-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit-error.d.ts","sourceRoot":"","sources":["../../src/errors/kit-error.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,MAAM,YAAY;AACvB,uEAAuE;AACrE,QAAQ;AACV,gFAAgF;GAC9E,WAAW;AACb,4DAA4D;GAC1D,aAAa;AACf,oEAAoE;GAClE,mBAAmB;AACrB,+EAA+E;GAC7E,aAAa;AACf,4EAA4E;GAC1E,SAAS;AACX,6EAA6E;GAC3E,WAAW,CAAC;AAEf,MAAM,WAAW,eAAe;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,SAAS;IAC7B,IAAI,SAAc;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAErB,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe;CAM1E"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { defineConfig } from './config/define-config';
 export type { CollectionsIn, CollectionsOf, DatabaseConfig, DbName, KitCollectionOptions, KitConfig, KitConfigInput, NoCollision, ReservedName, Unwired, } from './config/types';
 export { type DiscoverOptions, discoverCollections } from './discover';
+export { KitError, type KitErrorCode, type KitErrorOptions, } from './errors/kit-error';
 export { createKit } from './kit/create-kit';
 export type { DbScope, KitActor, KitOf, KitTransactionOptions, MongoKit, SoleScope, } from './kit/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,MAAM,EACN,oBAAoB,EACpB,SAAS,EACT,cAAc,EACd,WAAW,EACX,YAAY,EACZ,OAAO,GACP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EACX,OAAO,EACP,QAAQ,EACR,KAAK,EACL,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACT,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,MAAM,EACN,oBAAoB,EACpB,SAAS,EACT,cAAc,EACd,WAAW,EACX,YAAY,EACZ,OAAO,GACP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EACN,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,eAAe,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EACX,OAAO,EACP,QAAQ,EACR,KAAK,EACL,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACT,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,14 @@
+// src/errors/kit-error.ts
+class KitError extends TypeError {
+  constructor(code, message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "KitError";
+    this.code = code;
+    this.database = options?.database;
+    this.key = options?.key;
+  }
+}
+
 // src/config/checks.ts
 function isDefinition(value) {
   if (typeof value !== "object" || value === null)
@@ -8,65 +19,67 @@ function isDefinition(value) {
 function definitionsOf(collections) {
   return Object.entries(collections).filter((entry) => isDefinition(entry[1]));
 }
-var refuse = (where, said) => {
-  throw new TypeError(`defineConfig: ${where} ${said}`);
+var refuse = (name, said, key) => {
+  throw new KitError("CONFIG", `defineConfig: database "${name}" ${said}`, {
+    database: name,
+    key
+  });
 };
 var OWNED = ["db", "session", "actor", "autoSync"];
-function checkOwned(where, what, options) {
+function checkOwned(name, what, options, forKey) {
   if (typeof options !== "object" || options === null)
     return;
   for (const key of OWNED) {
     if (key in options) {
-      refuse(where, `has "${key}" in ${what}, which the kit decides: ` + "a database is named by its key, `as` and `withSession` carry the " + "actor and the session, and `autoSync` is the database's");
+      refuse(name, `has "${key}" in ${what}, which the kit decides: ` + "a database is named by its key, `as` and `withSession` carry the " + "actor and the session, and `autoSync` is the database's", forKey);
     }
   }
 }
 function checkDatabase(name, config) {
-  const where = `database "${name}"`;
   if (typeof config !== "object" || config === null) {
-    refuse(where, "is not a configuration object");
+    refuse(name, "is not a configuration object");
   }
   const hasUri = config.uri !== undefined;
   const hasClient = config.client !== undefined;
   if (hasUri === hasClient) {
-    refuse(where, hasUri ? "has both a uri and a client: pass the one it should use" : "has neither a uri nor a client");
+    refuse(name, hasUri ? "has both a uri and a client: pass the one it should use" : "has neither a uri nor a client");
   }
   if (hasUri && (typeof config.uri !== "string" || config.uri === "")) {
-    refuse(where, "has a uri that is not a string");
+    refuse(name, "has a uri that is not a string");
   }
   if (hasClient && typeof config.client?.db !== "function") {
-    refuse(where, "has a client that is not a MongoClient");
+    refuse(name, "has a client that is not a MongoClient");
   }
   if (hasClient && config.clientOptions !== undefined) {
-    refuse(where, "has client options beside a client it did not open: pass them where the client is made");
+    refuse(name, "has client options beside a client it did not open: pass them where the client is made");
   }
   if (config.database !== undefined && config.database === "") {
-    refuse(where, "has an empty database name");
+    refuse(name, "has an empty database name");
   }
   if (typeof config.collections !== "object" || config.collections === null) {
-    refuse(where, "has no collections object");
+    refuse(name, "has no collections object");
   }
   const definitions = definitionsOf(config.collections);
   if (definitions.length === 0) {
-    refuse(where, "has a collections object with no definition in it: pass the module, as in `import * as collections`");
+    refuse(name, "has a collections object with no definition in it: pass the module, as in `import * as collections`");
   }
   const byName = new Map;
   for (const [key, definition] of definitions) {
     const seen = byName.get(definition.name);
     if (seen !== undefined) {
-      refuse(where, `wires "${seen}" and "${key}" to the same collection, "${definition.name}"`);
+      refuse(name, `wires "${seen}" and "${key}" to the same collection, "${definition.name}"`);
     }
     byName.set(definition.name, key);
   }
   const keys = new Set(definitions.map(([key]) => key));
   for (const key of Object.keys(config.optionsFor ?? {})) {
     if (!keys.has(key)) {
-      refuse(where, `has options for "${key}", which it does not wire`);
+      refuse(name, `has options for "${key}", which it does not wire`, key);
     }
   }
-  checkOwned(where, "options", config.options);
+  checkOwned(name, "options", config.options);
   for (const [key, options] of Object.entries(config.optionsFor ?? {})) {
-    checkOwned(where, `the options of "${key}"`, options);
+    checkOwned(name, `the options of "${key}"`, options, key);
   }
   return definitions;
 }
@@ -74,18 +87,18 @@ function checkDatabase(name, config) {
 // src/config/define-config.ts
 function databasesOf(config) {
   if (typeof config !== "object" || config === null) {
-    throw new TypeError("defineConfig: a configuration object is required");
+    throw new KitError("CONFIG", "defineConfig: a configuration object is required");
   }
   if (!("databases" in config)) {
     return { default: config };
   }
   const { databases } = config;
   if (typeof databases !== "object" || databases === null) {
-    throw new TypeError("defineConfig: databases is not an object");
+    throw new KitError("CONFIG", "defineConfig: databases must be an object of databases by name, " + "as `{ databases: { main: … } }`. One database is the " + "configuration itself, and names itself with `database`.");
   }
   const names = Object.keys(databases);
   if (names.length === 0) {
-    throw new TypeError("defineConfig: databases names none");
+    throw new KitError("CONFIG", "defineConfig: databases names none. Give it at least one, " + "as `{ databases: { main: … } }`.");
   }
   return databases;
 }
@@ -102,7 +115,7 @@ function defineConfig(config) {
 async function discoverCollections(options) {
   const { glob, cwd = process.cwd(), export: name } = options;
   if (typeof glob !== "string" || glob === "") {
-    throw new TypeError("discoverCollections: a glob is required");
+    throw new KitError("DISCOVERY", "discoverCollections: a glob is required");
   }
   const paths = await Array.fromAsync(new Bun.Glob(glob).scan({ cwd }));
   const found = [];
@@ -111,12 +124,12 @@ async function discoverCollections(options) {
     const module = await import(`${cwd}/${path}`);
     const definitions = name === undefined ? definitionsOf(module) : isDefinition(module[name]) ? [[name, module[name]]] : [];
     if (name !== undefined && definitions.length === 0) {
-      throw new TypeError(`discoverCollections: ${path} exports no definition named "${name}"`);
+      throw new KitError("DISCOVERY", `discoverCollections: ${path} exports no definition named "${name}"`, { key: path });
     }
     for (const [, definition] of definitions) {
       const seen = byName.get(definition.name);
       if (seen !== undefined && seen !== path) {
-        throw new TypeError(`discoverCollections: ${seen} and ${path} both define the collection "${definition.name}"`);
+        throw new KitError("DISCOVERY", `discoverCollections: ${seen} and ${path} both define the collection "${definition.name}"`, { key: path });
       }
       byName.set(definition.name, path);
       found.push(definition);
@@ -140,7 +153,7 @@ function derived(ctx, change) {
 function databaseOf(ctx, name) {
   const found = ctx.databases.find((database) => database.name === name);
   if (!found) {
-    throw new TypeError(`This kit has no database "${name}": it has ${ctx.databases.map((database) => `"${database.name}"`).join(", ")}.`);
+    throw new KitError("NO_DATABASE", `This kit has no database "${name}": it has ${ctx.databases.map((database) => `"${database.name}"`).join(", ")}.`, { database: name });
   }
   return found;
 }
@@ -208,13 +221,13 @@ function clientFor(ctx, on) {
   const [only] = clients;
   if (clients.size === 1 && only)
     return only;
-  throw new TypeError("transaction: this kit holds more than one client, and a transaction " + "lives on one. Name the database it runs on, as `{ on: 'main' }`.");
+  throw new KitError("TRANSACTION", "transaction: this kit holds more than one client, and a transaction " + "lives on one. Name the database it runs on, as `{ on: 'main' }`.");
 }
 function hostFor(ctx, on) {
   if (!ctx.session)
     return clientFor(ctx, on);
   if (on !== undefined) {
-    throw new TypeError("transaction: this kit is already in a session, which this call " + "joins, so `on` has no client left to choose.");
+    throw new KitError("TRANSACTION", "transaction: this kit is already in a session, which this call " + "joins, so `on` has no client left to choose.");
   }
   return ctx.session;
 }
@@ -228,7 +241,7 @@ async function transact(ctx, build, fn, options) {
 // src/kit/derive.ts
 async function closeKit(ctx) {
   if (!ctx.root) {
-    throw new TypeError("close: this kit came from `as`, `withSession` or a transaction. " + "Close the kit `createKit` returned — the clients are shared.");
+    throw new KitError("DERIVED", "close: this kit came from `as`, `withSession` or a transaction. " + "Close the kit `createKit` returned — the clients are shared.");
   }
   for (const database of ctx.databases) {
     await database.connection?.close();
@@ -260,7 +273,7 @@ function kitOf(ctx) {
     get db() {
       const [only] = ctx.databases;
       if (ctx.databases.length !== 1 || !only) {
-        throw new TypeError("kit.db: this kit has several databases. Read the one you mean, " + `as \`kit.databases.${ctx.databases[0]?.name ?? "main"}\`.`);
+        throw new KitError("SEVERAL_DATABASES", "kit.db: this kit has several databases. Read the one you mean, " + `as \`kit.databases.${ctx.databases[0]?.name ?? "main"}\`.`);
       }
       return scopeFor(only.name);
     },
@@ -312,7 +325,7 @@ async function open(config) {
 function checkCollisions(name, db, keys) {
   for (const key of keys) {
     if (key in db) {
-      throw new TypeError(`createKit: database "${name}" wires a collection under "${key}", ` + "which is a member of the driver's Db: it would be unreachable. " + "Export that definition under another name.");
+      throw new KitError("COLLISION", `createKit: database "${name}" wires a collection under "${key}", ` + "which is a member of the driver's Db: it would be unreachable. " + "Export that definition under another name.", { database: name, key });
     }
   }
 }
@@ -350,10 +363,11 @@ async function createKit(config) {
   return kitOf(ctx);
 }
 export {
+  KitError,
   createKit,
   defineConfig,
   discoverCollections
 };
 
-//# debugId=00B9BBA5C20F9E8D64756E2164756E21
+//# debugId=D45C9A203331820F64756E2164756E21
 //# sourceMappingURL=index.js.map