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

package/dist/scheduler.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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;
+    /**
+     * TEST-ONLY, UNSUPPORTED. The byte bound has no falsifier without it: at a
+     * fixed default nothing in the suite can tell a working bound from one that
+     * never fires. Absent from the public options type on purpose.
+     */
+    __unsafeTestStatementCacheBytes?: number;
+};
+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;
+    /**
+     * Takes a slot out of the pool for good because its worker DECLINED to open:
+     * the environment caps the pool below its requested size (spec 2026-09-13).
+     * Unlike `remove()`, the slot settles the readiness gate as neither opened
+     * nor failed, so it never appears in `onFirstSettle`'s `failedIndices` and
+     * never enters the startup retry round.
+     */
+    retire: (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/sqlite-codes.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The result codes of SQLite 3.53.0, keyed without the `SQLITE_` prefix, in two
+ * tables that match `SQLiteError`'s two fields: test the family on `sqliteCode`
+ * against `SQLITE_CODES` (`CONSTRAINT`, `FULL`), the subtype on
+ * `sqliteExtendedCode` against `SQLITE_EXTENDED_CODES` (`CONSTRAINT_UNIQUE`).
+ * An extended code's low byte is its family (`(2067 & 0xff) === 19`), and its key
+ * begins with the family's key. What each one means:
+ * https://sqlite.org/rescode.html.
+ *
+ * Transcribed from `src/sqlite.h.in` — the source of `sqlite3.h` — at SQLite's
+ * tag `version-3.53.0`, checked 2026-09-14. That is the SQLite of the vendored
+ * wa-sqlite, v1.1.2 (its `package.json` still reads 1.1.1: upstream did not
+ * bump it): its source-id, read from the wasm, is `2026-04-09 11:41:38
+ * 4525003a53a7fc63ca75`, and the tag's `manifest.uuid` begins with the same
+ * hash. Not read from wa-sqlite's `sqlite-constants.js`, which has no
+ * `BUSY_*`, `LOCKED_*`, `CANTOPEN_*`, `CORRUPT_*` or `READONLY_*` codes;
+ * `tests/unit/sqlite-codes.test.ts` checks every name the two share.
+ * Re-transcribe when wa-sqlite moves to another SQLite.
+ *
+ * `SQLiteError.sqliteCode` is typed `SQLiteResultCode` (strict): since
+ * `sqliteCodeOf`, it is always a primary code of the bundled SQLite (D10).
+ * `sqliteExtendedCode` stays open (`SQLiteExtendedResultCode | (number & {})`):
+ * a wrong read must stay representable (D9).
+ */
+/** The 31 primary result codes — what `SQLiteError.sqliteCode` holds. */
+export declare const SQLITE_CODES: Readonly<{
+    readonly OK: 0;
+    readonly ERROR: 1;
+    readonly INTERNAL: 2;
+    readonly PERM: 3;
+    readonly ABORT: 4;
+    readonly BUSY: 5;
+    readonly LOCKED: 6;
+    readonly NOMEM: 7;
+    readonly READONLY: 8;
+    readonly INTERRUPT: 9;
+    readonly IOERR: 10;
+    readonly CORRUPT: 11;
+    readonly NOTFOUND: 12;
+    readonly FULL: 13;
+    readonly CANTOPEN: 14;
+    readonly PROTOCOL: 15;
+    readonly EMPTY: 16;
+    readonly SCHEMA: 17;
+    readonly TOOBIG: 18;
+    readonly CONSTRAINT: 19;
+    readonly MISMATCH: 20;
+    readonly MISUSE: 21;
+    readonly NOLFS: 22;
+    readonly AUTH: 23;
+    readonly FORMAT: 24;
+    readonly RANGE: 25;
+    readonly NOTADB: 26;
+    readonly NOTICE: 27;
+    readonly WARNING: 28;
+    readonly ROW: 100;
+    readonly DONE: 101;
+}>;
+/**
+ * The 82 extended result codes — what `SQLiteError.sqliteExtendedCode` holds
+ * when SQLite reports a subtype. No primary code is repeated here.
+ */
+export declare const SQLITE_EXTENDED_CODES: Readonly<{
+    readonly ERROR_MISSING_COLLSEQ: 257;
+    readonly ERROR_RETRY: 513;
+    readonly ERROR_SNAPSHOT: 769;
+    readonly ERROR_RESERVESIZE: 1025;
+    readonly ERROR_KEY: 1281;
+    readonly ERROR_UNABLE: 1537;
+    readonly IOERR_READ: 266;
+    readonly IOERR_SHORT_READ: 522;
+    readonly IOERR_WRITE: 778;
+    readonly IOERR_FSYNC: 1034;
+    readonly IOERR_DIR_FSYNC: 1290;
+    readonly IOERR_TRUNCATE: 1546;
+    readonly IOERR_FSTAT: 1802;
+    readonly IOERR_UNLOCK: 2058;
+    readonly IOERR_RDLOCK: 2314;
+    readonly IOERR_DELETE: 2570;
+    readonly IOERR_BLOCKED: 2826;
+    readonly IOERR_NOMEM: 3082;
+    readonly IOERR_ACCESS: 3338;
+    readonly IOERR_CHECKRESERVEDLOCK: 3594;
+    readonly IOERR_LOCK: 3850;
+    readonly IOERR_CLOSE: 4106;
+    readonly IOERR_DIR_CLOSE: 4362;
+    readonly IOERR_SHMOPEN: 4618;
+    readonly IOERR_SHMSIZE: 4874;
+    readonly IOERR_SHMLOCK: 5130;
+    readonly IOERR_SHMMAP: 5386;
+    readonly IOERR_SEEK: 5642;
+    readonly IOERR_DELETE_NOENT: 5898;
+    readonly IOERR_MMAP: 6154;
+    readonly IOERR_GETTEMPPATH: 6410;
+    readonly IOERR_CONVPATH: 6666;
+    readonly IOERR_VNODE: 6922;
+    readonly IOERR_AUTH: 7178;
+    readonly IOERR_BEGIN_ATOMIC: 7434;
+    readonly IOERR_COMMIT_ATOMIC: 7690;
+    readonly IOERR_ROLLBACK_ATOMIC: 7946;
+    readonly IOERR_DATA: 8202;
+    readonly IOERR_CORRUPTFS: 8458;
+    readonly IOERR_IN_PAGE: 8714;
+    readonly IOERR_BADKEY: 8970;
+    readonly IOERR_CODEC: 9226;
+    readonly LOCKED_SHAREDCACHE: 262;
+    readonly LOCKED_VTAB: 518;
+    readonly BUSY_RECOVERY: 261;
+    readonly BUSY_SNAPSHOT: 517;
+    readonly BUSY_TIMEOUT: 773;
+    readonly CANTOPEN_NOTEMPDIR: 270;
+    readonly CANTOPEN_ISDIR: 526;
+    readonly CANTOPEN_FULLPATH: 782;
+    readonly CANTOPEN_CONVPATH: 1038;
+    readonly CANTOPEN_DIRTYWAL: 1294;
+    readonly CANTOPEN_SYMLINK: 1550;
+    readonly CORRUPT_VTAB: 267;
+    readonly CORRUPT_SEQUENCE: 523;
+    readonly CORRUPT_INDEX: 779;
+    readonly READONLY_RECOVERY: 264;
+    readonly READONLY_CANTLOCK: 520;
+    readonly READONLY_ROLLBACK: 776;
+    readonly READONLY_DBMOVED: 1032;
+    readonly READONLY_CANTINIT: 1288;
+    readonly READONLY_DIRECTORY: 1544;
+    readonly ABORT_ROLLBACK: 516;
+    readonly CONSTRAINT_CHECK: 275;
+    readonly CONSTRAINT_COMMITHOOK: 531;
+    readonly CONSTRAINT_FOREIGNKEY: 787;
+    readonly CONSTRAINT_FUNCTION: 1043;
+    readonly CONSTRAINT_NOTNULL: 1299;
+    readonly CONSTRAINT_PRIMARYKEY: 1555;
+    readonly CONSTRAINT_TRIGGER: 1811;
+    readonly CONSTRAINT_UNIQUE: 2067;
+    readonly CONSTRAINT_VTAB: 2323;
+    readonly CONSTRAINT_ROWID: 2579;
+    readonly CONSTRAINT_PINNED: 2835;
+    readonly CONSTRAINT_DATATYPE: 3091;
+    readonly NOTICE_RECOVER_WAL: 283;
+    readonly NOTICE_RECOVER_ROLLBACK: 539;
+    readonly NOTICE_RBU: 795;
+    readonly WARNING_AUTOINDEX: 284;
+    readonly AUTH_USER: 279;
+    readonly OK_LOAD_PERMANENTLY: 256;
+    readonly OK_SYMLINK: 512;
+}>;
+/** A primary result code of SQLite 3.53.0 — the type of `SQLiteError.sqliteCode`. */
+export type SQLiteResultCode = (typeof SQLITE_CODES)[keyof typeof SQLITE_CODES];
+/**
+ * An extended result code of SQLite 3.53.0. `SQLiteError.sqliteExtendedCode`
+ * is typed `SQLiteExtendedResultCode | (number & {})`: open, because a wrong
+ * read must stay representable (spec D9), yet still completing these values.
+ */
+export type SQLiteExtendedResultCode = (typeof SQLITE_EXTENDED_CODES)[keyof typeof SQLITE_EXTENDED_CODES];

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' | 'retired') => SupervisorDecision | undefined;
+};
+export declare const createSupervisor: (options: {
+    size: number;
+    maxWorkerRestarts?: number | undefined;
+}) => Supervisor;

