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

package/dist/database-CGDsXW1K.d.ts

@@ -0,0 +1,959 @@
+import { D as DatabaseBackupController, B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions } from './database-backup-DcLhxoa1.js';
+import { S as SQLiteDriver, U as SynchronousLevel, ao as WorkerHostOptions, I as SQLiteConnection, T as Transaction, ap as WriterContext, M as Migration, W as MigrationResult, X as RollbackResult, aj as QueryHookContext, a4 as ConnectionHookContext, a1 as BeforeSubscribeHook, a0 as BeforeSnapshotHook, $ as BeforePushHook, a9 as HookConfig, ab as MetricsConfig, ak as QueryMetrics, a5 as ConnectionMetrics, a2 as CDCMetrics, D as DatabaseOptions, p as BackupFileReport, y as BackupToDestinationOptions, f as BackupRunReport, O as BackupScheduleOptions, g as BackupChain, o as BackupCycleStatus, z as BackupVerifyResult, k as BackupChainRecord, b as BeforeQueryHook, A as AfterQueryHook } from './types-Dc8oWlxj.js';
+import { C as ChangeTracker } from './change-tracker-DqCdeEyx.js';
+import { C as ChangeEvent, d as SubscriptionOptions, S as Subscription, c as SubscriptionBuilder, P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-5B02ixH0.js';
+import { H as HLCTimestamp, c as ReplicationChange, C as ConflictResolver, A as ApplyResult, R as ReplicationBatch } from './types-DqODKeOq.js';
+import { A as AppliedMigrationRow, c as BulkLoadOptions, a as BulkLoadResult } from './server-options-aYtCkefX.js';
+import { L as LiveQueryOptions, a as LiveQuery } from './types-CEJG0eFS.js';
+
+/**
+ * Settings that {@link ConnectionPool.create} uses to open the writer and reader connections.
+ *
+ * @internal
+ */
+interface ConnectionPoolOptions {
+    driver: SQLiteDriver;
+    path: string;
+    readOnly?: boolean;
+    readPoolSize?: number;
+    walMode?: boolean;
+    synchronous?: SynchronousLevel;
+    walAutoCheckpoint?: number;
+    useWriterWorker?: boolean;
+    workerHostOptions?: WorkerHostOptions;
+}
+/**
+ * Opens one writer connection and a set of reader connections for a single database file, and returns the readers in rotation.
+ *
+ * @internal
+ */
+declare class ConnectionPool {
+    private readonly writer;
+    private readonly readers;
+    private readerIndex;
+    private closed;
+    private constructor();
+    static create(options: ConnectionPoolOptions): Promise<ConnectionPool>;
+    acquireReader(): SQLiteConnection;
+    acquireWriter(): SQLiteConnection;
+    /** Returns the writer and every reader, so that the caller can apply an operation to every connection in the pool. */
+    connections(): readonly SQLiteConnection[];
+    get readerCount(): number;
+    get isReadOnly(): boolean;
+    close(): Promise<void>;
+}
+
+interface DeviceRetentionPolicy {
+    cursorRetentionMs: number;
+    maxChangesHeldForDevice: number;
+}
+interface DeviceRetentionOptions {
+    deviceCursorRetention?: number;
+    maxChangesHeldForDevice?: number;
+}
+interface ChangeRetentionOptions extends DeviceRetentionOptions {
+    cdcRetention?: number;
+}
+
+type ChangeDispatchObserver = (event: ChangeEvent, subscriberCount: number) => void;
+declare class SubscriptionManager {
+    private readonly onDispatched?;
+    constructor(onDispatched?: ChangeDispatchObserver | undefined);
+    private nextId;
+    private readonly subscriptions;
+    private readonly byTable;
+    private readonly batchEndListeners;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscriptionOptions): Subscription;
+    dispatch(events: ChangeEvent[]): void;
+    reportError(error: Error): void;
+    addBatchEndListener(listener: (atTxBoundary: boolean) => void): () => void;
+    endBatch(atTxBoundary: boolean): void;
+    get size(): number;
+    subscriberCount(table: string): number;
+}
+
+/**
+ * Generates hybrid logical clock (HLC) timestamps that order events across nodes.
+ *
+ * Each timestamp has the form `{wallMs hex}-{logical hex}-{nodeId}`, so a plain
+ * string comparison orders two timestamps by wall-clock time, then by logical
+ * counter, then by node ID. The wall-clock part holds milliseconds since the
+ * Unix epoch, and the logical counter orders events within one millisecond.
+ *
+ * Call `now()` to stamp a local write with a timestamp higher than every
+ * earlier one from this clock. Call `receive(remote)` for each remote change,
+ * so that the clock moves ahead of every timestamp that it receives.
+ *
+ * @public
+ */
+declare class HLC {
+    private wallMs;
+    private logical;
+    private readonly nodeId;
+    constructor(nodeId: string);
+    /**
+     * Returns a new timestamp and advances the clock.
+     *
+     * @internal
+     */
+    now(): string;
+    /**
+     * Merges a remote timestamp into the clock and returns the new local timestamp.
+     *
+     * @internal
+     */
+    receive(remote: string): string;
+    /** Compares two encoded timestamps as strings and returns -1, 0, or 1. */
+    static compare(a: string, b: string): number;
+    /** Parses an encoded timestamp into its wall-clock, logical, and node ID parts. */
+    static decode(hlc: string): HLCTimestamp;
+    /**
+     * Returns the string form of a clock reading, padded so that string order matches clock order.
+     *
+     * @param wallMs - The wall-clock milliseconds since the Unix epoch.
+     * @param logical - The counter that orders events within one millisecond.
+     * @param nodeId - The ID of the node that takes the reading.
+     * @returns The encoded stamp.
+     */
+    static encode(wallMs: number, logical: number, nodeId: string): string;
+}
+
+interface StampStatement {
+    sql: string;
+    params: unknown[];
+    trusted: true;
+}
+declare class SyncStamper {
+    readonly nodeId: string;
+    readonly hlc: HLC;
+    private readonly changesTable;
+    private constructor();
+    static init(conn: SQLiteConnection, changesTable?: string): Promise<SyncStamper>;
+    stampStatements(options?: {
+        persistClock?: boolean;
+    }): StampStatement[];
+    applyStamps(txConn: SQLiteConnection): Promise<void>;
+}
+
+type RunExclusive$1 = <T>(op: () => Promise<T>) => Promise<T>;
+declare class DatabaseCdcController {
+    private readonly runExclusive;
+    private readonly acquireWriter;
+    private readonly pollInterval;
+    private readonly retention;
+    private readonly openSnapshotConnection;
+    private readonly deviceRetention;
+    private readonly onDispatched?;
+    private tracker;
+    private subscriptionManager;
+    private liveConnRequest;
+    private stopPolling;
+    private stamper;
+    private epochRequest;
+    constructor(runExclusive: RunExclusive$1, acquireWriter: () => SQLiteConnection, pollInterval: number, retention: number, openSnapshotConnection: (() => Promise<SQLiteConnection>) | null, deviceRetention: DeviceRetentionPolicy, onDispatched?: ChangeDispatchObserver | undefined);
+    ensureEpoch(): Promise<string>;
+    readAtPositionWith<T>(read: (conn: SQLiteConnection) => Promise<T>): Promise<{
+        value: T;
+        position: string;
+        seq: bigint;
+    }>;
+    liveConnection(): Promise<{
+        conn: SQLiteConnection;
+        run: RunExclusive$1;
+    }>;
+    closeLiveConnection(): Promise<void>;
+    get subscriptions(): SubscriptionManager | null;
+    get changeTracker(): ChangeTracker | null;
+    watch(table: string): Promise<void>;
+    ensureStamper(): Promise<SyncStamper>;
+    ensureStamping(): Promise<void>;
+    stampStatements(options?: {
+        persistClock?: boolean;
+    }): readonly StampStatement[] | null;
+    applyStamps(txConn: SQLiteConnection): Promise<void>;
+    unwatch(table: string): Promise<void>;
+    on(table: string): SubscriptionBuilder;
+    runTransaction<T>(writer: SQLiteConnection, fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    stop(): void;
+    private ensure;
+    private ensurePolling;
+}
+
+declare class WriterLock {
+    private tail;
+    private readonly context;
+    constructor(context?: WriterContext);
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    isHeld(): boolean;
+    settle(): Promise<void>;
+    detached<T>(operation: () => T): T;
+}
+
+interface DatabaseMigrationDeps {
+    pool: ConnectionPool;
+    writerLock: WriterLock;
+    changeTracker: () => ChangeTracker | null;
+}
+declare class DatabaseMigrationController {
+    private readonly deps;
+    constructor(deps: DatabaseMigrationDeps);
+    migrate(migrations: Migration[]): Promise<MigrationResult>;
+    rollback(migrations: Migration[], version?: number): Promise<RollbackResult>;
+    applied(): Promise<AppliedMigrationRow[]>;
+}
+
+/**
+ * The lifecycle points at which you can register a hook.
+ *
+ * @internal
+ */
+type HookEvent = 'beforeQuery' | 'afterQuery' | 'beforeConnect' | 'databaseOpen' | 'databaseClose' | 'beforeSubscribe' | 'beforeSnapshot' | 'beforePush';
+/**
+ * The context that a subscribe hook receives.
+ *
+ * @internal
+ */
+type SubscribeHookContext = Parameters<BeforeSubscribeHook>[0];
+/**
+ * The context that a snapshot hook receives.
+ *
+ * @internal
+ */
+type SnapshotHookContext = Parameters<BeforeSnapshotHook>[0];
+/**
+ * The context that a push hook receives.
+ *
+ * @internal
+ */
+type PushHookContext = Parameters<BeforePushHook>[0];
+/**
+ * Maps each lifecycle point to the context that its hooks receive.
+ *
+ * @internal
+ */
+interface HookEventContextMap {
+    beforeQuery: QueryHookContext;
+    afterQuery: QueryHookContext & {
+        durationMs: number;
+    };
+    beforeConnect: ConnectionHookContext;
+    databaseOpen: ConnectionHookContext;
+    databaseClose: ConnectionHookContext;
+    beforeSubscribe: SubscribeHookContext;
+    beforeSnapshot: SnapshotHookContext;
+    beforePush: PushHookContext;
+}
+/**
+ * The function that you register as a hook for one lifecycle point.
+ *
+ * @internal
+ */
+type HookHandler<E extends HookEvent> = (ctx: HookEventContextMap[E]) => void | Promise<void>;
+/**
+ * Removes the hook whose registration returned this function, and a second call has no effect.
+ *
+ * @public
+ */
+type HookDispose = () => void;
+
+/**
+ * Stores the lifecycle hooks for a database or registry and calls each event's hooks in the order that the caller registered them.
+ *
+ * @internal
+ */
+declare class HookRegistry {
+    private hooks;
+    constructor(config?: HookConfig);
+    register<E extends HookEvent>(event: E, hook: HookHandler<E>): HookDispose;
+    invoke<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): Promise<void>;
+    invokeSync<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): void;
+    invokeSyncIgnoringFailures<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): void;
+    has(event: HookEvent): boolean;
+    count(event: HookEvent): number;
+    clear(event?: HookEvent): void;
+    private addHook;
+    private loadConfig;
+}
+
+type QueryOutcome = Pick<QueryMetrics, 'rowsReturned' | 'changes'>;
+type QueryOutcomeMeasure<T> = (result: T) => QueryOutcome;
+/**
+ * Times each query and passes query timings, connection events, and change-capture events to the metrics callbacks that the caller configures.
+ *
+ * @internal
+ */
+declare class MetricsCollector {
+    private config;
+    constructor(config?: MetricsConfig);
+    trackQuery<T>(fn: () => Promise<T>, context: Omit<QueryMetrics, 'durationMs' | 'error'>, measure?: QueryOutcomeMeasure<T>): Promise<T>;
+    trackConnection(metrics: ConnectionMetrics): void;
+    trackCDCEvent(metrics: CDCMetrics): void;
+    observeDispatch(databaseId: string): ChangeDispatchObserver | undefined;
+    get active(): boolean;
+}
+
+interface ObservedStatement {
+    sql: string;
+    params?: Params;
+}
+declare class DatabaseObserver {
+    private readonly databaseId;
+    private readonly localHooks;
+    private readonly parentHooks;
+    private readonly metrics;
+    constructor(databaseId: string, localHooks: HookRegistry, parentHooks: HookRegistry | null, metrics: MetricsCollector | null);
+    get observesQueries(): boolean;
+    withQueryHooks<T>(sql: string, params: Params | undefined, options: QueryOptions | undefined, op: () => Promise<T>): Promise<T>;
+    track<T>(sql: string, op: () => Promise<T>, measure?: QueryOutcomeMeasure<T>): Promise<T>;
+    withTransactionHooks(statements: readonly ObservedStatement[], op: () => Promise<ExecuteResult[]>): Promise<ExecuteResult[]>;
+    private fireAfterEach;
+    private trackEach;
+    private fireBefore;
+    private fireAfter;
+}
+
+interface DatabaseReadDeps {
+    pool: ConnectionPool;
+    writerLock: WriterLock;
+    observer: DatabaseObserver;
+}
+
+interface StagedRecovery {
+    resumeSeq: bigint | null;
+    appliedSeq: bigint | null;
+    /**
+     * The error that stopped the recovery apply, or `null`. The staged rows stay
+     * in place after the failed apply, and the resume sequence still covers
+     * them, so the caller opens the subscription regardless. When the server's
+     * schema gate refuses that subscription, the refusal error states that the
+     * device has to migrate first. The caller then has to retry the recovery
+     * itself, because the resume sequence lies past the unapplied transaction,
+     * so the server resends none of it.
+     */
+    applyError: unknown | null;
+}
+
+/**
+ * The position up to which a device has pulled from its server, and the epoch
+ * of the server change log that the position comes from.
+ *
+ * @public
+ */
+interface DeviceSyncPullState {
+    /** The highest server change-log position that this device has applied. */
+    seq: bigint;
+    /** The epoch of the server change log that the position comes from. */
+    epoch: string | undefined;
+}
+/**
+ * Gives a device's sync loop the calls that it makes on the local database,
+ * which stage and apply the changes that the server sends, read the local
+ * changes that the device has yet to push, and store the push and pull
+ * cursors. Get one from {@link Database.deviceSync}.
+ *
+ * @public
+ */
+interface DeviceSyncPort {
+    /** Returns the node identifier that this device stamps on its own changes. */
+    identity(): Promise<{
+        nodeId: string;
+    }>;
+    /** Applies one pulled transaction and advances the pull cursor in the same write. */
+    applyPulledTransaction(changes: readonly ReplicationChange[], pullSeq: bigint, resolver?: ConflictResolver | ((table: string) => ConflictResolver)): Promise<ApplyResult>;
+    /** Stores pulled changes on disk without applying them, so that a device that stops part-way can resume from them, and returns the highest position stored, or null for an empty list. */
+    stagePulledChanges(events: readonly ChangeEvent[]): Promise<bigint | null>;
+    /** Applies each complete staged transaction in order, and returns the position of the last one applied, or null when it applied none. */
+    applyStagedPull(resolver?: ConflictResolver | ((table: string) => ConflictResolver), onChange?: (event: ChangeEvent) => void): Promise<bigint | null>;
+    /** Applies the changes that an earlier session left staged, and returns the position to resume from, the position applied, and any error that stopped this apply. */
+    recoverStagedPull(resolver?: ConflictResolver | ((table: string) => ConflictResolver), onChange?: (event: ChangeEvent) => void): Promise<StagedRecovery>;
+    /** Returns the next batch of local changes that the device has yet to push, or null when none remain. */
+    readOutboxBatch(afterSeq: bigint, limit: number): Promise<ReplicationBatch | null>;
+    /** Counts the local changes that the device has yet to push. */
+    countOutboxPending(afterSeq: bigint): Promise<number>;
+    /** Returns the position up to which the device has pushed. */
+    getPushCursor(): Promise<bigint>;
+    /** Stores the position up to which the device has pushed. */
+    setPushCursor(seq: bigint): Promise<void>;
+    /** Returns the position up to which the device has pulled, or null before its first pull. */
+    getPullState(): Promise<DeviceSyncPullState | null>;
+    /** Returns true when the device must download a fresh snapshot, as {@link DeviceSyncPort.setResyncRequired} last stored. */
+    getResyncRequired(): Promise<boolean>;
+    /** Stores whether the device must download a fresh snapshot. */
+    setResyncRequired(required: boolean): Promise<void>;
+    /** Stores the position up to which the device has pulled, and the epoch that the position comes from. */
+    setPullState(seq: bigint, epoch?: string): Promise<void>;
+    /** Stops change-log pruning from deleting any local change above the pushed position, so that the device can still push it. */
+    protectUnpushedChanges(pushedSeq: bigint): void;
+    /** Returns true when a snapshot download started and has yet to finish. */
+    snapshotLoadPending(): Promise<boolean>;
+    /** Drops the named tables, discards staged pulled changes, and rejects ordinary reads and writes on this database until {@link DeviceSyncPort.endSnapshotLoad} completes. */
+    beginSnapshotLoad(tables: readonly string[]): Promise<void>;
+    /** Executes the schema statements that a snapshot contains. */
+    applySnapshotSchema(schema: readonly string[]): Promise<void>;
+    /** Writes one page of snapshot rows into a table. */
+    loadSnapshotPage(table: string, rows: readonly Record<string, unknown>[]): Promise<void>;
+    /** Replaces the local migration history with the server's. */
+    replaceMigrationHistory(rows: readonly AppliedMigrationRow[]): Promise<void>;
+    /** Finishes a snapshot download: watches the named tables again, turns foreign keys back on, and lifts the block on ordinary reads and writes. */
+    endSnapshotLoad(tables: readonly string[]): Promise<void>;
+    /** Turns foreign keys back on after a failed snapshot download and leaves the download pending, so ordinary reads and writes stay rejected and {@link DeviceSyncPort.snapshotLoadPending} returns true. */
+    abortSnapshotLoad(): Promise<void>;
+}
+
+type RunExclusive = <T>(op: () => Promise<T>) => Promise<T>;
+
+declare class DatabaseSyncController {
+    private readonly runExclusive;
+    private readonly acquireWriter;
+    private readonly cdc;
+    private pkResolver;
+    private tablesReady;
+    private metaReady;
+    private outboxReader;
+    private localPruneBoundary;
+    private snapshotGate;
+    private readonly defaultResolver;
+    constructor(runExclusive: RunExclusive, acquireWriter: () => SQLiteConnection, cdc: DatabaseCdcController);
+    applyChanges(batch: ReplicationBatch, resolver?: ConflictResolver | ((table: string) => ConflictResolver)): Promise<ApplyResult>;
+    devicePort(): DeviceSyncPort;
+    get snapshotLoadBlocked(): boolean;
+    seedSnapshotGate(): void;
+    private applyPulledTransaction;
+    private stagePulled;
+    private applyStagedPull;
+    private recoverStagedPullState;
+    private stagedApplyOptions;
+    private replaceMigrationHistory;
+    private beginSnapshotLoad;
+    private endSnapshotLoad;
+    private applyLocalPruneBoundary;
+    private readOutboxBatch;
+    private countOutboxPending;
+    private getResyncRequired;
+    private setResyncRequired;
+    private getPullState;
+    private setPullState;
+    private getMetaSeq;
+    private setMetaSeq;
+    private ensureMeta;
+    private ensureSyncTables;
+    private ensureOutboxReader;
+    private ensureApplier;
+    private catchUpLocalColumnVersions;
+    private lastAppliedSeq;
+}
+
+/**
+ * Executes 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[]>;
+/**
+ * Executes a read on one connection and returns the first row, or undefined when the read returns none.
+ *
+ * @internal
+ */
+declare function queryOne<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T | undefined>;
+/**
+ * Executes one write on a connection and returns the change count and the row id of the last inserted row.
+ *
+ * @internal
+ */
+declare function execute(conn: SQLiteConnection, sql: string, params?: Params, trusted?: boolean): Promise<ExecuteResult>;
+interface GroupStatement {
+    sql: string;
+    params?: Params;
+    trusted?: boolean;
+}
+/**
+ * Executes one statement on a connection once for each parameter set, and returns one result per set.
+ *
+ * @internal
+ */
+declare function executeBatch(conn: SQLiteConnection, sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
+
+interface GroupCommitterHooks {
+    acquireWriter: () => SQLiteConnection;
+    afterCommit: (writer: SQLiteConnection, sql: string) => Promise<void>;
+    stampStatements: (options?: {
+        persistClock?: boolean;
+    }) => readonly GroupStatement[] | null;
+}
+declare class GroupCommitter {
+    private readonly writerLock;
+    private readonly hooks;
+    private readonly maxGroup;
+    private readonly pending;
+    private running;
+    private scheduled;
+    private loopPromise;
+    constructor(writerLock: WriterLock, hooks: GroupCommitterHooks, maxGroup?: number);
+    submit(sql: string, params?: Params): Promise<ExecuteResult>;
+    submitTransaction(statements: readonly GroupStatement[]): Promise<ExecuteResult[]>;
+    drain(): Promise<void>;
+    runUngrouped(sql: string, params?: Params): Promise<ExecuteResult>;
+    private schedule;
+    private runLoop;
+    private takeBatch;
+    private flush;
+    private needsStamp;
+    private runSingle;
+    private runStampedAlone;
+    private runGroup;
+}
+
+declare class WriteGate {
+    private readonly limit;
+    private readonly retryAfterMs;
+    private inFlight;
+    constructor(limit: number, retryAfterMs: number);
+    run<T>(op: () => Promise<T>): Promise<T>;
+}
+
+interface DatabaseWriteDeps {
+    pool: ConnectionPool;
+    writeGate: WriteGate;
+    writerLock: WriterLock;
+    groupCommitter: GroupCommitter;
+    cdc: DatabaseCdcController;
+    observer: DatabaseObserver;
+    synchronous: SynchronousLevel;
+    walMode: boolean;
+    capturesChangeLog: boolean;
+}
+declare class DatabaseWriteController {
+    private readonly deps;
+    constructor(deps: DatabaseWriteDeps);
+    execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    executeBatch(sql: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    bulkLoad(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+    executeTransaction(statements: readonly {
+        sql: string;
+        params?: Params;
+    }[]): Promise<ExecuteResult[]>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    drain(): Promise<void>;
+    private runStatementsAlone;
+    private runInTransaction;
+}
+
+interface DatabaseInternals {
+    parentHooks?: HookRegistry;
+    metrics?: MetricsCollector;
+}
+interface DatabaseRuntime {
+    pool: ConnectionPool;
+    writeGate: WriteGate;
+    writerLock: WriterLock;
+    hookRegistry: HookRegistry;
+    observer: DatabaseObserver;
+    backups: DatabaseBackupController;
+    cdc: DatabaseCdcController;
+    sync: DatabaseSyncController;
+    groupCommitter: GroupCommitter;
+    writes: DatabaseWriteController;
+    reads: DatabaseReadDeps;
+    migrations: DatabaseMigrationController;
+    loadExtension: (extensionPath: string) => Promise<void>;
+}
+
+/**
+ * Gives every open database its identity, its file, the checks that each
+ * method makes before it does any work, and the methods that close the
+ * database.
+ *
+ * Open a database through {@link Sirannon.open}, which returns a
+ * {@link Database} that extends this class.
+ *
+ * @public
+ */
+declare class DatabaseLifecycle {
+    /** The identifier that this database was opened under. */
+    readonly id: string;
+    /** The file path of the SQLite database. */
+    readonly path: string;
+    /** Whether this database rejects writes. */
+    readonly readOnly: boolean;
+    /**
+     * The retention settings that this database was opened with, which form an empty object when the caller set none.
+     *
+     * @internal
+     */
+    readonly changeRetention: ChangeRetentionOptions;
+    /**
+     * The pool, locks, and controllers that this database sends its work through.
+     *
+     * @internal
+     */
+    protected readonly runtime: DatabaseRuntime;
+    /**
+     * The functions that Sirannon calls while this database closes.
+     *
+     * @internal
+     */
+    protected readonly closeListeners: (() => void | Promise<void>)[];
+    private closing;
+    protected constructor(id: string, path: string, runtime: DatabaseRuntime, options?: DatabaseOptions);
+    /**
+     * Registers a function that Sirannon calls while this database closes.
+     *
+     * @param fn - The function to call during {@link DatabaseLifecycle.close}.
+     *
+     * @internal
+     */
+    addCloseListener(fn: () => void | Promise<void>): void;
+    /**
+     * Closes every connection that this database opened, and stops delivering changes to its subscriptions.
+     */
+    close(): Promise<void>;
+    /**
+     * True once {@link DatabaseLifecycle.close} has started on this database.
+     */
+    get closed(): boolean;
+    /**
+     * The number of read connections in the pool.
+     */
+    get readerCount(): number;
+    /**
+     * Throws when this database is closed, is loading a snapshot, or rejects writes.
+     *
+     * @internal
+     */
+    protected ensureWritable(): void;
+    /**
+     * Throws when this database is closed or is loading a snapshot.
+     *
+     * @internal
+     */
+    protected ensureOpen(): void;
+    /**
+     * Throws when this database is closed.
+     *
+     * @internal
+     */
+    protected ensureNotClosed(): void;
+}
+
+/**
+ * Gives an open database its backup methods: one-off copies, a cron schedule,
+ * the cycle that captures the change log, and queries over the chain of
+ * backups that the cycle writes.
+ *
+ * Open a database through {@link Sirannon.open}, which returns a
+ * {@link Database} that extends this class.
+ *
+ * @public
+ */
+declare class DatabaseBackups extends DatabaseLifecycle {
+    /**
+     * Copies this database to a file while it stays open for reads and writes.
+     *
+     * Sirannon holds the writer only until SQLite copies the first step of pages,
+     * so later writes commit between the steps of the copy and wait for none of it.
+     *
+     * @param destPath - The path of the file that Sirannon writes the copy to.
+     * @returns The run identifier, the timings, the number of pages copied, and the size of the file in bytes.
+     */
+    backup(destPath: string): Promise<BackupFileReport>;
+    /**
+     * Copies this database to a destination that you supply, in fixed-size
+     * pieces, while it stays open for reads and writes.
+     *
+     * Sirannon includes no storage client, so you connect object storage, or any
+     * other store, through the destination.
+     *
+     * Where this runtime has the compiled streaming extension, Sirannon sends each
+     * piece to the destination as SQLite writes it, so the copy needs no local
+     * disk. On every other runtime, Sirannon writes one local file first, which
+     * needs local disk equal to the size of the backup.
+     * {@link DatabaseBackups.backupCapabilities} reports which of the two routes
+     * applies to this runtime.
+     *
+     * @param options - The destination, the naming, the piece size, and the progress callback.
+     * @returns The run identifier, the timings, what the copy wrote, and how many times the copy restarted.
+     */
+    backupTo(options: BackupToDestinationOptions): Promise<BackupRunReport>;
+    /**
+     * Reports which backup operations this database's runtime supports, so that
+     * you can check them before you start a backup.
+     *
+     * @returns Whether this runtime can copy the database, whether a copy needs local disk, and whether it can schedule copies.
+     */
+    backupCapabilities(): BackupCapabilities;
+    /**
+     * Starts copying this database to a directory on a cron schedule, and deletes
+     * the oldest copies beyond {@link BackupScheduleOptions.maxFiles}.
+     *
+     * @param options - The cron expression, destination directory, retention, and time zone, with the callbacks that Sirannon calls after each finished copy and after each failure.
+     */
+    scheduleBackup(options: BackupScheduleOptions): void;
+    /**
+     * Takes one turn of the backup cycle now, without waiting for the interval. A
+     * turn sends any capture that is still waiting, captures the log frames
+     * written since the previous turn, and then checkpoints the log.
+     *
+     * Only a database opened with the `backups` option has a cycle, and on any
+     * other database this throws `BACKUP_UNSUPPORTED`. On a node whose replication
+     * group takes its backups from another node, Sirannon writes nothing on the
+     * turn and reports a skip through `onSkip`.
+     *
+     * @returns What Sirannon wrote on the turn, or undefined when it wrote nothing.
+     */
+    captureBackupChanges(): Promise<BackupRunReport | undefined>;
+    /**
+     * Lists the backup chains at the destination.
+     *
+     * @returns One entry per chain, newest first, each with its full copy and its change pieces in order.
+     */
+    backupChain(): Promise<BackupChain[]>;
+    /**
+     * Returns what this database's backup cycle is doing now, and the outcome of
+     * its recent turns.
+     *
+     * You can poll this while a turn that you started with
+     * {@link DatabaseBackups.captureBackupChanges} is still under way, and during
+     * a full copy of a large database, the status includes the pages that SQLite
+     * has copied so far.
+     *
+     * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
+     */
+    backupStatus(): BackupCycleStatus;
+    /**
+     * Fetches one of this database's backups from the destination and checks it
+     * against the record that Sirannon wrote with that backup.
+     *
+     * A restore fails on a damaged piece only after the restore has started, so
+     * call this beforehand to check the backup. Sirannon fetches every piece in
+     * order, computes a SHA-256 over the bytes as they arrive, and compares that
+     * digest and the byte count with the record. Sirannon keeps one piece in
+     * memory at a time, so checking a large full copy needs no local disk.
+     *
+     * This method throws `BACKUP_DESTINATION_ERROR` when a piece is missing, or
+     * when the byte count or the digest differs from the record.
+     *
+     * @param name - The name that the backup is stored under, as each entry from {@link DatabaseBackups.backupChain} gives it.
+     * @returns The number of pieces read, their total size in bytes, and the digest when the backup recorded one.
+     */
+    verifyBackup(name: string): Promise<BackupVerifyResult>;
+    /**
+     * Returns where this database's backups are stored.
+     *
+     * Pass the destination, chain name, and deadline from the result to
+     * `restoreBackup` to rebuild this database from its backups at a path that
+     * you name.
+     *
+     * @returns The destination, the name that the chains are listed under, and the directory where Sirannon stages captures.
+     */
+    backupLocation(): BackupChainLocation;
+    /**
+     * Returns the full copy and the change pieces that a restore to a given
+     * moment would apply.
+     *
+     * The plan also includes the moment that the restored database would reflect,
+     * which is the capture time of its last piece. Each piece contains every write
+     * from one capture interval, so a restore stops at a piece boundary, which
+     * can fall before the millisecond that you name.
+     *
+     * @param moment - The moment to restore to, in epoch milliseconds.
+     * @returns The full copy, the change pieces to apply in order, and the moment that the result reflects.
+     */
+    backupRestorePlan(moment: number): Promise<BackupRestorePlan>;
+    /**
+     * Returns the backup records that no restore needs any longer, so that you
+     * can delete them from the destination yourself.
+     *
+     * When you pass the earliest moment that a restore must still reach, the list
+     * also includes every chain whose full copy finished before the full copy
+     * that a restore to that moment would start from.
+     *
+     * @param options - The earliest moment that a restore must still reach.
+     * @returns The records that you can delete, oldest chain first.
+     */
+    backupPiecesSafeToDelete(options?: BackupSafeToDeleteOptions): Promise<BackupChainRecord[]>;
+}
+
+/**
+ * An open SQLite database, with methods for reads, writes, transactions, migrations, change subscriptions, and live queries.
+ *
+ * Open one through {@link Sirannon.open}.
+ *
+ * @public
+ */
+declare class Database extends DatabaseBackups {
+    /** @internal */
+    static create(id: string, path: string, driver: SQLiteDriver, options?: DatabaseOptions, internals?: DatabaseInternals): Promise<Database>;
+    /** @internal */
+    applyChanges(batch: ReplicationBatch, resolver?: ConflictResolver | ((table: string) => ConflictResolver)): Promise<ApplyResult>;
+    /**
+     * Returns the device-sync port for this database, which a `SyncController`
+     * calls to apply pulled changes, read unpushed local changes, and store its
+     * push and pull cursors.
+     *
+     * @returns The port, which you can also pass to `downloadDatabaseSnapshot`.
+     */
+    deviceSync(): DeviceSyncPort;
+    /**
+     * Executes a read and returns every row.
+     *
+     * @param sql - The statement to execute.
+     * @param params - The values to bind to the statement, named or positional.
+     * @param options - The read concern for this statement.
+     * @returns The rows that the statement returns.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    /** @internal */
+    queryForWire(sql: string, params?: Params, options?: QueryOptions): Promise<unknown[]>;
+    /**
+     * Executes a read and returns its first row.
+     *
+     * @param sql - The statement to execute.
+     * @param params - The values to bind to the statement, named or positional.
+     * @param options - The read concern for this statement.
+     * @returns The first row, or undefined when the statement returns none.
+     */
+    queryOne<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T | undefined>;
+    /**
+     * Executes one write statement.
+     *
+     * @param sql - The statement to execute.
+     * @param params - The values to bind to the statement, named or positional.
+     * @param options - The write concern for this statement.
+     * @returns The number of rows that the statement changed, and the row id of the last inserted row.
+     */
+    execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    /**
+     * Executes one statement once for each parameter set, inside a single transaction.
+     *
+     * @param sql - The statement to execute for each parameter set.
+     * @param paramsBatch - One parameter set for each execution.
+     * @param options - The write concern for the transaction.
+     * @returns One result per parameter set, in order.
+     */
+    executeBatch(sql: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    /**
+     * Imports many rows at a relaxed synchronous level, then restores the level that you configured.
+     *
+     * Use this for a load that you can re-run from scratch, and use
+     * {@link Database.executeBatch} where the rows need full durability. Sirannon
+     * holds the writer lock for the whole load and commits every row in one
+     * transaction. Whether the load succeeds or fails, Sirannon restores the
+     * configured level before this method resolves. The result contains totals
+     * for the whole load, so that a large load keeps no per-row results in memory.
+     *
+     * Like {@link Database.execute}, this writes to the local database only. A
+     * server whose execution target has no `bulkLoad` method, such as the
+     * replication engine, rejects bulk loads with `BULK_LOAD_UNSUPPORTED`.
+     *
+     * @param sql - The statement to execute for each parameter set.
+     * @param paramsBatch - One parameter set per row.
+     * @param options - The synchronous level during the load, and whether the load ends with a checkpoint.
+     * @returns The number of parameter sets that the load applied, and the number of rows that changed.
+     */
+    bulkLoad(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+    /**
+     * Executes a fixed list of statements in one transaction, which Sirannon can commit together with other callers' writes.
+     *
+     * When every statement is an INSERT, UPDATE, DELETE, or REPLACE, Sirannon
+     * groups the transaction with other writes into one commit, and otherwise it
+     * executes the transaction on its own. This method takes the statements up
+     * front, because a group commit that waited on a caller's callback would delay
+     * every other transaction in the group.
+     *
+     * @param statements - The statements to execute, in order, each with its own parameters.
+     * @returns One result per statement, in order.
+     */
+    executeTransaction(statements: readonly {
+        sql: string;
+        params?: Params;
+    }[]): Promise<ExecuteResult[]>;
+    /**
+     * Calls a function inside one transaction, and commits when the function returns or rolls back when it throws.
+     *
+     * @param fn - The function to call with the transaction, which executes its statements through it.
+     * @returns The value that the function returns.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Starts recording changes to a table, so that subscribers and replication receive them.
+     *
+     * @param table - The name of the table to watch.
+     */
+    watch(table: string): Promise<void>;
+    /**
+     * Stops recording changes to a table.
+     *
+     * @param table - The name of the table to stop watching.
+     */
+    unwatch(table: string): Promise<void>;
+    /**
+     * Executes a change-log maintenance write, such as pruning, on the shared
+     * writer connection under the writer lock, so that it queues behind
+     * application writes and never contends with them for SQLite's write lock,
+     * which would block the event loop for the `busy_timeout`.
+     *
+     * @internal
+     */
+    runCdcMaintenance(op: (writer: SQLiteConnection) => Promise<unknown>): Promise<void>;
+    /** @internal */
+    ensureChangeStamping(): Promise<void>;
+    /**
+     * Starts building a change subscription on a watched table.
+     *
+     * @param table - The name of the watched table.
+     * @returns A builder that you narrow with a filter and then subscribe to.
+     */
+    on(table: string): SubscriptionBuilder;
+    /**
+     * Opens a live query that keeps the rows of a single-table SELECT current as that table changes, and watches the table first.
+     *
+     * @param sql - The SELECT statement to keep current.
+     * @param params - The values to bind to the statement, named or positional.
+     * @param options - The re-read jitter, the transaction size above which the query re-reads, and the reporter for listener failures.
+     * @returns The live query, holding its first rows and subscribed to changes.
+     */
+    live<T = Record<string, unknown>>(sql: string, params?: Params, options?: LiveQueryOptions): Promise<LiveQuery<T>>;
+    /**
+     * Applies every migration that this database has yet to apply, in ascending version order.
+     *
+     * @param migrations - The full set of migrations for this database.
+     * @returns The migrations that this call applied, and the number that the database had already applied.
+     */
+    migrate(migrations: Migration[]): Promise<MigrationResult>;
+    /**
+     * Lists the migrations that this database has applied.
+     *
+     * @returns One entry per applied migration, with its version, name, and checksum.
+     */
+    appliedMigrations(): Promise<AppliedMigrationRow[]>;
+    /**
+     * Reverts applied migrations, newest first.
+     *
+     * @param migrations - The full set of migrations, from which the runner takes each down statement.
+     * @param version - The version to roll back to, which stays applied with every version below it; when you omit it, the runner reverts only the newest migration.
+     * @returns The migrations that this call reverted.
+     */
+    rollback(migrations: Migration[], version?: number): Promise<RollbackResult>;
+    /**
+     * Loads a compiled SQLite extension into every connection of this database.
+     *
+     * @param extensionPath - The path to the extension, which the driver resolves to an absolute path.
+     */
+    loadExtension(extensionPath: string): Promise<void>;
+    /**
+     * Registers a hook that Sirannon calls before each statement on this database; throw from the hook to reject the statement.
+     *
+     * @param hook - The hook, which Sirannon calls with the statement, its parameters, and its read or write concern.
+     * @returns A function that removes the hook.
+     */
+    onBeforeQuery(hook: BeforeQueryHook): HookDispose;
+    /**
+     * Registers a hook that Sirannon calls after each statement on this database.
+     *
+     * @param hook - The hook, which Sirannon calls with the statement and its duration.
+     * @returns A function that removes the hook.
+     */
+    onAfterQuery(hook: AfterQueryHook): HookDispose;
+}
+
+export { ConnectionPool as C, Database as D, HookRegistry as H, MetricsCollector as M, type PushHookContext as P, type SnapshotHookContext as S, type HookDispose as a, type ConnectionPoolOptions as b, DatabaseBackups as c, DatabaseLifecycle as d, type HookEvent as e, type HookEventContextMap as f, type HookHandler as g, type SubscribeHookContext as h, execute as i, executeBatch as j, queryOne as k, type DeviceSyncPort as l, HLC as m, query as q };