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

package/dist/types.d.ts

@@ -0,0 +1,348 @@
+export type SQLiteWorkerMessageData<_T = unknown> = {
+    callId: number;
+    terminate?: boolean;
+} & (SQLWorkerResultData[keyof SQLWorkerResultData] | {
+    type: 'error';
+    message: string;
+});
+export type SQLWorkerResultData<T = unknown> = {
+    open: {
+        success: boolean;
+    };
+    sql: {
+        type: 'partial';
+        result: T[];
+    } | {
+        type: 'one';
+        sizes: number[];
+    };
+    abort: {
+        type: 'done';
+    };
+};
+export declare const SharedArrayTypes: {
+    INT: number;
+    STRING: number;
+    OBJECT: number;
+};
+type SQLOptions = {
+    chunkSize?: number;
+    /** Chunks the worker may send before waiting for a credit. Spec §3.2. */
+    credits?: number;
+};
+/**
+ * Where a worker fetches its `.wasm` from, when the consumer overrode it.
+ *
+ * Discriminated rather than a single string because the two forms differ in
+ * what they leave to the Emscripten glue. `base` is a directory: the glue
+ * supplies the file name (`locateFile('wa-sqlite-async.wasm')`), so nothing
+ * here names the three builds' files — and nothing has to be renamed when
+ * wa-sqlite renames one. `file` is the whole URL, typically content-hashed by
+ * a bundler, so the glue's file name is discarded.
+ *
+ * Always absolute: `resolveWasmLocation` (`src/utils.ts`) resolves against the
+ * page before the `open` message is posted, so the worker applies it without
+ * knowing what it was relative to.
+ */
+export type WasmLocation = {
+    base: string;
+} | {
+    file: string;
+};
+export type ClientMessageData = {
+    type: 'open';
+    file: string;
+    vfs: SQLiteVFS;
+    build?: SQLiteBuild;
+    pragmas?: Record<string, string>;
+    /** Statements retained per worker; see `src/client.ts`. Internal. */
+    statementCacheSize?: number;
+    wasm?: WasmLocation;
+} | {
+    type: 'query';
+    callId: number;
+    sql: string;
+    params: unknown[];
+    options?: SQLOptions;
+} | {
+    type: 'close';
+    callId: number;
+} | {
+    type: 'credit';
+    callId: number;
+    n: number;
+} | {
+    type: 'stop';
+    callId: number;
+} | {
+    type: 'delete';
+    callId: number;
+    file: string;
+    vfs: SQLiteVFS;
+    build?: SQLiteBuild;
+    wasm?: WasmLocation;
+};
+export type WorkerMessageData = {
+    type: 'ready';
+    callId: number;
+} | {
+    type: 'chunk';
+    callId: number;
+    data: unknown[];
+} | {
+    type: 'done';
+    callId: number;
+    affected: number;
+    /**
+     * Statements compiled while serving this query — zero on a cache hit.
+     * Rides the same message as `affected` rather than opening a channel:
+     * the effect this instruments is a count, not a duration (`mem:lessons`,
+     * "for a sub-millisecond effect, count the round trips").
+     */
+    prepared: number;
+} | {
+    type: 'error';
+    callId: number;
+    message: string;
+    cause?: unknown;
+    /** SQLite's numeric result code, when the failure came from SQLite. */
+    sqliteCode?: number;
+} | {
+    type: 'closed';
+    callId: number;
+} | {
+    type: 'deleted';
+    callId: number;
+} | {
+    type: 'open-error';
+    callId: number;
+    message: string;
+    cause?: unknown;
+    /** SQLite's numeric result code, when the failure came from SQLite. */
+    sqliteCode?: number;
+};
+/** Which wa-sqlite WebAssembly build a worker loads. */
+export type SQLiteBuild = 'sync' | 'async' | 'jspi';
+/**
+ * What each build needs from the engine beyond plain WebAssembly.
+ *
+ * `satisfies Record<SQLiteBuild, …>` and not `SQLiteBuild = keyof typeof …`:
+ * the check must run in this direction. Adding a build to the union then fails
+ * to compile until its requirements are declared, where `keyof` would let a
+ * forgotten entry mean silently that the build does not exist. `VFS_CAPABILITIES`
+ * derives `SQLiteVFS` from its keys because it *is* the VFS registry; the build
+ * registry is `WA_SQLITE_BUILDS` in the worker, and this table describes one
+ * attribute of builds rather than the builds themselves.
+ */
+export declare const BUILD_REQUIREMENTS: {
+    readonly sync: readonly [];
+    readonly async: readonly [];
+    readonly jspi: readonly ["jspi"];
+};
+/**
+ * A platform feature a VFS may need. Which browser versions ship each one is
+ * documentation data, not runtime data, so it lives in the README generator
+ * (`scripts/render-vfs-matrix.ts`) with its sources — not here, where it would
+ * ship to every consumer for nothing.
+ */
+export type PlatformFeature = 'opfs' | 'readwrite-unsafe' | 'jspi' | 'writable-stream';
+/** Where a VFS keeps the database. */
+export type VFSStorage = 'opfs' | 'indexeddb' | 'memory';
+/**
+ * How a VFS arranges a database in its storage — which is not the same
+ * question as `storage`, and cannot be derived from it: `AccessHandlePoolVFS`
+ * is `storage: 'opfs'` yet keeps opaque, randomly named slot files whose
+ * association with a SQLite path lives in a header inside each file.
+ *
+ * `deleteDatabase` reads this to decide whether the database is also an OPFS
+ * entry it can remove by name after `jDelete` — the pass that covers the two
+ * VFS whose `jDelete` does not delete. A wrong value here is a deletion that
+ * reports success over an intact file.
+ */
+export type VFSLayout = 'opfs-path' | 'opfs-pool' | 'idb-store' | 'memory';
+/** How much of the database a VFS keeps resident in RAM. */
+export type VFSMemoryModel = 'page-cache' | 'whole-database';
+/** What a VFS can and cannot do. One entry per VFS, and no second table. */
+export type VFSCapability = {
+    /** Builds this VFS can run on, most preferred first. */
+    readonly builds: readonly [SQLiteBuild, ...SQLiteBuild[]];
+    /** Largest pool this VFS supports; `null` when unbounded. */
+    readonly maxPoolSize: number | null;
+    /** Why the cap exists. Required whenever `maxPoolSize` is not null. */
+    readonly poolLimitReason: string | null;
+    /** Whether several connections may share one database. */
+    readonly multiConnection: boolean;
+    /** Whether data outlives `close()`. */
+    readonly persistent: boolean;
+    /**
+     * `page-cache`: only SQLite's page cache is resident, bounded by
+     * `PRAGMA cache_size`. `whole-database`: the entire database is resident,
+     * and `poolSize` multiplies it.
+     */
+    readonly memoryModel: VFSMemoryModel;
+    /** Where the database actually lives. */
+    readonly storage: VFSStorage;
+    /** How the database is arranged within that storage. */
+    readonly layout: VFSLayout;
+    /**
+     * Platform features without which this VFS cannot work at all.
+     *
+     * `readwrite-unsafe` is the one that bites: WebIDL ignores the unknown
+     * dictionary member on engines that do not implement it, so the handle
+     * silently opens exclusive and the second connection hangs rather than
+     * failing. Declaring it is what lets the conformance suite probe for it and
+     * skip, instead of leaving it to surface as a 60-second timeout.
+     */
+    readonly requires: readonly PlatformFeature[];
+    /**
+     * Platform features this VFS uses when present and works without, at a cost.
+     *
+     * `OPFSAdaptiveVFS` is the case this field exists for. Without
+     * `readwrite-unsafe` it rotates a single exclusive access handle between
+     * connections instead of holding one each. That works — 102 of 104 browser
+     * tests pass on Firefox — but it serializes the whole pool for the duration
+     * of a long uninterruptible statement.
+     *
+     * Without this distinction, a support table derived from browser specs would
+     * mark that VFS broken everywhere outside Chromium, when it merely degrades.
+     */
+    readonly degradesWithout: readonly PlatformFeature[];
+};
+/**
+ * The single source of truth for VFS selection. `SQLiteVFS` is derived from its
+ * keys, `worker/worker.ts` must supply a loader for every key, the guards in
+ * `client.ts` read it, the conformance suite gates its scenarios on it, and the
+ * README table is generated from it. Nothing may hold a second copy.
+ *
+ * Build order is a decision per VFS, not a rule: `sync` is both the fastest and
+ * the most portable build, so it leads wherever supported; `OPFSAdaptiveVFS`
+ * cannot use it and leads with `async` because `jspi` is Chromium-only.
+ *
+ * Every declared build combination is verified by running it against the pinned
+ * wa-sqlite v1.1.2, never copied from upstream's table.
+ */
+export declare const VFS_CAPABILITIES: {
+    readonly OPFSAdaptiveVFS: {
+        readonly builds: readonly ["async", "jspi"];
+        readonly maxPoolSize: null;
+        readonly poolLimitReason: null;
+        readonly multiConnection: true;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'opfs';
+        readonly layout: 'opfs-path';
+        readonly requires: readonly ["opfs"];
+        readonly degradesWithout: readonly ["readwrite-unsafe"];
+    };
+    readonly OPFSWriteAheadVFS: {
+        readonly builds: readonly ["sync", "async", "jspi"];
+        readonly maxPoolSize: null;
+        readonly poolLimitReason: null;
+        readonly multiConnection: true;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'opfs';
+        readonly layout: 'opfs-path';
+        readonly requires: readonly ["opfs"];
+        readonly degradesWithout: readonly ["readwrite-unsafe"];
+    };
+    readonly OPFSCoopSyncVFS: {
+        readonly builds: readonly ["sync", "async", "jspi"];
+        readonly maxPoolSize: null;
+        readonly poolLimitReason: null;
+        readonly multiConnection: true;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'opfs';
+        readonly layout: 'opfs-path';
+        readonly requires: readonly ["opfs"];
+        readonly degradesWithout: readonly [];
+    };
+    readonly AccessHandlePoolVFS: {
+        readonly builds: readonly ["sync", "async", "jspi"];
+        readonly maxPoolSize: 1;
+        readonly poolLimitReason: 'it cannot share access handles between connections';
+        readonly multiConnection: false;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'opfs';
+        readonly layout: 'opfs-pool';
+        readonly requires: readonly ["opfs"];
+        readonly degradesWithout: readonly [];
+    };
+    readonly IDBBatchAtomicVFS: {
+        readonly builds: readonly ["async", "jspi"];
+        readonly maxPoolSize: null;
+        readonly poolLimitReason: null;
+        readonly multiConnection: true;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'indexeddb';
+        readonly layout: 'idb-store';
+        readonly requires: readonly [];
+        readonly degradesWithout: readonly [];
+    };
+    readonly IDBMirrorVFS: {
+        readonly builds: readonly ["async", "jspi"];
+        readonly maxPoolSize: 1;
+        readonly poolLimitReason: 'its pages are mirrored per worker and commits propagate asynchronously, so a larger pool reads stale data or fails outright';
+        readonly multiConnection: false;
+        readonly persistent: true;
+        readonly memoryModel: 'whole-database';
+        readonly storage: 'indexeddb';
+        readonly layout: 'idb-store';
+        readonly requires: readonly [];
+        readonly degradesWithout: readonly [];
+    };
+    readonly OPFSAnyContextVFS: {
+        readonly builds: readonly ["async", "jspi"];
+        readonly maxPoolSize: null;
+        readonly poolLimitReason: null;
+        readonly multiConnection: true;
+        readonly persistent: true;
+        readonly memoryModel: 'page-cache';
+        readonly storage: 'opfs';
+        readonly layout: 'opfs-path';
+        readonly requires: readonly ["opfs", "writable-stream"];
+        readonly degradesWithout: readonly [];
+    };
+    readonly MemoryVFS: {
+        readonly builds: readonly ["sync", "async", "jspi"];
+        readonly maxPoolSize: 1;
+        readonly poolLimitReason: 'its pages live in the worker that opened them, so a larger pool would open independent databases that diverge silently';
+        readonly multiConnection: false;
+        readonly persistent: false;
+        readonly memoryModel: 'whole-database';
+        readonly storage: 'memory';
+        readonly layout: 'memory';
+        readonly requires: readonly [];
+        readonly degradesWithout: readonly [];
+    };
+    readonly MemoryAsyncVFS: {
+        readonly builds: readonly ["async", "jspi"];
+        readonly maxPoolSize: 1;
+        readonly poolLimitReason: 'its pages live in the worker that opened them, so a larger pool would open independent databases that diverge silently';
+        readonly multiConnection: false;
+        readonly persistent: false;
+        readonly memoryModel: 'whole-database';
+        readonly storage: 'memory';
+        readonly layout: 'memory';
+        readonly requires: readonly [];
+        readonly degradesWithout: readonly [];
+    };
+};
+export type SQLiteVFS = keyof typeof VFS_CAPABILITIES;
+/** The build used when the caller does not name one. */
+export declare const defaultBuildFor: (vfs: SQLiteVFS) => SQLiteBuild;
+/**
+ * The VFS this project recommends when a caller has no reason to choose
+ * another. It is NOT a default — `vfs` is required, precisely so that the name
+ * lives in the consumer's own source and cannot move underneath their data.
+ *
+ * It lives here, beside the table, because the README generator marks this row
+ * `(recommended)` and would otherwise hold a second copy. It is deliberately
+ * not exported: a consumer writing `vfs: RECOMMENDED_VFS` would be exposed to
+ * the same displacement the day the recommendation changes.
+ */
+export declare const RECOMMENDED_VFS: SQLiteVFS;
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,116 @@
+import type { SQLiteBuild, WasmLocation } from './types';
+export declare const sqlParams: () => {
+    addParam: (v: unknown) => string;
+    addParamArray: (values: unknown[]) => string;
+    params: unknown[];
+};
+export declare const isReadQuery: (sql: string) => boolean;
+export declare const isWriteQuery: (sql: string) => boolean;
+/**
+ * Combines two abort signals into one that fires with the reason of whichever
+ * source aborted first, plus the `release()` that unsubscribes it.
+ *
+ * NOT `AbortSignal.any()`. That is Chrome 116 / Firefox 124 / Safari 17.4, far
+ * above this library's floor (Chrome 92 / Firefox 95 / Safari 15.4), and
+ * adopting it would raise every row of the generated README matrix for every
+ * consumer.
+ *
+ * The common case allocates nothing: with one side absent, or one side already
+ * aborted, the surviving signal is returned as itself — no listener, no
+ * teardown owed, and the caller sees the original `reason` rather than a copy.
+ */
+export declare const mergeSignals: (a: AbortSignal | undefined, b: AbortSignal | undefined) => {
+    signal: AbortSignal | undefined;
+    release: () => void;
+};
+/**
+ * Routing guard for the read-shaped methods (`read`, `chunk`, `stream`, `first`).
+ * Throws before a lease is taken, so a rejected statement costs no pool capacity.
+ *
+ * A bare read pragma (`PRAGMA journal_mode`) is accepted; a pragma that assigns
+ * (`PRAGMA journal_mode=WAL`), takes an argument, or is followed by anything
+ * else must go through `write()`.
+ */
+export declare const assertReadable: (sql: string, method: string) => void;
+/**
+ * Quotes an SQL identifier so it can never be read as anything but a name.
+ *
+ * The library interpolates table, column and index names into generated SQL —
+ * `bulkWrite`, `output` and their indexes. wa-sqlite's `statements()` executes
+ * `;`-separated statements, so an unquoted name is a stacked-query injection
+ * (B4). Quoting is what makes `t"; DROP TABLE users; --` one identifier.
+ *
+ * Note that quoting preserves case in `sqlite_master`; SQLite still resolves
+ * names case-insensitively.
+ */
+export declare const quoteIdent: (name: string) => string;
+/**
+ * A column type is not an identifier and cannot be quoted — it is an SQL
+ * fragment the caller writes. It is validated by shape instead: this is the
+ * narrowed, not closed, channel documented in the spec (§1.2).
+ */
+export declare const assertColumnType: (type: string, column: string) => string;
+/**
+ * A GENERATED ALWAYS AS expression is caller-authored SQL. It must at least be
+ * parenthesised and free of statement separators, so it cannot escape its slot.
+ */
+export declare const assertGeneratedExpression: (expr: string, column: string) => string;
+/**
+ * Renders the client's `pragmas` option into executable statements, rejecting
+ * anything that is not provably a name and a scalar value (B4).
+ *
+ * Validation is syntactic rather than a closed list of the ~60 SQLite pragmas:
+ * a fixed list makes every legitimate pragma outside it unreachable and drifts
+ * with SQLite versions, for no additional protection — no ";", no parenthesis
+ * and no comment marker survives these three shapes either.
+ *
+ * Called twice: by the client at construction, so a bad configuration fails at
+ * `createSQLiteClient()` rather than inside an unrelated query, and by the
+ * worker at open, which is the only place the statements actually run.
+ */
+export declare const renderPragmas: (pragmas: Record<string, string>) => string[];
+/**
+ * The single definition of database identity — one string used everywhere:
+ * the worker open call, the VFS, the epoch registry and every lock name.
+ *
+ * The form is **relative** (no leading `/`). `URL.pathname` is absolute by
+ * construction, so stripping the slash is necessary: SQLite core checks
+ * `nPathname + 8 > mxPathname` (64, `node_modules/wa-sqlite/src/VFS.js:10`)
+ * before `xOpen`, and a leading `/` costs a character the budget cannot spare —
+ * measured at task 1: it broke all 96 browser tests on 56-char names. The
+ * strip gives that character back, so a 56-char name that the caller wrote
+ * still fits after normalization. The VFS re-parse (`new URL(zName, 'file://')`
+ * for four of five; `AccessHandlePoolVFS` via `'file://localhost/'`) produces
+ * identical `pathname` whether the open call receives `'data'` or `'/data'`,
+ * so the opened OPFS file is the same regardless.
+ *
+ * Idempotent: the VFS re-parse of an already-normalized name is a no-op.
+ */
+export declare const normalizeDatabaseFile: (file: string) => string;
+/**
+ * Turns the `wasmUrl` client option into the absolute location posted in the
+ * `open` message, or `undefined` when the option was not given.
+ *
+ * `undefined` is the load-bearing case: the worker sets Emscripten's
+ * `locateFile` only when it receives a location, and `findWasmBinary` takes its
+ * `new URL('wa-sqlite.wasm', import.meta.url)` branch whenever `locateFile` is
+ * absent. So an omitted option leaves resolution byte-for-byte as it was
+ * before this option existed — which is the entire contract of the escape
+ * hatch.
+ *
+ * Resolution happens **here**, on the client, against the page: what the
+ * consumer writes means what it means from the page they wrote it on, not from
+ * the worker's own directory one level down. The callback is therefore called
+ * once, at client construction, before any worker exists — its result is
+ * reused by every worker in the pool and by every restart.
+ *
+ * A string is a **directory** and gets its missing trailing slash back before
+ * resolution: URL resolution treats a last segment without a slash as a
+ * document and replaces it, so `'/static/wasm'` would otherwise silently mean
+ * `/static/`. A callback names a **file**, so nothing is appended to it.
+ *
+ * @throws `SQLiteError('INVALID_OPTION')` when the value cannot be parsed as a
+ * URL — synchronously, at construction, rather than as an opaque open failure
+ * from a worker that could not fetch its module.
+ */
+export declare const resolveWasmLocation: (wasmUrl: string | ((build: SQLiteBuild) => string) | undefined, build: SQLiteBuild, baseHref: string) => WasmLocation | undefined;