package/dist/transaction.d.ts

@@ -0,0 +1,61 @@
+import type { SQLiteQueryAPI, SQLiteTransactionDB, SQLiteTransactionOptions } from './api';
+import type { ReadFn, TransactionFn, WriteFn } from './bulk';
+import { SQLiteError } from './errors';
+import type { Logger } from './logger';
+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) => Promise<unknown>;
+    /**
+     * 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;
+    /**
+     * Aborted when the client closes, with `CLIENT_CLOSED`.
+     *
+     * Merged into the transaction's own signal so that closing ABANDONS a
+     * running transaction the way a caller's `signal` does — the callback is
+     * not interrupted, it simply can no longer reach the database. Without it
+     * the caller of a transaction whose callback sits on an `await` that is not
+     * a statement waited for ever: nothing else in the transaction observes the
+     * client going away.
+     */
+    closeSignal: AbortSignal;
+    /**
+     * 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;
+        /** See `src/bulk.ts`: the batch's place in this transaction's queue. */
+        reserve?: () => {
+            started: Promise<void>;
+            done: () => void;
+        };
+    }) => {
+        bulkWrite: SQLiteQueryAPI['bulkWrite'];
+        output: SQLiteQueryAPI['output'];
+    };
+    /**
+     * Reached only through `always`: `rollback()` on a transaction that has
+     * already committed warns whatever the `debug` option says (spec R4) — a
+     * warning visible only under debug would be the same as silence.
+     */
+    logger: Pick<Logger, 'always'>;
+}) => <T = void>(callback: (db: SQLiteTransactionDB) => Promise<T>, options?: SQLiteTransactionOptions) => Promise<T>;