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

package/NOTICE

@@ -0,0 +1,56 @@
+THIRD-PARTY NOTICES
+===================
+
+browser-sqlite is distributed under the MIT License; see LICENSE.
+
+Its published worker artifact (dist/worker/worker.js) has third-party code
+bundled into it, and ships compiled WebAssembly built from third-party
+sources (dist/worker/wa-sqlite.wasm, wa-sqlite-async.wasm, wa-sqlite-jspi.wasm).
+The notices below travel with those files and must be preserved in any
+redistribution.
+
+
+-------------------------------------------------------------------------------
+wa-sqlite — https://github.com/rhashimoto/wa-sqlite
+-------------------------------------------------------------------------------
+
+The JavaScript glue and the VFS implementations bundled into
+dist/worker/worker.js, and the .wasm binaries beside it, are produced by
+wa-sqlite.
+
+MIT License
+
+Copyright (c) 2023 Roy T. Hashimoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+-------------------------------------------------------------------------------
+SQLite — https://sqlite.org
+-------------------------------------------------------------------------------
+
+The .wasm binaries are builds of SQLite. SQLite is in the public domain and
+requires no attribution; the customary blessing is reproduced here.
+
+    The author disclaims copyright to this source code.  In place of
+    a legal notice, here is a blessing:
+
+       May you do good and not evil.
+       May you find forgiveness for yourself and forgive others.
+       May you share freely, never taking more than you give.

package/README.md