package/dist/worker/cloneable.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Makes a value safe to hand to `postMessage`.
+ *
+ * The whole point is a failure the caller cannot recover from: a cause that
+ * cannot be structured-cloned makes `postMessage` itself throw, and every call
+ * site here is already inside a `catch` building an error reply. The throw
+ * would replace that reply with nothing, and the client would wait for ever on
+ * a request that was answered by no message at all.
+ *
+ * Pure, and in its own module for the reason `statement-cache.ts` is: the
+ * remainder of `worker.ts` only runs in a browser, and this decides something
+ * worth testing in Node against a value that is deliberately unclonable.
+ */
+/**
+ * Returns `value` when it survives the structured-clone algorithm, and its
+ * string form when it does not.
+ *
+ * `MessageChannel` rather than `structuredClone()`: the two run the same
+ * algorithm and throw the same `DataCloneError`, but `structuredClone` lands at
+ * Chrome 98 where `MessageChannel` is Chrome 2 / Firefox 41 / Safari 5. Using
+ * it would have raised this library's floor by six Chrome versions to protect
+ * an error *cause* — see `scripts/render-vfs-matrix.ts`, which computes that
+ * floor from the APIs named here.
+ */
+export declare const cloneable: (value: unknown) => unknown;

package/dist/worker/statement-cache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A per-worker LRU of prepared statements, keyed by the exact SQL string.
+ *
+ * Pure bookkeeping: this module prepares nothing and finalises nothing.
+ * `worker.ts` owns every effect, which is what lets the policy be tested in
+ * Node against plain integers in a subsystem whose remainder only runs in a
+ * browser — the role `mem:architecture` describes for `scheduler.ts` and
+ * `supervisor.ts`.
+ */
+/** A `sqlite3_stmt` pointer. Opaque here: the cache only files it. */
+export type StatementHandle = number;
+export type StatementCache = {
+    get: (sql: string) => StatementHandle | 'uncacheable' | undefined;
+    /** Returns the handles evicted by this insertion; the caller finalises them. */
+    set: (sql: string, handle: StatementHandle) => StatementHandle[];
+    /** Returns the handles evicted by this marking; the caller finalises them. */
+    markUncacheable: (sql: string) => StatementHandle[];
+    delete: (sql: string) => StatementHandle | undefined;
+    /** Empties the cache and returns every live handle, for close. */
+    drain: () => StatementHandle[];
+};
+export declare const createStatementCache: (capacity: number) => StatementCache;