@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/core/index.d.ts

@@ -1,17 +1,24 @@
-import { e as SQLiteConnection, s as SynchronousLevel, a as SQLiteDriver, t as WorkerHostOptions, P as Params, E as ExecuteResult, D as DatabaseOptions, L as LifecycleConfig, M as Migration, q as MigrationResult, r as RollbackResult } from '../types-zhnRXrsb.js';
-export { A as AfterQueryHook, u as AppliedMigration, v as AppliedMigrationEntry, f as BackupScheduleOptions, w as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, k as BeforeSubscribeHook, o as CDCMetrics, h as ChangeEvent, x as ChangeOperation, y as ClusterReadEndpointInfo, C as ClusterStatusInfo, j as ConnectionHookContext, n as ConnectionMetrics, d as DatabaseCloseHook, c as DatabaseOpenHook, z as DriverCapabilities, F as DriverWorkerEntry, H as HookConfig, G as MIGRATION_NAME_RE, l as MetricsConfig, I as MigrationBaseline, J as MigrationSource, N as NodeHealth, K as NodeHealthReason, O as NodeHealthState, U as OpenOptions, i as QueryHookContext, m as QueryMetrics, Q as QueryOptions, R as ReadConcern, g as ReadConcernLevel, V as RunResult, X as SQLiteStatement, S as SirannonOptions, Y as Subscription, p as SubscriptionBuilder, T as Transaction, W as WriteConcern, Z as WriteConcernLevel, _ as WriterWorkerOptions } from '../types-zhnRXrsb.js';
-import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-1JHu8pid.js';
-export { c as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, R as ReplicationStatusInfo, f as RequestContext, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-1JHu8pid.js';
-export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DKRVUC3l.js';
-import { D as Database } from '../database-BY0L5Q2n.js';
-export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-BY0L5Q2n.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-Bw5MdNCu.js';
-export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-CL6piSnD.js';
-import { B as BaselineFileOption } from '../baseline-Br77Fnhb.js';
-export { S as Sirannon } from '../sirannon-DaQSyhbJ.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-9DcvxcE5.js';
-import '../types-C_D8IhpO.js';
+import { e as SQLiteConnection, n as SynchronousLevel, a as SQLiteDriver, W as WorkerHostOptions, D as DatabaseOptions, L as LifecycleConfig, M as Migration, m as MigrationResult, R as RollbackResult } from '../types-rVZKnKN-.js';
+export { A as AfterQueryHook, o as AppliedMigration, p as AppliedMigrationEntry, f as BackupScheduleOptions, q as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, h as BeforeSubscribeHook, l as CDCMetrics, r as ClusterReadEndpointInfo, C as ClusterStatusInfo, g as ConnectionHookContext, k as ConnectionMetrics, d as DatabaseCloseHook, c as DatabaseOpenHook, s as DriverCapabilities, t as DriverWorkerEntry, H as HookConfig, u as MIGRATION_NAME_RE, i as MetricsConfig, v as MigrationBaseline, w as MigrationSource, N as NodeHealth, x as NodeHealthReason, y as NodeHealthState, O as OpenOptions, Q as QueryHookContext, j as QueryMetrics, z as RunResult, E as SQLiteStatement, S as SirannonOptions, T as Transaction, F as WriterWorkerOptions } from '../types-rVZKnKN-.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-Dab_Jvd_.js';
+export { c as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, R as ReplicationStatusInfo, f as RequestContext, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-Dab_Jvd_.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DDmXB754.js';
+import { D as Database } from '../database-B5Qv1-cU.js';
+export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-B5Qv1-cU.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-BCejqzNA.js';
+import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
+import { P as Params, E as ExecuteResult } from '../query-types-DL3LtPvY.js';
+export { C as ChangeEvent, b as ChangeOperation, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, c as Subscription, S as SubscriptionBuilder, W as WriteConcern, d as WriteConcernLevel } from '../query-types-DL3LtPvY.js';
+export { S as Sirannon } from '../sirannon-CMhiJa5Y.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-hlbhqu7q.js';
+import '../types-CjhxcjhA.js';
 
+/**
+ * Reports whether a value is one of the durability levels a bulk load accepts.
+ *
+ * @internal
+ */
 declare function isBulkLoadDurability(value: unknown): value is BulkLoadDurability;
 interface BulkLoadRun {
     writer: SQLiteConnection;
@@ -24,7 +31,7 @@ interface BulkLoadRun {
 /**
  * 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 no other write commits under the relaxed level.
+ * 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
@@ -58,9 +65,16 @@ interface BulkLoadRun {
  * 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.
+ *
+ * @internal
  */
 declare function runBulkLoad(run: BulkLoadRun): Promise<BulkLoadResult>;
 
+/**
+ * Settings a connection pool opens its writer and readers with.
+ *
+ * @internal
+ */
 interface ConnectionPoolOptions {
     driver: SQLiteDriver;
     path: string;
@@ -71,6 +85,11 @@ interface ConnectionPoolOptions {
     useWriterWorker?: boolean;
     workerHostOptions?: WorkerHostOptions;
 }
+/**
+ * Holds one writer connection and a rotating set of reader connections for a single database file.
+ *
+ * @internal
+ */
 declare class ConnectionPool {
     private readonly writer;
     private readonly readers;
@@ -85,27 +104,80 @@ declare class ConnectionPool {
     close(): Promise<void>;
 }
 
+/**
+ * Runs a read on one connection and returns the rows with their values decoded.
+ *
+ * @internal
+ */
 declare function query<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T[]>;
+/**
+ * Runs a read on one connection and returns the first row, or undefined when there is none.
+ *
+ * @internal
+ */
 declare function queryOne<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T | undefined>;
+/**
+ * Runs one write on a connection and returns the change count and last inserted row id.
+ *
+ * @internal
+ */
 declare function execute(conn: SQLiteConnection, sql: string, params?: Params, trusted?: boolean): Promise<ExecuteResult>;
+/**
+ * Runs one statement over many parameter sets on a connection and returns a result per set.
+ *
+ * @internal
+ */
 declare function executeBatch(conn: SQLiteConnection, sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
 
+/**
+ * Builds a {@link SQLiteDriver} from an implementation, copying across only the optional members Sirannon supports.
+ *
+ * @param driver - The driver implementation.
+ * @returns The driver, ready to pass to a `Sirannon` registry.
+ *
+ * @public
+ */
 declare function defineDriver(config: SQLiteDriver): SQLiteDriver;
 
+/**
+ * Writer durability a database opens at when you name none.
+ *
+ * @public
+ */
 declare const DEFAULT_SYNCHRONOUS: SynchronousLevel;
 /**
- * Map a synchronous level to its PRAGMA argument through an allowlist, so a
+ * 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.
+ *
+ * @public
  */
 declare function synchronousPragmaValue(level: SynchronousLevel | undefined): string;
+/**
+ * Reports whether a value is one of the durability levels SQLite accepts.
+ *
+ * @param value - The value to check.
+ * @returns True when it is a valid level.
+ *
+ * @public
+ */
 declare function isSynchronousLevel(value: unknown): value is SynchronousLevel;
 
+/**
+ * Operations the lifecycle manager calls back into on the owning registry.
+ *
+ * @internal
+ */
 interface LifecycleCallbacks {
     open: (id: string, path: string, options?: DatabaseOptions) => Promise<Database>;
     close: (id: string) => Promise<void>;
     count: () => number;
     has: (id: string) => boolean;
 }
+/**
+ * Opens databases on demand, evicts idle ones, and enforces the configured open-database limit.
+ *
+ * @internal
+ */
 declare class LifecycleManager {
     #private;
     private readonly config;
@@ -125,31 +197,121 @@ declare class LifecycleManager {
     private ensureNotDisposed;
 }
 
+/**
+ * How tenant identifiers map onto database files.
+ *
+ * @public
+ */
 interface TenantResolverOptions {
+    /**
+     * Directory every tenant's database file is written to.
+     */
     basePath: string;
+    /**
+     * File extension appended to the tenant identifier. Default: '.db'.
+     */
     extension?: string;
+    /**
+     * Options every tenant database opens with.
+     */
     defaultOptions?: DatabaseOptions;
 }
+/**
+ * Checks a tenant identifier against the characters and length a file name may carry.
+ *
+ * @param id - The identifier to check.
+ * @returns The identifier when it is safe, and undefined when it is not.
+ *
+ * @public
+ */
 declare function sanitizeTenantId(id: string): string | undefined;
+/**
+ * Builds 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.
+ *
+ * @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}.
+ *
+ * @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.
+ *
+ * @public
+ */
 declare function createTenantResolver(options: TenantResolverOptions): (id: string) => {
     path: string;
     options?: DatabaseOptions;
 } | undefined;
 
+/**
+ * Matches a migration file name of the form `001_create_orders.up.sql`.
+ *
+ * @public
+ */
 declare const MIGRATION_FILENAME_PATTERN: RegExp;
+/**
+ * The three parts of a migration file name.
+ *
+ * @public
+ */
 interface ParsedMigrationFilename {
+    /**
+     * Version number the file name starts with.
+     */
     version: number;
+    /**
+     * Migration name between the version and the direction.
+     */
     name: string;
+    /**
+     * Whether the file applies the migration or 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.
+ *
+ * @public
+ */
 declare function parseMigrationFilename(filename: string): ParsedMigrationFilename | null;
 
+/**
+ * How a set of migration files is turned into migrations.
+ *
+ * @public
+ */
 interface MigrationsFromFilesOptions {
+    /**
+     * Marks the migration an existing database starts from.
+     */
     baseline?: BaselineFileOption;
 }
+/**
+ * Builds migrations from file contents you have already read, which suits a bundler that inlines the SQL.
+ *
+ * @param files - Migration file names mapped to their SQL.
+ * @param options - The baseline to apply, when an existing database starts from one.
+ * @returns The migrations, in ascending version order.
+ *
+ * @public
+ */
 declare function migrationsFromFiles(files: Record<string, unknown>, options?: MigrationsFromFilesOptions): Migration[];
 
+/**
+ * Applies and rolls back migrations against one connection.
+ *
+ * @internal
+ */
 declare class MigrationRunner {
     static run(conn: SQLiteConnection, migrations: Migration[]): Promise<MigrationResult>;
     private static retryOnConcurrentConflict;