@@ -2,6 +2,10 @@
 
 A persistent SQLite database that lives in your browser — yes, for real. Powered by [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (WebAssembly), built for (read) concurrency.
 
+A client stores its data through a wa-sqlite VFS, which decides where that data lives.
+**[Read the VFS page](VFS.md)** to compare them, then
+**[run the benchmarks in your own browser](https://lalexdotcom.github.io/browser-sqlite/)**.
+
 ## Install
 
 ```bash
@@ -10,152 +14,156 @@ npm install browser-sqlite
 pnpm add browser-sqlite
 ```
 
-Requires a bundler that supports Web Workers with dynamic imports (Rsbuild, webpack 5, Vite 3+).
+Requires a bundler that supports Web Workers with dynamic imports — or no bundler at all.
+
+<details>
+<summary><b>Bundler Configuration</b></summary>
 
-## VFS Selection
+Works with no configuration under **rsbuild 1+**, **rspack 1+**, **Parcel 2+**, **Vite 8+**, **webpack 5.101+** — and with no bundler at all.
 
-browser-sqlite delegates storage to a wa-sqlite Virtual File System (VFS). Choose based on browser support and storage requirements:
+Works under **Vite 6.1 to 7** with the following config, which only the dev server needs:
 
-| VFS | Storage | Constraint | When to use |
-|-----|---------|------------|-------------|
-| `OPFSPermutedVFS` **(default)** | OPFS | None — supports `poolSize >= 1` | General purpose. Best choice for most applications. |
-| `OPFSAdaptiveVFS` | OPFS | Requires JSPI (Chromium 126+) | When JSPI is available and adaptive sync strategy is desired. |
-| `OPFSCoopSyncVFS` | OPFS | None — cooperative sync, no JSPI required | Broader browser compatibility fallback when JSPI is unavailable. |
-| `AccessHandlePoolVFS` | OPFS | **`poolSize` must be `1`** — throws otherwise | Single-connection scenarios requiring access handle pool semantics. |
-| `IDBBatchAtomicVFS` | IndexedDB | None | Fallback when OPFS is unavailable (older browsers, some mobile environments). |
+```typescript
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: { exclude: ['browser-sqlite'] },
+});
+```
 
-When `vfs` is omitted, `OPFSPermutedVFS` is used.
+Another bundler will likely work — the worker and its `.wasm` are reached through plain, statically analysable URLs — but may need configuration of its own.
 
-For a detailed VFS comparison, see the [wa-sqlite VFS comparison](https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#vfs-comparison).
+The `.wasm` are read from beside `worker.js`. If a build separates them, or you move them by hand, point at them with [`wasmUrl`](API.md#options).
+</details>
+
+## Browser support
+
+| Chrome | Firefox | Safari |
+|---|---|---|
+| 92+ | 95+ | 15.4+ |
+
+Cross-origin isolation is worth adding where you control your headers: it is what lets an
+aborted call stop a running statement when using a VFS with `sync` build. See
+[Aborting a call](#aborting-a-call).
 
 ## Usage
 
-### Initialize
+Read the [detailed API documentation](API.md) for the full description.
 
 ```typescript
 import { createSQLiteClient } from 'browser-sqlite';
 
-const db = createSQLiteClient('myapp.sqlite', {
-  poolSize: 2,                    // number of worker threads (default: 2)
-  vfs: 'OPFSPermutedVFS',         // VFS selection (default: 'OPFSPermutedVFS')
-  pragmas: {                      // SQLite PRAGMAs applied on open
-    journal_mode: 'WAL',
-    synchronous: 'NORMAL',
-  },
-});
-```
+const db = createSQLiteClient('myapp.sqlite', { vfs: 'OPFSAdaptiveVFS' });
 
-`createSQLiteClient` spawns `poolSize` Web Worker threads immediately. Workers reach READY state asynchronously — queries made before workers are ready are queued automatically.
+await db.write('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
+await db.write('INSERT INTO users (name) VALUES (?)', ['Alice']);
 
-### Read
+const users = await db.read<{ id: number; name: string }>('SELECT id, name FROM users');
 
-```typescript
-type User = { id: number; name: string };
+for await (const row of db.stream<{ id: number; name: string }>('SELECT * FROM users')) {
+  process(row);
+}
 
-const users = await db.read<User>(
-  'SELECT id, name FROM users WHERE active = ?',
-  [1],
-);
-// users: User[]
+await db.close();
 ```
 
-Read queries are dispatched to any available worker, enabling concurrent reads.
+[*client*.id](API.md#clientid) · [*client*.name](API.md#clientname) · [*client*.file](API.md#clientfile) · [*client*.vfs](API.md#clientvfs) · [*client*.build](API.md#clientbuild) · [*client*.poolSize](API.md#clientpoolsize)
 
-### Write
+[createSQLiteClient()](API.md#createsqliteclient) · [*client*.read()](API.md#clientread) · [*client*.write()](API.md#clientwrite) · [*client*.stream()](API.md#clientstream) · [*client*.chunk()](API.md#clientchunk) · [*client*.first()](API.md#clientfirst) · [*client*.transaction()](API.md#clienttransaction) · [*client*.bulkWrite()](API.md#clientbulkwrite) · [*client*.output()](API.md#clientoutput) · [*client*.inspect()](API.md#clientinspect) · [*client*.close()](API.md#clientclose) · [deleteDatabase()](API.md#deletedatabase) · [inspectDatabase()](API.md#inspectdatabase)
 
-```typescript
-const { affected } = await db.write(
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['Alice', 'alice@example.com'],
-);
-// affected: number of rows inserted
-```
+## Storage
 
-Write queries are serialized through a dedicated writer worker — only one write executes at a time.
+The VFS decides *where* your database is written.
+[See every available VFS on the dedicated page](VFS.md), with their pros, their cons, their
+limitations and their browser compatibility.
 
-### Stream (large result sets)
+`OPFSWriteAheadVFS` and `OPFSAdaptiveVFS` are the recommended options.
 
-```typescript
-// Worker is held for the full generator lifetime — always exhaust or break.
-for await (const chunk of db.stream<User>(
-  'SELECT * FROM large_table',
-  [],
-  { chunkSize: 100 },
-)) {
-  processChunk(chunk); // chunk is User[]
-}
-```
+[`OPFSWriteAheadVFS`](VFS.md#opfswriteaheadvfs) · [`OPFSAdaptiveVFS`](VFS.md#opfsadaptivevfs) · [`OPFSCoopSyncVFS`](VFS.md#opfscoopsyncvfs) · [`AccessHandlePoolVFS`](VFS.md#accesshandlepoolvfs) · [`IDBBatchAtomicVFS`](VFS.md#idbbatchatomicvfs) · [`IDBMirrorVFS`](VFS.md#idbmirrorvfs) · [`OPFSAnyContextVFS`](VFS.md#opfsanycontextvfs) · [`MemoryVFS`](VFS.md#memoryvfs) · [`MemoryAsyncVFS`](VFS.md#memoryasyncvfs)
 
-`stream()` yields rows in chunks without buffering the full result set in memory.
+## Guarantees
 
-### One (first row)
+### Reads run concurrently
 
-```typescript
-const user = await db.one<User>(
-  'SELECT * FROM users WHERE id = ?',
-  [42],
-);
-// user: User | undefined
-```
+Every read is dispatched to whichever worker in the pool is free, so several run at once.
+Writes take a dedicated writer worker instead, one at a time.
 
-`one()` automatically aborts after the first result row. Use it for lookups by primary key or unique field.
+### Read-your-own-writes
 
-### Advanced
+It holds within a tab and across tabs. Once a write has resolved, any read issued afterwards
+observes it — from that client, from any other client in the same tab, and from any other tab
+on the same database, whatever the pool size. A worker that has not yet observed the latest
+commit runs one discarded statement that opens a real read transaction before it serves the
+query; that costs one extra worker round-trip on each worker's first statement after a write,
+and nothing under read-only load. `poolSize: 1` and reading inside the same `transaction()`
+remain valid, they are no longer required.
 
-For batch inserts, schema-driven table replacement, or explicit transactions, see:
-- `db.bulkWrite(table, keys)` — batches inserts within `SQLITE_MAX_VARS` limit
-- `db.output(table, schema, options)` — drops, recreates, and populates a table from a schema definition
-- `db.transaction(callback, options)` — wraps operations in a SQLite transaction with auto-commit and rollback
+The one exception is [`IDBMirrorVFS`](VFS.md#idbmirrorvfs), which does not hold it across
+tabs.
 
-### Close
+### Writes are serialized
 
-```typescript
-db.close();
-```
+A write, a write transaction, and each batch of a `bulkWrite` take one lock per database
+across the whole origin, so a second writer **waits** rather than failing — between clients
+and between tabs alike. The wait is unbounded and first-come-first-served: pass a `signal` if
+you would rather fail than wait. A write transaction holds that lock for the whole of its
+callback, so a callback that never returns blocks every other writer in the origin, not only
+its own client. **A `bulkWrite` takes the lock per batch and commits per batch**, so another
+client's write can land between two of its batches — use `tx.bulkWrite` where you need all or
+nothing.
 
-Terminates all worker threads.
+## Known Limitations
 
-## Requirements
+Some VFS have limitations of their own — see [the detailed VFS page](VFS.md#vfs-reference).
+What follows holds on all of them.
 
-> **These HTTP headers are mandatory.** Without them, `new SharedArrayBuffer()` throws a `SecurityError` and browser-sqlite cannot initialize.
+### Aborting a call
 
-browser-sqlite uses a `SharedArrayBuffer` to coordinate worker pool state. Browsers require [cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated) to create `SharedArrayBuffer` instances. Your page must be served with:
+An abort does not always stop the work, and your hosting decides. On the `sync` build, a
+`signal` or a `timeout` rejects your promise straight away, but the statement runs to its
+end on its worker, which stays unavailable until it does.
 
-```http
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
+Two ways out — serving the page cross-origin isolated, or `build: 'async'` — and what each
+one costs are under [Interrupting a call](API.md#interrupting-a-call).
+
+### Deleting a database
 
-### Server configuration examples
+A database that any client still holds cannot be deleted, in this tab or another, on every
+VFS. More on the dedicated [`deleteDatabase`](API.md#deletedatabase) API entry.
 
-**Nginx**
-```nginx
-add_header Cross-Origin-Opener-Policy "same-origin";
-add_header Cross-Origin-Embedder-Policy "require-corp";
+## Development
+
+```bash
+pnpm install
+pnpm build          # rslib → dist/
+pnpm test           # unit (Node) + browser (Playwright/Chromium)
+pnpm check          # biome, with --write
 ```
 
-**Express**
-```javascript
-app.use((req, res, next) => {
-  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
-  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
-  next();
-});
+Two suites run on demand rather than on every change:
+
+```bash
+pnpm test:conformance   # every declared (vfs, build) pair through six invariants
+pnpm test:consumer      # packs the tarball and drives four bundler modes
 ```
 
-**Rsbuild / Vite dev server**
-```typescript
-// rsbuild.config.ts or vite.config.ts
-server: {
-  headers: {
-    'Cross-Origin-Opener-Policy': 'same-origin',
-    'Cross-Origin-Embedder-Policy': 'require-corp',
-  },
-},
+### The benchmark page
+
+`scripts/bench/html/index.html` is the page published above. It is one self-contained file
+served beside a verbatim copy of `dist/`, so it exercises the library exactly as
+a consumer would with no bundler at all.
+
+```bash
+pnpm bench:dev      # build, serve on http://127.0.0.1:8099, rebuild on change
+pnpm bench:serve    # same without the watch
+pnpm bench:build    # assemble _site/ only
 ```
 
-## Known Limitations
+`http://127.0.0.1` is a secure context, so OPFS works with no certificate — no
+TLS setup is needed to develop against it. A phone on the LAN is a different
+matter: it is not a secure context, so OPFS is unavailable there and a tunnel
+(or the published page) is the way to test a real device.
 
-- **`AccessHandlePoolVFS` requires `poolSize: 1`.** Passing `poolSize > 1` with this VFS throws synchronously at client creation time.
-- **`SharedArrayBuffer` requires cross-origin isolation.** See the [Requirements](#requirements) section. Omitting COOP/COEP headers causes a `SecurityError` at runtime with no fallback.
-- **`OPFSAdaptiveVFS` requires Chromium 126+.** This VFS uses JavaScript Promise Integration (JSPI), which is not available in Firefox or Safari as of 2025.
+`node scripts/bench/check.mjs [chromium|firefox] [--all]` drives the page under
+Playwright and asserts that it still works — it is run by hand and deliberately
+not wired into CI. It checks the *page*, never that a VFS passes: a red cell can
+be a correct report about the engine you are on.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lalexdotcom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/NOTICE

@@ -0,0 +1,56 @@
+THIRD-PARTY NOTICES
+===================
+
+browser-sqlite is distributed under the MIT License; see LICENSE.
+
+Its published worker artifact (dist/worker/worker.js) has third-party code
+bundled into it, and ships compiled WebAssembly built from third-party
+sources (dist/worker/wa-sqlite.wasm, wa-sqlite-async.wasm, wa-sqlite-jspi.wasm).
+The notices below travel with those files and must be preserved in any
+redistribution.
+
+
+-------------------------------------------------------------------------------
+wa-sqlite — https://github.com/rhashimoto/wa-sqlite
+-------------------------------------------------------------------------------
+
+The JavaScript glue and the VFS implementations bundled into
+dist/worker/worker.js, and the .wasm binaries beside it, are produced by
+wa-sqlite.
+
+MIT License
+
+Copyright (c) 2023 Roy T. Hashimoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+-------------------------------------------------------------------------------
+SQLite — https://sqlite.org
+-------------------------------------------------------------------------------
+
+The .wasm binaries are builds of SQLite. SQLite is in the public domain and
+requires no attribution; the customary blessing is reproduced here.
+
+    The author disclaims copyright to this source code.  In place of
+    a legal notice, here is a blessing:
+
+       May you do good and not evil.
+       May you find forgiveness for yourself and forgive others.
+       May you share freely, never taking more than you give.

package/dist/abandon.d.ts

@@ -0,0 +1,77 @@
+import type { PoolWorker } from './pool';
+/**
+ * Whether this cleanup has already run.
+ *
+ * A plain object rather than a boolean because the held value must observe a
+ * change the generator makes after registration. Three routes reach the
+ * cleanup — the registry, the abort listener and the generator's own `finally`
+ * — and whichever arrives first closes the door on the other two.
+ *
+ * What it deliberately does NOT record is whether the query ever started. That
+ * answers "did this generator run", where the only question that matters is
+ * "is the worker still serving this query" — and the worker is the one that
+ * knows, which is why `interrupt()` is asked rather than told.
+ */
+export type AbandonState = {
+    done: boolean;
+};
+/**
+ * What the cleanup needs, and all it may hold.
+ *
+ * **It must never refer to the registered generator.** A `FinalizationRegistry`
+ * held value that reaches its own target keeps the target alive and the
+ * callback then never fires. Every field here points downward or sideways: the
+ * worker and the transport iterator are reachable from the pool anyway, `state`
+ * is a plain flag, `detach` closes over the caller's signal and its listener,
+ * and `release` is the owning layer's teardown.
+ */
+export type Abandoned = {
+    worker: Pick<PoolWorker, 'interrupt'>;
+    iterator: {
+        return: (value?: undefined) => Promise<unknown>;
+    };
+    state: AbandonState;
+    /**
+     * Removes the abort listener that carries this very cleanup. Without it a
+     * listener stays armed on a signal the CALLER owns, long after the query it
+     * belonged to has ended — and fires against whatever the worker is doing
+     * then.
+     */
+    detach: () => void;
+    release?: (() => void) | undefined;
+};
+/**
+ * What the `finally` of `queries.chunk` would have done, for a generator that
+ * will never run it.
+ *
+ * The order is that `finally`'s and for its reason: `interrupt()` first, so the
+ * queued `return()` is not parked behind a `next()` that will not settle.
+ *
+ * **Nothing here may assume the worker is still ours.** This runs at a moment
+ * nobody chose — a collection, or the caller tidying up its own controller —
+ * and by then the worker may be serving a query that has nothing to do with
+ * this one. So the transport is named in both calls: `interrupt(iterator)` is a
+ * no-op unless the worker is still serving it, and `iterator.return()` resumes
+ * a transport whose own `finally` makes the same check. `return()` on a
+ * generator whose body never ran is a no-op besides, the body having never
+ * entered its `try`.
+ *
+ * `release` is the exception and runs unconditionally: it is the owning layer's
+ * resource — a lease, a timer, a merge teardown — and it is owed whatever the
+ * worker has since moved on to.
+ */
+export declare const reclaim: ({ worker, iterator, state, detach, release, }: Abandoned) => void;
+export type AbandonRegistry = {
+    /** Watch `target`; `held` is what the cleanup receives, `token` unregisters. */
+    watch: (target: object, held: Abandoned, token: object) => void;
+    /** The generator ended by an ordinary route — there is nothing to reclaim. */
+    forget: (token: object) => void;
+};
+/**
+ * `run` is injected so that tests drive the cleanup without a collection.
+ * Nothing else here is observable: a `FinalizationRegistry` fires when the
+ * engine decides, which is not a schedule a test can assert against.
+ */
+export declare const createAbandonRegistry: (run?: (held: Abandoned) => void) => AbandonRegistry;
+/** The one this library uses. */
+export declare const abandonRegistry: AbandonRegistry;