@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/codegen/cli.mjs

@@ -1,8 +1,8 @@
-import { runCodegen } from '../chunk-VOSJBZ6Q.mjs';
-import '../chunk-SBL6GN43.mjs';
-import '../chunk-TUD5CJ76.mjs';
+import { runCodegen } from '../chunk-2ES3DT4A.mjs';
+import '../chunk-ZYWI45EN.mjs';
+import '../chunk-KB4OLJAD.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-PBRXXISQ.mjs';
+import '../chunk-KINDFBQP.mjs';
 
 // src/codegen/cli.ts
 runCodegen(process.argv.slice(2)).catch((err) => {

package/dist/codegen/index.d.ts

@@ -1,100 +1,105 @@
-import { a as OperationRegistry } from '../operation-registry-oiPuSYI6.js';
-import '../query-types-p1liOP-b.js';
+import { a as OperationRegistry, D as DatabaseOperations } from '../operation-registry-CGhNT-Sn.js';
+import '../query-types-5B02ixH0.js';
 
 /**
- * Version of the manifest format the generator writes.
+ * The version of the manifest format that the generator writes.
  *
  * @public
  */
 declare const OPERATION_MANIFEST_VERSION = 1;
 /**
- * The arguments and columns of one registered operation, as code generation reads them.
+ * Describes the arguments and result columns of one registered operation for code generation.
  *
  * @public
  */
 interface OperationShape {
     /**
-     * Argument names the caller supplies.
+     * The names of the arguments that the caller supplies.
      */
     args: string[];
     /**
-     * Argument names the server fills from the authenticated identity.
+     * The names of the arguments that the server sets from the authenticated identity.
      */
     identityArgs: string[];
     /**
-     * Columns every row of a read carries, or null when the generator cannot tell.
+     * The column names in every row of a read, or `null` for a write and for a read whose columns the generator cannot derive.
      */
     columns: string[] | null;
 }
 /**
- * The reads and writes one database exposes by name.
+ * Describes the named reads and writes that the registry holds for one database.
  *
  * @public
  */
 interface DatabaseManifest {
     /**
-     * Registered reads, keyed by operation name.
+     * The registered reads, keyed by operation name.
      */
     reads: Record<string, OperationShape>;
     /**
-     * Registered writes, keyed by operation name.
+     * The registered writes, keyed by operation name.
      */
     writes: Record<string, OperationShape>;
 }
 /**
- * Every database's registered operations, in the form code generation reads.
+ * Describes every database's registered operations for code generation.
  *
  * @public
  */
 interface OperationManifest {
     /**
-     * Version of the manifest format.
+     * The version of the manifest format.
      */
     version: number;
     /**
-     * Digest of the registry, which a client compares against the server's.
+     * The registry digest, which a client can compare with the digest that the server announces.
      */
     digest: string | undefined;
     /**
-     * One manifest per database, keyed by database identifier.
+     * One manifest for each database, keyed by database ID.
      */
     databases: Record<string, DatabaseManifest>;
+    /**
+     * The operations that callers may invoke on every database, present when {@link buildOperationManifest} receives a shared set.
+     */
+    shared?: DatabaseManifest;
 }
 /**
- * Reads a registry and describes each operation's arguments and columns.
+ * Returns a manifest that describes the arguments and result columns of every operation in a registry.
  *
- * @param registry - The registered operations to describe.
- * @returns The manifest code generation renders types from.
+ * @param registry - The registered operations to describe, keyed by database identifier.
+ * @param shared - The operations that callers may invoke on every database, which you pass to the server as `sharedOperations`.
+ * @returns The manifest from which code generation renders types.
  *
  * @public
  */
-declare function buildOperationManifest<I>(registry: OperationRegistry<I>): OperationManifest;
+declare function buildOperationManifest<I>(registry: OperationRegistry<I>, shared?: DatabaseOperations<I>): OperationManifest;
 /**
- * Reads the column names a SELECT statement produces.
+ * Returns the column names that a `SELECT` statement produces.
  *
  * @param sql - The statement to inspect.
- * @returns The column names, or null when the statement's columns cannot be read from its text.
+ * @returns The column names, or `null` when the parser cannot derive every column name from the statement's text.
  *
  * @public
  */
 declare function selectColumns(sql: string): string[] | null;
 
 /**
- * How the generated TypeScript is written.
+ * Settings for the TypeScript source that {@link renderOperationTypes} returns.
  *
  * @public
  */
 interface RenderOptions {
     /**
-     * Package the generated file imports its types from. Default: `@delali/sirannon-db`.
+     * The package that the generated file imports its types from, which defaults to `@delali/sirannon-db`.
      */
     packageName?: string;
 }
 /**
- * Renders typed references for every operation in a manifest.
+ * Returns TypeScript source that declares a typed reference for every operation in a manifest.
  *
  * @param manifest - The operations to render.
- * @param options - The package the generated file imports from.
+ * @param options - The package that the generated file imports its types from.
  * @returns The TypeScript source to write.
  *
  * @public
@@ -102,16 +107,18 @@ interface RenderOptions {
 declare function renderOperationTypes(manifest: OperationManifest, options?: RenderOptions): string;
 
 /**
- * Usage text the code generator prints when its arguments do not parse.
+ * The code generator appends this usage text to its error message when it cannot parse the arguments.
  *
  * @public
  */
-declare const CODEGEN_USAGE = "sirannon-codegen --registry <module> --out <file> [--manifest <file>] [--export <name>] [--package <name>]\n\nReads the operation registry a server is built from and writes the typed\nreferences a client calls it through. The registry module is imported, so run\nit under a loader that reads your source format when it is not JavaScript.";
+declare const CODEGEN_USAGE = "sirannon-codegen --registry <module> --out <file> [--manifest <file>] [--export <name>] [--shared-export <name>] [--package <name>]\n\nReads the operations that you register with a server and writes the typed\nreferences through which a client calls them. The generator takes the\nper-database registry from the 'operations' export, or from the default\nexport, and the operations for every database from the 'sharedOperations'\nexport. The generator imports the registry module, so run it under a loader\nthat reads your source format when that format is not JavaScript.";
 /**
- * Runs the code generator: it loads a registry module, builds the manifest, and writes the typed references.
+ * Writes typed operation references for the registry in the `--registry` module to the `--out` file.
+ *
+ * When you pass `--manifest`, the generator also writes the operation manifest to that file as JSON.
  *
- * @param argv - Command-line arguments, without the executable and script names.
- * @throws When an argument is missing or the registry module cannot be loaded.
+ * @param argv - The command-line arguments that follow the executable and script names.
+ * @throws An `Error` when an argument is missing or unrecognised, when Node cannot import the registry module, when the module exports neither an operation registry nor shared operations, or when the module has no export of the name that `--export` or `--shared-export` gives.
  *
  * @public
  */

package/dist/codegen/index.mjs

@@ -1,5 +1,5 @@
-export { CODEGEN_USAGE, OPERATION_MANIFEST_VERSION, buildOperationManifest, renderOperationTypes, runCodegen, selectColumns } from '../chunk-VOSJBZ6Q.mjs';
-import '../chunk-SBL6GN43.mjs';
-import '../chunk-TUD5CJ76.mjs';
+export { CODEGEN_USAGE, OPERATION_MANIFEST_VERSION, buildOperationManifest, renderOperationTypes, runCodegen, selectColumns } from '../chunk-2ES3DT4A.mjs';
+import '../chunk-ZYWI45EN.mjs';
+import '../chunk-KB4OLJAD.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-PBRXXISQ.mjs';
+import '../chunk-KINDFBQP.mjs';

package/dist/core/index.d.ts

@@ -1,21 +1,21 @@
-export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-B7oszQ2n.js';
-import { I as SQLiteConnection, U as SynchronousLevel, S as SQLiteDriver, D as DatabaseOptions, V as LifecycleConfig, M as Migration, W as MigrationResult, X as RollbackResult } from '../types-DPSmjU54.js';
-export { A as AfterQueryHook, Y as AfterQueryHookContext, Z as AppliedMigrationEntry, g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, m as BackupCycleError, n as BackupCycleOptions, o as BackupCycleStatus, B as BackupDestination, p as BackupFileReport, q as BackupGroupMembership, r as BackupGroupSource, s as BackupLogPosition, t as BackupNodePreference, u as BackupPiece, v as BackupProgress, f as BackupRunReport, O as BackupScheduleOptions, w as BackupSkip, x as BackupSkipReason, y as BackupToDestinationOptions, z as BackupVerifyResult, _ as BatchSummary, c as BeforeConnectHook, b as BeforeQueryHook, $ as BeforeSnapshotHook, a0 as BeforeSubscribeHook, a1 as CDCMetrics, a2 as ClusterReadEndpointInfo, H as ClusterStatusInfo, a3 as ConnectionHookContext, a4 as ConnectionMetrics, C as DEFAULT_CHAIN_NAME, e as DatabaseCloseHook, a5 as DatabaseCopyRequest, a6 as DatabaseCopyStep, d as DatabaseOpenHook, P as DriverCapabilities, a7 as DriverWorkerEntry, a8 as HookConfig, a9 as MIGRATION_NAME_RE, aa as MetricsConfig, ab as MigrationBaseline, ac as MigrationSource, ad as NODE_HEALTH_REASONS, ae as NODE_HEALTH_STATES, N as NodeHealth, af as NodeHealthReason, ag as NodeHealthState, ah as OpenOptions, ai as QueryHookContext, aj as QueryMetrics, ak as RunResult, al as SQLiteStatement, a as SirannonOptions, T as Transaction, am as WriterWorkerOptions, F as readBackupChains } from '../types-DPSmjU54.js';
-import { B as BulkLoadDurability, a as BulkLoadResult, R as RequestContext } from '../server-options-Bj5iJnjx.js';
-export { A as AppliedMigrationRow, b as AuthenticateHook, c as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, f as ReplicationStatusInfo, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-Bj5iJnjx.js';
-export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-CjRFuZdB.js';
-import { D as Database } from '../database-BLQvqjsw.js';
-export { C as ConnectionPool, b as ConnectionPoolOptions, c as DatabaseBackups, d as DatabaseLifecycle, a as HookDispose, e as HookEvent, f as HookEventContextMap, g as HookHandler, H as HookRegistry, M as MetricsCollector, S as SnapshotHookContext, h as SubscribeHookContext, i as execute, j as executeBatch, q as query, k as queryOne } from '../database-BLQvqjsw.js';
-export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, d as RequestDeniedError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-Dei4GdBb.js';
-export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-DTO4CYhW.js';
-import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
-export { S as Sirannon } from '../sirannon-BPxC5tC2.js';
-export { C as ChangeEvent, b as ChangeOperation, E as ExecuteResult, P as Params, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, S as Subscription, c as SubscriptionBuilder, d as SubscriptionOptions, W as WriteConcern, e as WriteConcernLevel } from '../query-types-p1liOP-b.js';
-export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-oiPuSYI6.js';
-import '../types-CjhxcjhA.js';
+export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-DcLhxoa1.js';
+import { I as SQLiteConnection, U as SynchronousLevel, S as SQLiteDriver, D as DatabaseOptions, V as LifecycleConfig, M as Migration, W as MigrationResult, X as RollbackResult } from '../types-Dc8oWlxj.js';
+export { A as AfterQueryHook, Y as AfterQueryHookContext, Z as AppliedMigrationEntry, g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, m as BackupCycleError, n as BackupCycleOptions, o as BackupCycleStatus, B as BackupDestination, p as BackupFileReport, q as BackupGroupMembership, r as BackupGroupSource, s as BackupLogPosition, t as BackupNodePreference, u as BackupPiece, v as BackupProgress, f as BackupRunReport, O as BackupScheduleOptions, w as BackupSkip, x as BackupSkipReason, y as BackupToDestinationOptions, z as BackupVerifyResult, _ as BatchSummary, c as BeforeConnectHook, $ as BeforePushHook, b as BeforeQueryHook, a0 as BeforeSnapshotHook, a1 as BeforeSubscribeHook, a2 as CDCMetrics, a3 as ClusterReadEndpointInfo, H as ClusterStatusInfo, a4 as ConnectionHookContext, a5 as ConnectionMetrics, C as DEFAULT_CHAIN_NAME, e as DatabaseCloseHook, a6 as DatabaseCopyRequest, a7 as DatabaseCopyStep, d as DatabaseOpenHook, P as DriverCapabilities, a8 as DriverWorkerEntry, a9 as HookConfig, aa as MIGRATION_NAME_RE, ab as MetricsConfig, ac as MigrationBaseline, ad as MigrationSource, ae as NODE_HEALTH_REASONS, af as NODE_HEALTH_STATES, N as NodeHealth, ag as NodeHealthReason, ah as NodeHealthState, ai as OpenOptions, aj as QueryHookContext, ak as QueryMetrics, al as RunResult, am as SQLiteStatement, a as SirannonOptions, T as Transaction, an as WriterWorkerOptions, F as readBackupChains } from '../types-Dc8oWlxj.js';
+import { B as BulkLoadDurability, a as BulkLoadResult, R as RequestContext } from '../server-options-aYtCkefX.js';
+export { A as AppliedMigrationRow, b as AuthenticateHook, c as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, f as ReplicationStatusInfo, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-aYtCkefX.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DqCdeEyx.js';
+import { D as Database } from '../database-CGDsXW1K.js';
+export { C as ConnectionPool, b as ConnectionPoolOptions, c as DatabaseBackups, d as DatabaseLifecycle, a as HookDispose, e as HookEvent, f as HookEventContextMap, g as HookHandler, H as HookRegistry, M as MetricsCollector, P as PushHookContext, S as SnapshotHookContext, h as SubscribeHookContext, i as execute, j as executeBatch, q as query, k as queryOne } from '../database-CGDsXW1K.js';
+export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, d as RequestDeniedError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-CJUkQ-KL.js';
+export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-CEJG0eFS.js';
+import { B as BaselineFileOption } from '../baseline-Co3iIsN_.js';
+export { S as Sirannon } from '../sirannon-J3EgPVD7.js';
+export { C as ChangeEvent, b as ChangeOperation, E as ExecuteResult, P as Params, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, S as Subscription, c as SubscriptionBuilder, d as SubscriptionOptions, W as WriteConcern, e as WriteConcernLevel } from '../query-types-5B02ixH0.js';
+export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-CGhNT-Sn.js';
+import '../types-DqODKeOq.js';
 
 /**
- * Reports whether a value is one of the durability levels a bulk load accepts.
+ * Returns true when the value is `'off'` or `'normal'`, the two durability levels that a bulk load accepts.
  *
  * @internal
  */
@@ -30,87 +30,92 @@ interface BulkLoadRun {
     loadRows: () => Promise<BulkLoadResult>;
 }
 /**
- * Run a bulk load with relaxed writer durability, then restore the
- * operator-configured level. The caller must hold the database's writer lock
- * for the whole call so that no other write commits under the relaxed level.
- *
- * Interruption safety, by failure mode:
- * - A load statement fails: the surrounding transaction rolls back, the
- *   configured level is restored, and the database is exactly as it was before
- *   the load; the operator recovers by re-running the load.
- * - The process crashes mid-load: `PRAGMA synchronous` is connection state
- *   that SQLite never stores in the database file, so the next open re-applies
- *   the configured level, and the uncommitted transaction rolls back from the
- *   WAL on open.
- * - Power loss or an OS crash during a load at 'off': SQLite documents that
- *   the file may be corrupted, which is why 'off' fits only a load the
- *   operator can re-run from scratch; 'normal' keeps WAL corruption safety.
- *
- * The restore runs on both the success and the failure path. A restore pragma
- * only fails when the writer connection itself is gone, so on a committed load
- * that failure is reported as 'DURABILITY_RESTORE_FAILED', which tells the
- * operator the load committed and must not be re-run; on a failed load the
- * original load error stays dominant.
- *
- * On success, and only when the load changed rows, the WAL is checkpointed
- * after the restore so the loaded pages are written into the main database
- * file and fsync'd at the restored synchronous level. A reader holding the WAL
- * can defer that transfer: the checkpoint retries a few times and then leaves
- * the remaining pages for a later checkpoint rather than failing a load that
- * has already committed, so those pages stay in the WAL until then. The
- * checkpoint runs synchronously in the engine and blocks the event loop for
- * the flush, which grows with the size of the load.
- *
- * A multi-batch import passes `checkpoint: false` on every load but the last so
- * the one fsyncing checkpoint is paid once at the end instead of once per
- * batch; each intermediate load still restores the configured level, and
- * SQLite's automatic checkpoint keeps the WAL bounded during the import at the
- * relaxed level with no fsync of its own.
- *
- * A database that captures its own change log runs no checkpoint here at all,
- * whatever the caller asked for. A checkpoint ahead of the capture would let
- * SQLite overwrite the very frames this load wrote. Its cycle checkpoints
- * instead, once it has those frames.
+ * Executes a bulk load at a relaxed synchronous level, then restores the level
+ * that the operator configured. The caller must hold the writer lock for the
+ * whole call so that no other write commits at the relaxed level.
+ *
+ * Each failure leaves the database in a known state:
+ * - When a load statement fails, SQLite rolls the transaction back and this
+ *   function restores the configured level, so the operator can re-run the load.
+ * - When the process crashes during a load, SQLite rolls the uncommitted
+ *   transaction back from the WAL on the next open, and that open applies the
+ *   configured level again, because SQLite keeps `PRAGMA synchronous` on the
+ *   connection and never stores it in the file.
+ * - When the power fails or the operating system crashes during a load at
+ *   'off', SQLite documents that the file can be corrupted, so 'off' suits only
+ *   a load that the operator can re-run from scratch, while 'normal' keeps the
+ *   WAL safe from corruption.
+ *
+ * This function restores the level on the success path and on the failure
+ * path. When the restore fails after a committed load, it throws
+ * 'DURABILITY_RESTORE_FAILED' so that the operator knows that the load
+ * committed and must not be re-run; when the load itself failed, it rethrows
+ * the load error.
+ *
+ * After a load that committed and changed rows, this function checkpoints the
+ * WAL at the restored level, which copies the loaded pages into the main
+ * database file and fsyncs them. While a reader holds the WAL open, SQLite can
+ * leave pages uncopied, so this function tries the checkpoint up to three times
+ * and then returns without failing the committed load, leaving the remaining
+ * pages for a later checkpoint. On a driver that calls SQLite on the main
+ * thread, the checkpoint blocks the event loop for as long as the flush takes,
+ * which grows with the size of the load.
+ *
+ * A caller that imports in several batches should pass `checkpoint: false` on
+ * every load except the last, so that it pays for one fsyncing checkpoint at
+ * the end. Each of those loads still restores the configured level, while
+ * SQLite's automatic checkpoint keeps the WAL bounded at the relaxed level
+ * without an fsync.
+ *
+ * On a database that captures its own change log, this function skips the
+ * checkpoint whatever the caller asked for, because a checkpoint before the
+ * capture would let SQLite overwrite the frames that this load wrote. The
+ * backup cycle checkpoints once it has captured those frames.
  *
  * @internal
  */
 declare function runBulkLoad(run: BulkLoadRun): Promise<BulkLoadResult>;
 
 /**
- * Builds a {@link SQLiteDriver} from an implementation, copying across only the optional members Sirannon supports.
+ * Returns a frozen {@link SQLiteDriver} that holds your implementation's capabilities, its `open` function, and only the optional members that Sirannon supports.
  *
- * @param driver - The driver implementation.
- * @returns The driver, ready to pass to a `Sirannon` registry.
+ * @param config - The driver implementation.
+ * @returns The driver, which you can pass to a `Sirannon` registry.
  *
  * @public
  */
 declare function defineDriver(config: SQLiteDriver): SQLiteDriver;
 
 /**
- * Writer durability a database opens at when you name none.
+ * The writer durability level that Sirannon applies when you pass no `synchronous` option.
  *
  * @public
  */
 declare const DEFAULT_SYNCHRONOUS: SynchronousLevel;
 /**
- * Map a synchronous level to its PRAGMA argument through an allowlist so that a
- * value smuggled past the type system can never reach SQL interpolation.
+ * Returns the `PRAGMA synchronous` argument for a durability level from a fixed
+ * lookup table, so that the SQL string can contain only `OFF`, `NORMAL`,
+ * `FULL`, or `EXTRA`.
+ *
+ * @param level - The durability level, or `undefined` for {@link DEFAULT_SYNCHRONOUS}.
+ * @returns The upper-case `PRAGMA synchronous` argument.
+ * @throws {@link SirannonError} with code `INVALID_SYNCHRONOUS` when `level` is none of the four levels.
  *
  * @public
  */
 declare function synchronousPragmaValue(level: SynchronousLevel | undefined): string;
 /**
- * Reports whether a value is one of the durability levels SQLite accepts.
+ * Returns `true` when a value is one of the durability levels that SQLite accepts for `PRAGMA synchronous`.
  *
  * @param value - The value to check.
- * @returns True when it is a valid level.
+ * @returns `true` when the value is `off`, `normal`, `full`, or `extra`.
  *
  * @public
  */
 declare function isSynchronousLevel(value: unknown): value is SynchronousLevel;
 
 /**
- * Operations the lifecycle manager calls back into on the owning registry.
+ * The registry supplies these functions so that the lifecycle manager can open, close, count, and look up its databases.
  *
  * @internal
  */
@@ -121,7 +126,9 @@ interface LifecycleCallbacks {
     has: (id: string) => boolean;
 }
 /**
- * Opens databases on demand, evicts idle ones, and enforces the configured open-database limit.
+ * Opens a database through the `autoOpen` resolver when the registry asks for it, and closes each database that stays idle for `idleTimeout` or longer.
+ *
+ * When one more open database would exceed `maxOpen`, the manager first closes the least recently used database.
  *
  * @internal
  */
@@ -145,50 +152,56 @@ declare class LifecycleManager {
 }
 
 /**
- * How tenant identifiers map onto database files.
+ * Configures how {@link createTenantResolver} maps a tenant ID to a database file.
  *
  * @public
  */
 interface TenantResolverOptions {
     /**
-     * Directory every tenant's database file is written to.
+     * The directory that holds every tenant's database file.
      */
     basePath: string;
     /**
-     * File extension appended to the tenant identifier. Default: '.db'.
+     * The file extension that the resolver appends to the tenant ID, which defaults to `.db`.
      */
     extension?: string;
     /**
-     * Options every tenant database opens with.
+     * The options with which Sirannon opens every tenant database.
      */
     defaultOptions?: DatabaseOptions;
 }
 /**
- * Checks a tenant identifier against the characters and length a file name may carry.
+ * Returns a tenant ID unchanged when it is safe to use in a file name, which
+ * means 1 to 255 characters that start with a lowercase letter or a digit and
+ * continue with lowercase letters, digits, underscores, or hyphens.
+ *
+ * The function returns `undefined` for an ID with a capital letter, because on
+ * a file system that ignores case, such as the default one on macOS or
+ * Windows, `Acme.db` and `acme.db` name the same file.
  *
- * @param id - The identifier to check.
- * @returns The identifier when it is safe, and undefined when it is not.
+ * @param id - The ID to check.
+ * @returns The ID when it is safe, or `undefined` otherwise.
  *
  * @public
  */
 declare function sanitizeTenantId(id: string): string | undefined;
 /**
- * Builds the database file path for one tenant.
+ * Returns the database file path for one tenant.
  *
- * @param basePath - Directory the file is written to.
- * @param tenantId - Identifier of the tenant.
- * @param extension - File extension to append. Default: '.db'.
- * @returns The full path for that tenant's database file.
- * @throws When the identifier is unsafe or the resulting file name is too long.
+ * @param basePath - The directory that holds the file.
+ * @param tenantId - The tenant's ID.
+ * @param extension - The file extension to append, which defaults to `.db`.
+ * @returns The full path of that tenant's database file.
+ * @throws An `Error` when {@link sanitizeTenantId} refuses the ID, or when the file name exceeds 255 characters.
  *
  * @public
  */
 declare function tenantPath(basePath: string, tenantId: string, extension?: string): string;
 /**
- * Builds a resolver that turns a tenant identifier into a database path, for {@link LifecycleConfig.autoOpen}.
+ * Returns a resolver for {@link LifecycleConfig.autoOpen} that turns a tenant ID into a database path.
  *
- * @param options - Base directory, file extension, and the options each tenant database opens with.
- * @returns A resolver that returns a path and options, or undefined for an unsafe identifier.
+ * @param options - The base directory, the file extension, and the options for each tenant database.
+ * @returns A resolver that returns a path and options, or `undefined` for an ID that {@link sanitizeTenantId} refuses or a file name over 255 characters.
  *
  * @public
  */
@@ -204,50 +217,50 @@ declare function createTenantResolver(options: TenantResolverOptions): (id: stri
  */
 declare const MIGRATION_FILENAME_PATTERN: RegExp;
 /**
- * The three parts of a migration file name.
+ * Holds the three parts of a migration file name.
  *
  * @public
  */
 interface ParsedMigrationFilename {
     /**
-     * Version number the file name starts with.
+     * The version number at the start of the file name.
      */
     version: number;
     /**
-     * Migration name between the version and the direction.
+     * The migration name between the version and the direction.
      */
     name: string;
     /**
-     * Whether the file applies the migration or undoes it.
+     * `up` for the SQL that applies the migration, or `down` for the SQL that undoes it.
      */
     direction: 'up' | 'down';
 }
 /**
  * Splits a migration file name into its version, name, and direction.
  *
- * @param filename - File name such as `001_create_orders.up.sql`.
- * @returns The three parts, or null when the name does not match the expected form.
+ * @param filename - A file name such as `001_create_orders.up.sql`.
+ * @returns The three parts, or `null` when the name has another form.
  *
  * @public
  */
 declare function parseMigrationFilename(filename: string): ParsedMigrationFilename | null;
 
 /**
- * How a set of migration files is turned into migrations.
+ * Configures how {@link migrationsFromFiles} builds migrations from a set of files.
  *
  * @public
  */
 interface MigrationsFromFilesOptions {
     /**
-     * Marks the migration an existing database starts from.
+     * Marks one migration as a baseline, which a new database runs in place of the earlier versions.
      */
     baseline?: BaselineFileOption;
 }
 /**
- * Builds migrations from file contents you have already read, which suits a bundler that inlines the SQL.
+ * Returns migrations built from file contents that you already hold in memory, such as SQL that a bundler inlines.
  *
- * @param files - Migration file names mapped to their SQL.
- * @param options - The baseline to apply, when an existing database starts from one.
+ * @param files - An object that maps each migration file name to its SQL text.
+ * @param options - The baseline, when one migration replaces the earlier versions for a new database.
  * @returns The migrations, in ascending version order.
  *
  * @public
@@ -271,49 +284,51 @@ declare class MigrationRunner {
 }
 
 /**
- * Packs a credential into one WebSocket subprotocol a handshake can offer.
+ * Encodes a credential as one WebSocket subprotocol that a handshake can offer.
  *
- * A browser sends no header on a WebSocket upgrade, so a credential travels as a
- * subprotocol instead, and a subprotocol accepts only the characters a header
- * token allows. This encodes the credential so that any text survives the trip,
- * and {@link readSubprotocolCredential} reads it back on the server.
+ * A browser sends no custom header on a WebSocket upgrade, so the client sends
+ * the credential as a subprotocol, which may contain only the characters that a
+ * header token allows. This function encodes the credential in base64url so
+ * that any text fits, and {@link readSubprotocolCredential} decodes it on the
+ * server.
  *
- * @param prefix - Text naming the scheme, which the server matches on.
- * @param credential - The credential to carry.
+ * @param prefix - The text that names the scheme, which the server matches on.
+ * @param credential - The credential to encode.
  * @returns The subprotocol to pass as `webSocketProtocols`.
  *
  * @public
  */
 declare function toSubprotocolCredential(prefix: string, credential: string): string;
 /**
- * Reads a header from a request, whatever casing the runtime reported it under.
+ * Returns a header from a request, whatever the casing of the header name that the runtime reported.
  *
- * @param ctx - The request the `authenticate` hook received.
- * @param name - Name of the header to read.
- * @returns The header value, or undefined where the request carries none.
+ * @param ctx - The request that Sirannon passed to the `authenticate` hook.
+ * @param name - The name of the header to return.
+ * @returns The header value, or undefined when the request has no such header.
  *
  * @public
  */
 declare function readHeader(ctx: RequestContext, name: string): string | undefined;
 /**
- * Reads the token from a request's `Authorization: Bearer` header.
+ * Returns the token from a request's `Authorization: Bearer` header.
  *
- * @param ctx - The request the `authenticate` hook received.
- * @returns The token, or undefined where the request carries another scheme or none.
+ * @param ctx - The request that Sirannon passed to the `authenticate` hook.
+ * @returns The token, or undefined when the request has no `Authorization` header, uses another scheme, or sends an empty token.
  *
  * @public
  */
 declare function readBearerToken(ctx: RequestContext): string | undefined;
 /**
- * Reads the credential a WebSocket upgrade offered under a prefix.
+ * Returns the credential that a WebSocket upgrade offered under a prefix.
  *
- * The upgrade carries the whole offer, including the `sirannon.v1` identifier the
- * client sends ahead of its own entries, so this picks the first entry under the
- * prefix and unpacks what {@link toSubprotocolCredential} put there.
+ * The upgrade request lists every offered subprotocol, including the
+ * `sirannon.v1` identifier that the client sends ahead of its own entries, so
+ * this function takes the first entry that starts with the prefix and decodes
+ * what {@link toSubprotocolCredential} encoded there.
  *
- * @param ctx - The request the `authenticate` hook received.
- * @param prefix - The same text passed to {@link toSubprotocolCredential}.
- * @returns The credential, or undefined where the offer carries none under that prefix.
+ * @param ctx - The request that Sirannon passed to the `authenticate` hook.
+ * @param prefix - The same text that you passed to {@link toSubprotocolCredential}.
+ * @returns The credential, or undefined when no offered subprotocol starts with that prefix or its value fails to decode.
  *
  * @public
  */