browser-sqlite 1.0.0-rc.3 → 1.0.0-rc.4

package/dist/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The prefixed logger the `debug` option turns on.
+ *
+ * Lifecycle events only — worker created, ready, open-error, crash, restart,
+ * worker loss, close, skipped sweep. A line per query would be illegible under
+ * real load and would put user values on the console; query throughput belongs
+ * in `db.debug`, not here.
+ */
+export type Logger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+    /**
+     * Always writes through the sink regardless of the `enabled` flag.
+     * Use for events that must be visible even when debug logging is off —
+     * permanent pool shrinkage being the primary case.
+     */
+    always: {
+        warn: (message: string) => void;
+    };
+};
+type Sink = Pick<Console, 'debug' | 'warn' | 'error'>;
+export declare const createLogger: (prefix: string, enabled: boolean, sink?: Sink) => Logger;
+export {};

package/dist/pool.d.ts

@@ -0,0 +1,98 @@
+import { SQLiteError } from './errors';
+import type { Logger } from './logger';
+import type { SQLiteBuild, SQLiteVFS, WasmLocation } from './types';
+/**
+ * Query execution options forwarded to a pool worker.
+ */
+export type PoolWorkerQueryOptions = {
+    chunkSize?: number | undefined;
+    credits?: number | undefined;
+    /**
+     * When true, the query's completion does not call `deps.onServed`. Set for
+     * the commit-propagation barrier: it is a synthetic probe, not user work, and
+     * must not reset the supervisor's restart counter.
+     * `createQueryDebugState` is intentionally NOT suppressed: barrier statements
+     * still appear in the debug request tree, and a browser test counts them there
+     * to prove the barrier stays conditional.
+     */
+    noServed?: boolean;
+};
+/**
+ * A Worker extended with pool-specific properties.
+ *
+ * Note: no `available` field — availability lives in the Scheduler, not on
+ * the worker itself. This makes it impossible to republish a borrowed worker
+ * from outside the scheduler (the root cause of B1).
+ */
+export type PoolWorker = Worker & {
+    index: number;
+    /** Lifecycle label for the debug surface. Replaces the SAB status byte. */
+    status: string;
+    /**
+     * The commit epoch this connection has absorbed. Starts at -1: a worker
+     * opens the file — and reads page 1 — BEFORE it enters the pool, and a
+     * commit can land in between. At poolSize 2 that is the nominal startup
+     * ordering, not a rare race, so a new worker is always treated as behind and
+     * pays exactly one barrier statement in its lifetime.
+     */
+    seen: number;
+    /** The epoch captured when the current lease was granted. */
+    epochTarget: number;
+    query: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: PoolWorkerQueryOptions) => AsyncGenerator<T[] | number>;
+    /**
+     * Ask the worker to stop. Also settles a `next()` already in flight, which
+     * is what lets the consumer's queued `return()` reach the generator's
+     * finally instead of waiting behind a chunk that may be minutes away.
+     */
+    interrupt: () => void;
+    /** Resolves when no query is in flight on this worker. */
+    quiesce: () => Promise<void>;
+    /** Posts `close`, awaits the `closed` reply, then the caller must terminate. */
+    close: () => Promise<void>;
+};
+/**
+ * Returns a SQLiteError('BUSY', …) when data carries a lock-conflict result
+ * code (5 or 6), else undefined. Shared by both the query-error and
+ * open-error paths so the BUSY_CODES decision lives in exactly one place.
+ */
+export declare const busyFromCode: (data: {
+    message: string;
+    cause?: unknown;
+    sqliteCode?: number;
+}) => SQLiteError | undefined;
+/**
+ * The single `new Worker(new URL(…))` expression in this package.
+ *
+ * It must stay one literal, in one place: bundlers find the worker by static
+ * analysis of exactly this shape, and a second copy would have them emit a
+ * second, untransformed worker bundle. `pool.ts:191` records what that cost
+ * when the expression was written a second time for an error message.
+ */
+export declare const spawnWorker: (name: string) => Worker;
+/**
+ * Creates a new pool worker and registers it in the pool array.
+ * Sets up message routing via callId for query responses.
+ *
+ * Moved verbatim from `createWorker` in client.ts, with three changes:
+ *  1. Closure variables become explicit `deps` parameters.
+ *  2. Both `available` assignments are deleted (availability lives in the Scheduler).
+ *  3. `worker.available = false/true` in the `query` generator are deleted.
+ */
+export declare const createPoolWorker: (deps: {
+    index: number;
+    pool: (PoolWorker | undefined)[];
+    clientPrefix: string;
+    file: string;
+    vfs: SQLiteVFS;
+    build: SQLiteBuild;
+    /** Already resolved and absolute; relayed to the worker, never read here. */
+    wasm?: WasmLocation | undefined;
+    pragmas?: Record<string, string> | undefined;
+    statementCacheSize?: number | undefined;
+    onDeath?: (index: number, error: SQLiteError) => void;
+    onServed?: (index: number) => void;
+    drainTimeout: number;
+    createWorkerDebugState?: ((index: number, name: string) => any) | undefined;
+    createQueryDebugState?: ((index: number, sql: string, params?: unknown[]) => any) | undefined;
+    logger: Logger;
+}) => Promise<PoolWorker>;

