@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/core/writer-worker.mjs

@@ -1,7 +1,7 @@
-import { executeGroup } from '../chunk-JZGINXTN.mjs';
-import '../chunk-D7LAYTKN.mjs';
+import { executeGroup } from '../chunk-HCCGEIZ2.mjs';
+import '../chunk-7R4ER4FB.mjs';
 import { WORKER_CANCELLED_CODE, serializeError } from '../chunk-4ISB7XMA.mjs';
-import { SirannonError } from '../chunk-UC3SCMIN.mjs';
+import { SirannonError } from '../chunk-PBRXXISQ.mjs';
 import { parentPort } from 'worker_threads';
 
 var STATEMENT_CACHE_CAPACITY = 128;

package/dist/database-B5Qv1-cU.d.ts

@@ -0,0 +1,380 @@
+import { Q as QueryHookContext, g as ConnectionHookContext, h as BeforeSubscribeHook, H as HookConfig, i as MetricsConfig, j as QueryMetrics, k as ConnectionMetrics, l as CDCMetrics, a as SQLiteDriver, D as DatabaseOptions, T as Transaction, e as SQLiteConnection, M as Migration, m as MigrationResult, R as RollbackResult, f as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-rVZKnKN-.js';
+import { c as ReplicationChange, C as ConflictResolver, A as ApplyResult, R as ReplicationBatch } from './types-CjhxcjhA.js';
+import { C as ChangeEvent, P as Params, Q as QueryOptions, E as ExecuteResult, S as SubscriptionBuilder } from './query-types-DL3LtPvY.js';
+import { A as AppliedMigrationRow, b as BulkLoadOptions, a as BulkLoadResult } from './server-options-Dab_Jvd_.js';
+import { L as LiveQueryOptions, a as LiveQuery } from './types-BCejqzNA.js';
+
+/**
+ * Names of the lifecycle points a hook can attach to.
+ *
+ * @internal
+ */
+type HookEvent = 'beforeQuery' | 'afterQuery' | 'beforeConnect' | 'databaseOpen' | 'databaseClose' | 'beforeSubscribe';
+/**
+ * Context a subscribe hook receives.
+ *
+ * @internal
+ */
+type SubscribeHookContext = Parameters<BeforeSubscribeHook>[0];
+/**
+ * Maps each lifecycle point to the context its hooks receive.
+ *
+ * @internal
+ */
+interface HookEventContextMap {
+    beforeQuery: QueryHookContext;
+    afterQuery: QueryHookContext & {
+        durationMs: number;
+    };
+    beforeConnect: ConnectionHookContext;
+    databaseOpen: ConnectionHookContext;
+    databaseClose: ConnectionHookContext;
+    beforeSubscribe: SubscribeHookContext;
+}
+/**
+ * Function a hook registration stores for one lifecycle point.
+ *
+ * @internal
+ */
+type HookHandler<E extends HookEvent> = (ctx: HookEventContextMap[E]) => void | Promise<void>;
+/**
+ * Removes a registered hook when called.
+ *
+ * @internal
+ */
+type HookDispose = () => void;
+
+/**
+ * Holds the lifecycle hooks a database or registry has registered and invokes them in order.
+ *
+ * @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;
+    has(event: HookEvent): boolean;
+    count(event: HookEvent): number;
+    clear(event?: HookEvent): void;
+    private addHook;
+    private loadConfig;
+}
+
+/**
+ * Times queries and reports connection and change-capture activity to the configured metrics callbacks.
+ *
+ * @internal
+ */
+declare class MetricsCollector {
+    private config;
+    constructor(config?: MetricsConfig);
+    trackQuery<T>(fn: () => Promise<T>, context: Omit<QueryMetrics, 'durationMs' | 'error'>): Promise<T>;
+    trackConnection(metrics: ConnectionMetrics): void;
+    trackCDCEvent(metrics: CDCMetrics): void;
+    get active(): boolean;
+}
+
+interface StagedRecovery {
+    resumeSeq: bigint | null;
+    appliedSeq: bigint | null;
+    /**
+     * The failure that stopped the recovery apply, or null. The staged rows
+     * are untouched by the failure and the resume watermark still covers
+     * them, so the caller opens the subscription anyway: a schema-gate refusal
+     * there is what tells a device it must migrate before this apply can
+     * succeed. The caller must then retry the recovery, because the resume
+     * watermark is past the transaction this apply left unapplied, so the
+     * server sends nothing that would prompt another try.
+     */
+    applyError: unknown | null;
+}
+
+/**
+ * How far a device has pulled from its server, and which sequence space that
+ * position belongs to.
+ *
+ * @public
+ */
+interface DeviceSyncPullState {
+    /** Highest server change-log position this device has applied. */
+    seq: bigint;
+    /** Sequence space that position came from. */
+    epoch: string | undefined;
+}
+/**
+ * What a device's local database offers the sync loop: it stages and applies
+ * what the server sends, reads what the device still owes the server, and
+ * keeps both cursors. Take one from {@link Database.deviceSync}.
+ *
+ * @public
+ */
+interface DeviceSyncPort {
+    /** Returns the identifier this device stamps its own changes with. */
+    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 durably without applying them, so an interrupted device resumes from disk. */
+    stagePulledChanges(events: readonly ChangeEvent[]): Promise<bigint | null>;
+    /** Applies whatever is staged and returns the position reached. */
+    applyStagedPull(resolver?: ConflictResolver | ((table: string) => ConflictResolver), onChange?: (event: ChangeEvent) => void): Promise<bigint | null>;
+    /** Applies what a previous run left staged, and reports the failure that stopped it. */
+    recoverStagedPull(resolver?: ConflictResolver | ((table: string) => ConflictResolver), onChange?: (event: ChangeEvent) => void): Promise<StagedRecovery>;
+    /** Reads the next run of local changes the device still owes the server. */
+    readOutboxBatch(afterSeq: bigint, limit: number): Promise<ReplicationBatch | null>;
+    /** Counts the local changes the device still owes the server. */
+    countOutboxPending(afterSeq: bigint): Promise<number>;
+    /** Reads how far the device has pushed. */
+    getPushCursor(): Promise<bigint>;
+    /** Records how far the device has pushed. */
+    setPushCursor(seq: bigint): Promise<void>;
+    /** Reads how far the device has pulled, or null before it has pulled anything. */
+    getPullState(): Promise<DeviceSyncPullState | null>;
+    /** Reports whether the server has told this device to download a fresh snapshot. */
+    getResyncRequired(): Promise<boolean>;
+    /** Records whether the device must download a fresh snapshot. */
+    setResyncRequired(required: boolean): Promise<void>;
+    /** Records how far the device has pulled, and the sequence space it came from. */
+    setPullState(seq: bigint, epoch?: string): Promise<void>;
+    /** Keeps changes above a position out of pruning until the server has accepted them. */
+    protectUnpushedChanges(pushedSeq: bigint): void;
+    /** Reports whether a snapshot download was interrupted and still has to finish. */
+    snapshotLoadPending(): Promise<boolean>;
+    /** Clears the named tables and opens the database for a snapshot download. */
+    beginSnapshotLoad(tables: readonly string[]): Promise<void>;
+    /** Applies the schema statements a snapshot carries. */
+    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>;
+    /** Closes a completed snapshot download and reopens the database for normal use. */
+    endSnapshotLoad(tables: readonly string[]): Promise<void>;
+    /** Abandons a snapshot download, leaving the database marked as needing another. */
+    abortSnapshotLoad(): Promise<void>;
+}
+
+interface DatabaseInternals {
+    parentHooks?: HookRegistry;
+    metrics?: MetricsCollector;
+}
+
+/**
+ * One open SQLite database, with its reads, writes, transactions, migrations, change subscriptions, and live queries.
+ *
+ * Open one through {@link Sirannon.open} rather than constructing it.
+ *
+ * @public
+ */
+declare class Database {
+    /** Identifier this database was opened under. */
+    readonly id: string;
+    /** File path of the SQLite database. */
+    readonly path: string;
+    /** Whether this database refuses writes. */
+    readonly readOnly: boolean;
+    private readonly runtime;
+    private readonly closeListeners;
+    private _closed;
+    private constructor();
+    /** @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 reads and advances
+     * the cursors a `SyncController` keeps against a server.
+     *
+     * @returns The port, which `downloadDatabaseSnapshot` also accepts.
+     */
+    deviceSync(): DeviceSyncPort;
+    /**
+     * Runs a read and returns every row.
+     *
+     * @param sql - The statement to run.
+     * @param params - Values bound to the statement, named or positional.
+     * @param options - Read concern for this statement.
+     * @returns The rows the statement produced.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    /** @internal */
+    queryForWire(sql: string, params?: Params, options?: QueryOptions): Promise<unknown[]>;
+    /**
+     * Runs a read and returns its first row.
+     *
+     * @param sql - The statement to run.
+     * @param params - Values bound to the statement, named or positional.
+     * @param options - Read concern for this statement.
+     * @returns The first row, or undefined when the statement produced none.
+     */
+    queryOne<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T | undefined>;
+    /**
+     * Runs one write.
+     *
+     * @param sql - The statement to run.
+     * @param params - Values bound to the statement, named or positional.
+     * @param options - Write concern for this statement.
+     * @returns How many rows changed, and the last inserted row id.
+     */
+    execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    /**
+     * Runs one statement over many parameter sets inside a single transaction.
+     *
+     * @param sql - The statement to run for each parameter set.
+     * @param paramsBatch - One parameter set per run.
+     * @param options - 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 with relaxed writer durability, then restores the configured level.
+     *
+     * Use this for a load you can re-run from scratch, because
+     * {@link Database.executeBatch} keeps full durability. The load holds the
+     * writer lock throughout and restores the configured level before this
+     * resolves, whether it succeeds or fails. One transaction covers the whole
+     * batch, and the rows are summed rather than returned one by one to bound
+     * memory on a large load. Like {@link Database.execute}, this writes only to
+     * the local database; under replication the server routes loads through the
+     * engine instead.
+     *
+     * @param sql - The statement to run for each parameter set.
+     * @param paramsBatch - One parameter set per row.
+     * @param options - Durability during the load, and whether it ends with a checkpoint.
+     * @returns How many rows the load applied and how many rows changed.
+     */
+    bulkLoad(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+    /**
+     * Runs a fixed list of statements in one transaction so that several callers can share one commit.
+     *
+     * This takes the statements up front rather than a callback, because a group
+     * cannot wait on an arbitrary caller-supplied callback without delaying every
+     * transaction beside it.
+     *
+     * @param statements - The statements to run, in order, each with its own parameters.
+     * @returns One result per statement, in order.
+     */
+    executeTransaction(statements: readonly {
+        sql: string;
+        params?: Params;
+    }[]): Promise<ExecuteResult[]>;
+    /**
+     * Runs a function inside one transaction, committing when it returns and rolling back when it throws.
+     *
+     * @param fn - Receives the transaction and runs statements on it.
+     * @returns Whatever the function returned.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Starts recording changes to a table so that subscribers and replication see them.
+     *
+     * @param table - Name of the table to watch.
+     */
+    watch(table: string): Promise<void>;
+    /**
+     * Stops recording changes to a table.
+     *
+     * @param table - Name of the table to stop watching.
+     */
+    unwatch(table: string): Promise<void>;
+    /**
+     * Runs a CDC maintenance write (change-log pruning) on the shared writer
+     * under the writer lock. Serialising it with application writes keeps it
+     * from becoming a second writer that contends for SQLite's single write
+     * lock and stalls the event loop on `busy_timeout`.
+     *
+     * @internal
+     */
+    runCdcMaintenance(op: (writer: SQLiteConnection) => Promise<unknown>): Promise<void>;
+    /** @internal */
+    ensureChangeStamping(): Promise<void>;
+    /**
+     * Begins a change subscription on a watched table.
+     *
+     * @param table - Name of the watched table.
+     * @returns A builder you narrow with a filter and then subscribe to.
+     */
+    on(table: string): SubscriptionBuilder;
+    /**
+     * Opens a live query that keeps a registered read's rows current as the tables behind it change.
+     *
+     * @param operation - Name of the registered read, or a reference built by {@link operationRef}.
+     * @param args - Arguments the operation takes.
+     * @param options - Re-read jitter and the transaction size above which the query re-reads.
+     * @returns The live query, already subscribed.
+     */
+    live<T = Record<string, unknown>>(sql: string, params?: Params, options?: LiveQueryOptions): Promise<LiveQuery<T>>;
+    /**
+     * Applies every migration this database has not yet applied, in ascending version order.
+     *
+     * @param migrations - The full set of migrations for this database.
+     * @returns Which migrations this call applied, and how many it skipped.
+     */
+    migrate(migrations: Migration[]): Promise<MigrationResult>;
+    /**
+     * Lists the migrations this database has applied.
+     *
+     * @returns One entry per applied migration, with its version, name, and checksum.
+     */
+    appliedMigrations(): Promise<AppliedMigrationRow[]>;
+    /**
+     * Undoes applied migrations, newest first.
+     *
+     * @param migrations - The full set of migrations so that the runner finds each down statement.
+     * @param version - Lowest version to keep. Without it, only the newest migration is undone.
+     * @returns Which migrations this call undid.
+     */
+    rollback(migrations: Migration[], version?: number): Promise<RollbackResult>;
+    /**
+     * Copies this database to a file while it stays open for reads and writes.
+     *
+     * @param destPath - Path the copy is written to.
+     */
+    backup(destPath: string): Promise<void>;
+    /**
+     * Starts repeating backups on a cron schedule, keeping a bounded number of files.
+     *
+     * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+     */
+    scheduleBackup(options: BackupScheduleOptions): void;
+    /**
+     * Loads a SQLite extension into this database.
+     *
+     * @param extensionPath - Path to the extension, which the driver resolves to an absolute path.
+     */
+    loadExtension(extensionPath: string): Promise<void>;
+    /**
+     * Registers a hook that runs before each statement on this database. Throw from it to refuse the statement.
+     *
+     * @param hook - Receives the statement, its parameters, and the concerns it carries.
+     */
+    onBeforeQuery(hook: BeforeQueryHook): void;
+    /**
+     * Registers a hook that runs after each statement on this database.
+     *
+     * @param hook - Receives the statement and how long it took.
+     */
+    onAfterQuery(hook: AfterQueryHook): void;
+    /** @internal */
+    addCloseListener(fn: () => void | Promise<void>): void;
+    /**
+     * Closes every connection this database holds and ends its subscriptions.
+     */
+    close(): Promise<void>;
+    /**
+     * Whether this database has been closed.
+     */
+    get closed(): boolean;
+    /**
+     * Number of read connections the pool holds.
+     */
+    get readerCount(): number;
+    private ensureWritable;
+    private ensureOpen;
+    private ensureNotClosed;
+}
+
+export { Database as D, type HookDispose as H, MetricsCollector as M, type SubscribeHookContext as S, type HookEvent as a, type HookEventContextMap as b, type HookHandler as c, HookRegistry as d, type DeviceSyncPort as e };

package/dist/driver/better-sqlite3.d.ts

@@ -1,8 +1,25 @@
-import { a as SQLiteDriver } from '../types-zhnRXrsb.js';
+import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
+/**
+ * @public
+ *
+ * Settings for the better-sqlite3 driver.
+ */
 interface BetterSqlite3Options {
+    /**
+     * Milliseconds a statement waits for the write lock before it fails.
+     */
     busyTimeout?: number;
 }
+/**
+ * @public
+ *
+ * Builds a driver on better-sqlite3, which is the fastest option on Node.
+ *
+ * @param driverOptions - How long a statement waits for the write lock.
+ * @returns The driver, ready to pass to a `Sirannon` registry.
+ */
 declare function betterSqlite3(driverOptions?: BetterSqlite3Options): SQLiteDriver;
 
 export { type BetterSqlite3Options, betterSqlite3 };

package/dist/driver/better-sqlite3.mjs

@@ -1,9 +1,9 @@
-import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, WriterWorker, createStatementCache, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-EBJXPQQO.mjs';
-import '../chunk-PIKHN33N.mjs';
-import { defineDriver } from '../chunk-FHWTZFI4.mjs';
+import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, WriterWorker, createStatementCache, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-UPKKSUPA.mjs';
+import '../chunk-VOYGMAU7.mjs';
+import { defineDriver } from '../chunk-BQFQ65OL.mjs';
 import '../chunk-4ISB7XMA.mjs';
-import { synchronousPragmaValue } from '../chunk-LFZ37BSX.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import { synchronousPragmaValue } from '../chunk-OUSWVNWT.mjs';
+import '../chunk-PBRXXISQ.mjs';
 
 // src/drivers/better-sqlite3/index.ts
 function createConnection(db) {

package/dist/driver/bun.d.ts

@@ -0,0 +1,28 @@
+import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
+
+/**
+ * @public
+ *
+ * Settings for the driver built on Bun's built-in SQLite.
+ */
+interface BunSqliteOptions {
+    /**
+     * Milliseconds a statement waits for the write lock before it fails as busy. Default: 5000.
+     */
+    busyTimeout?: number;
+}
+/**
+ * @public
+ *
+ * Builds a driver that runs SQLite through `bun:sqlite`, which is built into the Bun runtime.
+ *
+ * It reads every integer as a BigInt and narrows the safe ones back, so a
+ * value beyond `Number.MAX_SAFE_INTEGER` survives the round trip.
+ *
+ * @param driverOptions - How long a statement waits for the write lock.
+ * @returns The driver, ready to pass to a `Sirannon` registry running under Bun.
+ */
+declare function bunSqlite(driverOptions?: BunSqliteOptions): SQLiteDriver;
+
+export { type BunSqliteOptions, bunSqlite };

package/dist/driver/expo.d.ts

@@ -0,0 +1,17 @@
+import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
+
+/**
+ * @public
+ *
+ * Builds a driver that runs SQLite on a device through `expo-sqlite`.
+ *
+ * Expo opens one connection per database, so this driver reports no support
+ * for multiple connections and Sirannon serves every read and write over that
+ * single connection.
+ *
+ * @returns The driver, ready to pass to a `Sirannon` registry in a React Native app.
+ */
+declare function expoSqlite(): SQLiteDriver;
+
+export { expoSqlite };

package/dist/driver/node.d.ts

@@ -1,8 +1,25 @@
-import { a as SQLiteDriver } from '../types-zhnRXrsb.js';
+import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
+/**
+ * @public
+ *
+ * Settings for the driver built on Node's own SQLite module.
+ */
 interface NodeSqliteOptions {
+    /**
+     * Milliseconds a statement waits for the write lock before it fails.
+     */
     busyTimeout?: number;
 }
+/**
+ * @public
+ *
+ * Builds a driver on Node's own SQLite module, which needs no native dependency.
+ *
+ * @param driverOptions - How long a statement waits for the write lock.
+ * @returns The driver, ready to pass to a `Sirannon` registry.
+ */
 declare function nodeSqlite(driverOptions?: NodeSqliteOptions): SQLiteDriver;
 
 export { type NodeSqliteOptions, nodeSqlite };

package/dist/driver/node.mjs

@@ -1,9 +1,9 @@
-import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, createStatementCache, WriterWorker, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-EBJXPQQO.mjs';
-import '../chunk-PIKHN33N.mjs';
-import { defineDriver } from '../chunk-FHWTZFI4.mjs';
+import { nodeResolveExtensionPath, nodeBackupEngine, nodeWriterContext, createStatementCache, WriterWorker, narrowSafeBigInt, narrowRowIntegers, narrowRowsIntegers } from '../chunk-UPKKSUPA.mjs';
+import '../chunk-VOYGMAU7.mjs';
+import { defineDriver } from '../chunk-BQFQ65OL.mjs';
 import '../chunk-4ISB7XMA.mjs';
-import { synchronousPragmaValue } from '../chunk-LFZ37BSX.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import { synchronousPragmaValue } from '../chunk-OUSWVNWT.mjs';
+import '../chunk-PBRXXISQ.mjs';
 
 // src/drivers/node/index.ts
 function nodeSqlite(driverOptions) {

package/dist/driver/wa-sqlite.d.ts

@@ -1,8 +1,25 @@
-import { a as SQLiteDriver } from '../types-zhnRXrsb.js';
+import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
+/**
+ * @public
+ *
+ * Settings for the browser driver built on wa-sqlite.
+ */
 interface WaSqliteOptions {
+    /**
+     * Where the browser stores the database. Default: 'IDBBatchAtomicVFS'.
+     */
     vfs?: 'IDBBatchAtomicVFS' | 'AccessHandlePoolVFS';
 }
+/**
+ * @public
+ *
+ * Builds a driver that runs SQLite in the browser through WebAssembly.
+ *
+ * @param driverOptions - Where the browser stores the database.
+ * @returns The driver, ready to pass to a `Sirannon` registry.
+ */
 declare function waSqlite(driverOptions?: WaSqliteOptions): SQLiteDriver;
 
 export { type WaSqliteOptions, waSqlite };