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

package/dist/utils.d.ts

@@ -0,0 +1,156 @@
+import { type SQLiteBuild, type SQLiteVFS, type 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;
+/**
+ * Whether `sql` manages the transaction or its savepoints rather than data
+ * (spec 2026-09-11, D8). Never wrapped in the library's savepoint: there is
+ * nothing to undo, and a `RELEASE u` run inside it would pop it along with
+ * `u`. The leading keyword decides: these statements are never compound.
+ */
+export declare const isTransactionControl: (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 VFS.md 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;
+};
+/**
+ * The `timeout` option: a wall-clock budget in milliseconds, counted from the
+ * call. Returns the signal the call should actually use — the caller's own,
+ * merged with one this library owns and aborts when the budget is spent.
+ *
+ * The abort reason IS the error the caller receives. Every abort path in this
+ * library rejects with `signal.reason`, and `mergeSignals` relays a reason
+ * verbatim, so nothing downstream has to ask which signal fired. That is why
+ * this is an AbortController and a setTimeout rather than
+ * `AbortSignal.timeout()`, which offers no way to set the reason.
+ *
+ * `release()` is owed exactly once, however the call ends.
+ */
+export declare const withDeadline: (options: {
+    signal?: AbortSignal | undefined;
+    timeout?: number | undefined;
+} | undefined, method: string) => {
+    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.
+ */
+/**
+ * The PRAGMAs a client actually applies: the VFS's declared defaults with the
+ * consumer's own layered over them.
+ *
+ * **Merged, never replaced.** A consumer who passes one pragma is answering a
+ * question of their own — `foreign_keys` is the usual one — not declining the
+ * VFS's defaults, and replacing would silently drop every default the moment
+ * they set anything at all. A key they DO set always wins, which is how a
+ * default is refused: pass `journal_mode` yourself and yours is what runs.
+ *
+ * Order matters and is the whole function: spread the defaults first.
+ */
+export declare const resolvePragmas: (vfs: SQLiteVFS, pragmas: Record<string, string> | undefined) => Record<string, string>;
+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/probes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Platform features a worker can probe for itself, synchronously, before it
+ * loads anything. Pure, and tested in Node for the reason `cloneable.ts` is.
+ *
+ * `readwrite-unsafe` cannot be probed from the page: `FileSystemSyncAccessHandle`
+ * is exposed to dedicated workers only, which is why `capabilities.ts` lists
+ * it as unprobeable. A worker can, and without opening a file: the engines that
+ * implement the mode also ship the handle's `mode` ATTRIBUTE. That is not the
+ * trap `capabilities.ts` warns about — WebIDL ignores an unknown DICTIONARY
+ * member, so passing the option proves nothing, but an attribute an engine does
+ * not implement is simply absent from the prototype. Measured 2026-09-13 in a
+ * dedicated worker: Chromium true, Firefox false, Safari false
+ * (spec 2026-09-13, §3.1).
+ */
+import type { PlatformFeature } from '../types';
+/** The globals a probe reads; `globalThis` in a worker, a stub in tests. */
+export type ProbeScope = {
+    FileSystemSyncAccessHandle?: unknown;
+};
+export declare const WORKER_PROBES: Partial<Record<PlatformFeature, (scope: ProbeScope) => boolean>>;
+/**
+ * The first feature of `features` this worker lacks, or null. A feature with
+ * no probe here is never reported missing: declining on something unprobeable
+ * would shrink every pool on every engine.
+ */
+export declare const firstMissing: (features: readonly PlatformFeature[], scope?: ProbeScope) => PlatformFeature | null;

package/dist/worker/sqlite-code.d.ts

@@ -0,0 +1,9 @@
+import type { SQLiteResultCode } from '../sqlite-codes';
+/**
+ * SQLite's result code on a thrown value, or undefined when SQLite did not
+ * raise it (spec 2026-09-14, final review). wa-sqlite raises its own
+ * `SQLiteError(message, code)` for every result code. Anything else carrying a
+ * numeric `code` — a DOMException's legacy code, 18 for SecurityError — is
+ * not SQLite's and must not be published as `sqliteCode`.
+ */
+export declare const sqliteCodeOf: (e: unknown) => SQLiteResultCode | undefined;

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

@@ -0,0 +1,36 @@
+/**
+ * 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;
+/**
+ * The two bounds, both active. `maxEntries` answers the churn that generated
+ * SQL produces; `maxBytes` answers the footprint of a `bulkWrite` template,
+ * which is three orders of magnitude heavier than an ordinary statement
+ * (`mem:measurements`).
+ */
+export type StatementCacheBounds = {
+    maxEntries: number;
+    maxBytes: number;
+};
+export type StatementCache = {
+    get: (sql: string) => StatementHandle | 'uncacheable' | undefined;
+    /**
+     * Returns the handles evicted by this insertion; the caller finalises them.
+     * `weight` is `SQLITE_STMTSTATUS_MEMUSED` and is required on purpose: an
+     * optional one would silently account a statement as free.
+     */
+    set: (sql: string, handle: StatementHandle, weight: number) => 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: ({ maxEntries, maxBytes, }: StatementCacheBounds) => StatementCache;