package/dist/queries.d.ts

@@ -0,0 +1,36 @@
+import type { OptionsWithSignal, SQLiteChunkOptions } from './api';
+import type { PoolWorker } from './pool';
+/**
+ * Wires an AbortSignal into a promise that rejects the instant the signal
+ * fires, and returns a teardown that removes the listener. The rejection sink
+ * (`aborted?.catch`) suppresses the unhandled-rejection when the query ends
+ * normally and nobody is racing the promise any more.
+ *
+ * This is the only place in the module that reads an AbortSignal; both
+ * `chunk()` and `writeWorker()` delegate here.
+ */
+export declare const makeAbortRace: (signal: AbortSignal | undefined) => {
+    aborted: Promise<never> | undefined;
+    teardown: () => void;
+};
+/**
+ * The single query primitive. Every other read path is a thin derivation, and
+ * abort is implemented here exactly once.
+ */
+export declare const chunk: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions & {
+    credits?: number;
+}) => AsyncGenerator<T[]>;
+export declare const streamRows: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions) => AsyncGenerator<T>;
+export declare const readWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: SQLiteChunkOptions) => Promise<T[]>;
+/**
+ * First row, then stop. This BREAKS rather than aborting: a break triggers the
+ * generator's return path, which runs chunk()'s finally and the transport's
+ * stop-and-drain — the same worker-stop routine, reached without an exception.
+ * That is why there is no internal AbortController here and no need to tell an
+ * internal abort from the caller's.
+ */
+export declare const firstWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<T | undefined>;
+export declare const writeWorker: <T extends Record<string, unknown> = Record<string, unknown>>(worker: PoolWorker, sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<{
+    result: T[];
+    affected: number;
+}>;

package/dist/scheduler.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure worker scheduling: availability, wait queues, writer designation.
+ *
+ * This module is deliberately free of `Worker` and DOM imports so
+ * it can be exercised by fast Node tests. B1 survived for months because the
+ * scheduler was only reachable through slow browser tests.
+ */
+import type { CreateSQLiteClientOptions } from './client';
+/**
+ * A borrowed worker. `release()` is the only way back into the pool and is
+ * idempotent — a second call is a no-op, not an error.
+ */
+export type Lease<W> = {
+    readonly worker: W;
+    release: () => void;
+};
+/**
+ * Decides whether a worker index may hold the write designation. The default
+ * accepts every index, so production behaviour is exactly what it was.
+ */
+export type WriterPolicy = (index: number) => boolean;
+/**
+ * TEST-ONLY, UNSUPPORTED, removable without notice.
+ *
+ * The barrier's browser test needs the failing configuration — writer not on
+ * the worker that serves the read — to be deterministic; at startup chance it
+ * occurs ~3 runs in 10. This type is declared here, and NOT in `client.ts`,
+ * because `src/index.ts` re-exports only `./client` and `./errors`: keeping it
+ * out of that path keeps it out of the published `.d.ts` and out of every
+ * consumer's autocompletion. `CreateSQLiteClientOptions` is pulled in with
+ * `import type`, which is erased at build time and creates no runtime cycle.
+ *
+ * A predicate that refuses every index leaves writes queued forever — use it
+ * with `poolSize >= 2`.
+ */
+export type InternalSQLiteClientOptions = CreateSQLiteClientOptions & {
+    __unsafeTestWriterPolicy?: WriterPolicy;
+};
+export type Scheduler<W> = {
+    add: (worker: W) => void;
+    /**
+     * Leases a worker, queueing when none is free.
+     *
+     * `signal` aborts the WAIT, and only the wait: it rejects with
+     * `signal.reason` while the request is still queued, and is ignored once a
+     * lease has been granted — from that point the caller owns the worker and
+     * owes a `release()`. Without it an abort could not land at all while the
+     * pool had nothing to lend, which is the state a VFS rotating one exclusive
+     * OPFS handle can stay in indefinitely.
+     */
+    acquire: (kind: 'read' | 'write', signal?: AbortSignal) => Promise<Lease<W>>;
+    /**
+     * Takes a worker out of the pool for good. A lease already outstanding on
+     * that index becomes inert: its `release()` neither hands the worker back nor
+     * counts towards `shutdown()`'s wait.
+     */
+    remove: (index: number) => void;
+    /**
+     * Closes the front door. Queued waiters reject with `reason`, later
+     * acquisitions reject the same way, and the returned promise settles when the
+     * last outstanding lease has come back.
+     */
+    shutdown: (reason: Error) => Promise<void>;
+    /**
+     * Read-only counters for the debug subsystem. The scheduler stays pure: it
+     * exposes numbers and knows nothing about debug (spec §3.2).
+     */
+    stats: () => {
+        read: number;
+        write: number;
+        available: number;
+        leased: number;
+        /**
+         * Callers suspended on the readiness gate. They are in NEITHER wait queue —
+         * the gate is awaited before `takeAvailable` is ever reached — so `read`
+         * and `write` cannot see them, and without this the debug surface reports
+         * an idle pool for the whole startup window.
+         *
+         * Waiting for the pool to *exist* is a different wait from waiting for a
+         * free worker, which is why this is its own counter and not folded in.
+         */
+        gated: number;
+    };
+    /**
+     * Removes a slot from the settled-set so that its next `add()` or `remove()`
+     * call counts again toward opening the readiness gate. Only effective while
+     * the gate is still closed; a no-op once the gate has opened.
+     *
+     * Used by the startup retry round: the client re-arms the failed slots so
+     * the gate stays closed until the retry slots have settled.
+     */
+    rearmSlot: (index: number) => void;
+};
+/**
+ * Creates a scheduler over workers identified by a numeric `index`.
+ *
+ * @param opts.onIdle - Called when a released worker returns to the available
+ *   set with nothing queued behind it. The scheduler itself knows nothing about
+ *   worker state.
+ */
+export declare const createScheduler: <W extends {
+    index: number;
+}>(opts?: {
+    onIdle?: (worker: W) => void;
+    canDesignateWriter?: WriterPolicy;
+    /**
+     * Total number of worker slots the pool will spawn. Once every slot has
+     * settled (via `add` when it becomes ready, or via `remove` when it dies or
+     * fails to open), a one-shot gate is lifted and `acquire()` may proceed.
+     * Omit or pass 0 for an immediately-open gate (tests and single-shot use).
+     */
+    poolSize?: number;
+    /**
+     * Called exactly once when every slot in [0, poolSize) has settled for the
+     * first time. Fires before the gate opens so the callback can call
+     * `rearmSlot()` to extend the wait for a retry round.
+     *
+     * `openedCount` — slots that settled via `add()` (became ready).
+     * `failedIndices` — slots that settled via `remove()` (died / timed out).
+     */
+    onFirstSettle?: (result: {
+        openedCount: number;
+        failedIndices: number[];
+    }) => void;
+    /**
+     * Called when the readiness gate resolves (opens). Not called when the gate
+     * is rejected via `shutdown()`. Use this to clear any startup-pending flag
+     * after the retry round (if any) has fully settled.
+     */
+    onGateOpen?: () => void;
+}) => Scheduler<W>;

package/dist/supervisor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure restart policy for worker slots.
+ *
+ * Deliberately free of `Worker` and DOM imports so Node tests can
+ * drive it in milliseconds — the same reason `scheduler.ts` is pure. B1 lived
+ * for months because the only way to reach the pool's decisions was a browser.
+ *
+ * The caller reports facts; this module returns a decision and never acts.
+ */
+export type SupervisorDecision = 'restart' | 'lost' | 'fail-client';
+export type Supervisor = {
+    report: (index: number, event: 'spawned' | 'ready' | 'served' | 'died' | 'lost') => SupervisorDecision | undefined;
+};
+export declare const createSupervisor: (options: {
+    size: number;
+    maxWorkerRestarts?: number | undefined;
+}) => Supervisor;

package/dist/transaction.d.ts

@@ -0,0 +1,38 @@
+import type { SQLiteQueryAPI, SQLiteTransactionDB, SQLiteTransactionOptions } from './api';
+import type { ReadFn, TransactionFn, WriteFn } from './bulk';
+import { SQLiteError } from './errors';
+import type { PoolWorker } from './pool';
+import type { Scheduler } from './scheduler';
+/**
+ * Returns the `transaction()` method for a SQLiteDB instance.
+ *
+ * The returned function acquires exactly one lease for the full lifetime of
+ * the transaction. All SQLiteTransactionDB methods call worker-bound derivations
+ * directly — never the public API — so no secondary lease acquisition can
+ * occur during the callback.
+ */
+export declare const createTransaction: (deps: {
+    scheduler: Scheduler<PoolWorker>;
+    afterWrite: (worker: PoolWorker) => void;
+    /**
+     * Called when a connection may still hold an open transaction. The worker
+     * is lost rather than repaired: a "dirty worker" state is one more
+     * state the barrier would have to reason about, while a respawned
+     * connection is transaction-free by construction.
+     */
+    onPoisoned: (index: number, error: SQLiteError) => void;
+    /**
+     * The client's bulk factory. Called per transaction with the transaction's
+     * own read/write and a pass-through `transaction`, so output()'s swap runs
+     * on the caller's transaction instead of opening a BEGIN SQLite does not
+     * allow.
+     */
+    bulkFor: (target: {
+        read: ReadFn;
+        write: WriteFn;
+        transaction: TransactionFn;
+    }) => {
+        bulkWrite: SQLiteQueryAPI['bulkWrite'];
+        output: SQLiteQueryAPI['output'];
+    };
+}) => <T = void>(callback: (db: SQLiteTransactionDB) => Promise<T>, options?: SQLiteTransactionOptions) => Promise<T>;