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

package/README.md

@@ -2,10 +2,9 @@
 
 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.
 
-**▶ [Run the benchmarks in your own browser](https://lalexdotcom.github.io/browser-sqlite/)** — every
-VFS this library ships, put through the same conformance checks and measurements, on your device.
-It is the honest way to choose one: which VFS wins depends on the engine, and it changes often —
-a single browser release can move the answer.
+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
 
@@ -17,7 +16,8 @@ pnpm add browser-sqlite
 
 Requires a bundler that supports Web Workers with dynamic imports — or no bundler at all.
 
-## Bundler Configuration
+<details>
+<summary><b>Bundler Configuration</b></summary>
 
 Works with no configuration under **rsbuild 1+**, **rspack 1+**, **Parcel 2+**, **Vite 8+**, **webpack 5.101+** — and with no bundler at all.
 
@@ -32,254 +32,8 @@ export default defineConfig({
 
 Another bundler will likely work — the worker and its `.wasm` are reached through plain, statically analysable URLs — but may need configuration of its own.
 
-The `.wasm` are read from beside `worker.js`. If a build separates them, or you move them by hand, point at them with [`wasmUrl`](#options).
-
-## Usage
-
-[createSQLiteClient](#createsqliteclient) · [*client*.read](#clientread) · [*client*.write](#clientwrite) · [*client*.stream](#clientstream) · [*client*.chunk](#clientchunk) · [*client*.first](#clientfirst) · [*client*.transaction](#clienttransaction) · [*client*.bulkWrite](#clientbulkwrite) · [*client*.output](#clientoutput) · [*client*.close](#clientclose) · [deleteDatabase](#deletedatabase)
-
-### createSQLiteClient
-
-```typescript
-import { createSQLiteClient } from 'browser-sqlite';
-
-const db = createSQLiteClient('myapp.sqlite', {
-  poolSize: 2,                    // number of worker threads (default: 2)
-  vfs: 'OPFSAdaptiveVFS',         // required — see VFS Selection
-  build: 'async',                 // wa-sqlite build (default: the VFS's first)
-  pragmas: {                      // SQLite PRAGMAs applied on open
-    journal_mode: 'WAL',
-    synchronous: 'NORMAL',
-  },
-});
-```
-
-`createSQLiteClient` spawns `poolSize` Web Worker threads immediately. Workers reach READY state asynchronously — queries made before workers are ready are queued automatically.
-
-Every option is listed under [Options](#options). `vfs` is the one with no default — [VFS Selection](#vfs-selection) is how to choose it, and a database written through one VFS is not readable through another.
-
-### *client*.read
-
-```typescript
-type User = { id: number; name: string };
-
-const users = await db.read<User>(
-  'SELECT id, name FROM users WHERE active = ?',
-  [1],
-);
-// users: User[]
-```
-
-Read queries are dispatched to any available worker, enabling concurrent reads.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the query. Rejects with `signal.reason`. |
-| `chunkSize` | `number` | `500` | Rows per chunk crossing the worker boundary. Back-pressure grants credits per chunk with a window of 2, so the worker may run up to `2 × chunkSize` rows ahead of the consumer. |
-
-On `read()` this is transport only — it still resolves with the whole array.
-
-### *client*.write
-
-```typescript
-const { affected } = await db.write(
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['Alice', 'alice@example.com'],
-);
-// affected: number of rows inserted
-```
-
-Write queries are serialized through a dedicated writer worker — only one write executes at a time.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the query. Rejects with `signal.reason`. |
-
-### *client*.stream
-
-```typescript
-// Worker is held for the full generator lifetime — always exhaust or break.
-for await (const row of db.stream<User>('SELECT * FROM large_table', [])) {
-  processRow(row); // row is User
-}
-```
-
-`stream()` yields individual rows without buffering the full result set in memory.
-Use `chunk()` to iterate in batches: `for await (const rows of db.chunk(...))`.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the query. Rejects with `signal.reason`. |
-| `chunkSize` | `number` | `500` | Rows per chunk crossing the worker boundary. Back-pressure grants credits per chunk with a window of 2, so the worker may run up to `2 × chunkSize` rows ahead of the consumer. |
-
-On `stream()`, `chunkSize` is the only lever on how many rows are in flight.
-
-### *client*.chunk
-
-```typescript
-// Worker is held for the full generator lifetime — always exhaust or break.
-for await (const rows of db.chunk<User>('SELECT * FROM large_table', [])) {
-  processBatch(rows); // rows is User[]
-}
-```
-
-`chunk()` yields arrays instead of rows. Prefer it over `stream()` when the work
-is per-batch — one `INSERT` per chunk rather than per row.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the query. Rejects with `signal.reason`. |
-| `chunkSize` | `number` | `500` | Rows per chunk crossing the worker boundary. Back-pressure grants credits per chunk with a window of 2, so the worker may run up to `2 × chunkSize` rows ahead of the consumer. |
-
-Here `chunkSize` is the batch size the consumer sees, not only a transport detail.
-
-### *client*.first
-
-```typescript
-const user = await db.first<User>(
-  'SELECT * FROM users WHERE id = ?',
-  [42],
-);
-// user: User | undefined
-```
-
-`first()` returns the first result row, or `undefined` if no rows match. Use it for lookups by primary key or unique field.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the query. Rejects with `signal.reason`. |
-
-`first()` stops the query after one row instead of draining the result set.
-
-### *client*.transaction
-
-```typescript
-const orders = await db.transaction(async (tx) => {
-  await tx.write('INSERT INTO orders (id, total) VALUES (?, ?)', [1, 42]);
-  await tx.write('UPDATE stock SET qty = qty - 1 WHERE id = ?', [7]);
-  const rows = await tx.read<{ n: number }>('SELECT count(*) AS n FROM orders');
-  return rows[0].n;
-});
-```
-
-One worker is held for the callback's whole lifetime, so nothing else can run on
-it: the transaction is genuinely isolated, not merely wrapped in `BEGIN`.
-Returning commits, throwing rolls back and re-throws. `{ readOnly: true }`
-rejects write statements; `{ autoCommit: false }` leaves the commit to you.
-
-`tx` carries the same querying surface as the client — `read`, `write`, `chunk`, `stream`, `first`, `bulkWrite`, `output` — plus `commit` and `rollback`.
-
-`{ signal }` abandons the transaction at any point, including while it waits for a worker and while your callback sits on something that is not a statement. It rolls back and rejects with `signal.reason`, and it never commits — a callback that catches its own statement's rejection cannot commit around the abort. Your callback is not interrupted, but every statement it issues afterwards rejects. `BEGIN`, `COMMIT` and `ROLLBACK` are the exception: they do not carry the signal, so an abort raised while one of them is in flight lands when it settles.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `readOnly` | `boolean` | `false` | Rejects write statements with `READ_ONLY_TRANSACTION`, at the call rather than at the first flush. |
-| `autoCommit` | `boolean` | `true` | Commits when the callback resolves. Set it false to commit or roll back yourself. |
-| `signal` | `AbortSignal` | — | Abandons the transaction. Rolls back and rejects with `signal.reason`; never commits. |
-
-### *client*.bulkWrite
-
-```typescript
-const rows = db.bulkWrite('events', ['id', 'kind', 'at']);
-for (const event of events) rows.enqueue(event);
-const affected = await rows.close();
-```
-
-Batches inserts to stay under SQLite's variable limit (`SQLITE_MAX_VARS`,
-32 766), flushing whenever the next row would cross it. `close()` flushes the
-remainder and resolves with the total number of rows written.
-
-Single-use: `enqueue()` and `close()` throw once closed. A batch that fails
-rejects with a `SQLiteBulkWriteError` carrying `rowsWritten` and `rowsNotWritten` — a
-multi-row INSERT is statement-atomic, so the failing batch wrote nothing.
-
-`bulkWrite()` is not atomic: batches are committed as they flush, so a failure leaves the rows already written in place. Call it on a `tx` if you need all-or-nothing.
-
-Pass `{ signal }` to abort a load. `close()` then rejects with `signal.reason`, and the abort lands **between** batches — never inside one, because a multi-row INSERT is statement-atomic. The batches already written stay written, for the same reason a failure leaves them: an abort stops the load, it does not undo it.
-
-Await `enqueue()` to be slowed to the speed of the database. It resolves immediately while fewer than `queueSize` rows are queued for writing, and only defers beyond that — so a producer that awaits every row never holds more than that many unwritten rows. Ignoring the returned promise is legal and loads exactly as before: the bound is an offer, not a guarantee, and only you can take it. `queueSize` counts rows, not bytes: if your columns carry blobs, set it yourself.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signal` | `AbortSignal` | — | Aborts the load between batches. `close()` rejects with `signal.reason`. |
-| `queueSize` | `number` | 2 batches | Rows queued for writing above which `enqueue()` defers. A batch is `floor(32766 / columns)` rows. |
-
-### *client*.output
-
-```typescript
-const out = db.output(
-  'products',
-  { id: 'INTEGER', name: 'TEXT', price: { type: 'REAL', required: true } },
-  { indexes: ['name', { columns: ['name', 'price'], unique: true }] },
-);
-out.enqueue({ id: 1, name: 'widget', price: 9.99 });
-const affected = await out.close();
-```
-
-Builds a table from a schema declaration and populates it. Rows land in a
-staging table and the swap happens atomically at `close()`, so **the previous
-table stays intact and fully populated until the new one is ready** — a reader
-querying mid-load sees the old data, never a half-filled table. A target that
-did not exist appears only at `close()`. Single-use, like `bulkWrite`.
-
-`output()` takes `{ signal }` too, and an aborted one is observationally a no-op: the staging table is dropped and nothing else is touched. No rename, no partial publication — whatever was in the target before is still there, whole.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `indexes` | `Index[]` | — | Indexes built after the swap, under their final names. A column name, an array of them, or `{ columns, unique }`. |
-| `signal` | `AbortSignal` | — | Aborts the load between batches. `close()` rejects with `signal.reason` and the target is untouched. |
-| `queueSize` | `number` | 2 batches | Rows queued for writing above which `enqueue()` defers. A batch is `floor(32766 / columns)` rows. |
-
-**Inside a transaction, `output()` costs more than it looks.** On its own it loads rows outside any transaction and holds the write lock only for the final swap. Called on a `tx`, the entire load runs inside your transaction — every other write, in this tab and in others, waits for it to finish.
-
-### *client*.close
-
-```typescript
-await db.close();
-```
-
-Drains in-flight work, rejects queued work, closes each database connection, then terminates all workers. The returned promise settles once every worker has closed and been terminated, or once `drainTimeout` has elapsed. Calling `close()` a second time returns the same promise — the operation runs exactly once.
-
-**Stored data is not deleted.** `close()` releases workers and connections; it removes nothing. To remove the database itself, use [`deleteDatabase`](#deletedatabase).
-
-### deleteDatabase
-
-Removes a database and the `-journal` / `-wal` files SQLite may have left beside it. The database must not be open, in this tab or any other.
-
-```typescript
-import { deleteDatabase } from 'browser-sqlite';
-
-await deleteDatabase('myapp.sqlite', { vfs: 'OPFSAdaptiveVFS' });
-```
-
-`vfs` is required and must be the VFS the database was created with: a database written through one VFS is not visible through another, so deleting through the wrong one deletes nothing and reports success. `build` and `wasmUrl` are accepted with the same meaning as on `createSQLiteClient`.
-
-Deleting a database that does not exist is not an error.
-
-What a VFS keeps for itself is left alone — the IndexedDB store shared by every database that VFS holds on this origin, and the `AccessHandlePoolVFS` directory whose files are its reusable capacity. The deleted database's own bytes are freed in both cases.
-
-Throws `SQLiteError` with code `BUSY` when the database is open or being opened, and `TIMEOUT` when the VFS cannot answer within 30 seconds — most often the same cause.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `vfs` | `SQLiteVFS` | — (required) | The VFS the database was created with. Deleting through another one deletes nothing and reports success. |
-| `build` | `SQLiteBuild` | first build the VFS declares | Which wa-sqlite build to load. It does not affect where the database lives — only which builds can instantiate the VFS. |
-| `wasmUrl` | `string \| ((build: SQLiteBuild) => string)` | `undefined` | Same meaning as on [`createSQLiteClient`](#options). A deployment that needs it to open a database needs it to delete one. |
-
-## Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `poolSize` | `number` | `2` | Number of Web Workers spawned in the pool. A larger pool allows more concurrent reads but uses more memory. Must be `1` with `AccessHandlePoolVFS`. |
-| `vfs` | `SQLiteVFS` | — (required) | VFS implementation for storage. See the [VFS Selection](#vfs-selection) table. |
-| `build` | `SQLiteBuild` | first build the VFS declares | Which wa-sqlite WebAssembly build to load: `'sync'`, `'async'`, or `'jspi'`. Throws `INVALID_OPTION` at construction if the VFS does not support it. See [Builds](#builds). |
-| `wasmUrl` | `string \| ((build: SQLiteBuild) => string)` | `undefined` | Where the workers fetch their `.wasm`. Omit it and resolution is unchanged: the files are read from beside `worker.js`. A string is a directory resolved against the page — relative, absolute or a full URL, trailing slash optional. A callback receives the resolved `build` and names one file, for a bundler-emitted asset carrying a content hash. Called once, at construction. Throws `INVALID_OPTION` there if the value is not a URL. Another origin needs CORS and `Content-Type: application/wasm`. |
-| `pragmas` | `Record<string, string>` | `undefined` | SQLite PRAGMAs applied to each worker connection on open. |
-| `maxWorkerRestarts` | `number` | `1` | How many times a slot may be restarted after it dies. The counter resets once a replacement has actually served a request. A slot that fails to open is retried once, but only if another worker did open — when none did, the failure is a configuration error and the client fails immediately rather than retrying. |
-| `openTimeout` | `number` (ms) | `30_000` | How long a worker has to post `ready` after `open` is sent. On expiry the slot is failed — the most common cause is a database held under an exclusive lock by another tab. |
-| `drainTimeout` | `number` (ms) | `60_000` | How long the drain loop may run in the query generator's `finally` before the worker is presumed dead and the crash path is invoked. |
-| `debug` | `string \| boolean` | `undefined` | Enables lifecycle logging. A string value is used as the log prefix; `true` falls back to the client prefix (e.g. `"SQLite 1"`). Only lifecycle events are logged — worker created, ready, open-error, crash, restart, worker lost, close, and skipped staging sweep. No line per query. Off by default, with one exception: a permanently lost worker always warns, because a pool quietly smaller than `poolSize` is not something to discover later. When enabled, `db.debug` also exposes a live introspection state tree for query throughput and worker status. |
-| `onWorkerLost` | `(event: WorkerLostEvent) => void` | `undefined` | Called when a worker is lost for good, with the slot index, how many workers are left, the requested `poolSize`, and the error. Fires before the client fails if it was the last one. A throwing callback is caught and warned about; it cannot break the pool. |
+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
 
@@ -287,212 +41,94 @@ Throws `SQLiteError` with code `BUSY` when the database is open or being opened,
 |---|---|---|
 | 92+ | 95+ | 15.4+ |
 
-## VFS Selection
-
-browser-sqlite delegates storage to a
-[wa-sqlite Virtual File System](https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#readme)
-(VFS).
-
-**`vfs` is required — there is no default.** A VFS decides *where* your database
-is written, so a default that moved between versions would leave you reading an
-empty database while your bytes sat in a store nothing queries.
-
-**Pass `OPFSAdaptiveVFS` unless you have a reason not to.** Across every engine we
-could test — Chrome, Firefox and Safari, desktop and mobile — it opened and passed
-every conformance check without exception. It is the only VFS here of which that is
-true.
-
-> **Each VFS is a separate store.** A database written through one VFS is not
-> visible through another — the bytes are still there, but nothing reads them.
-> Changing `vfs` later does not migrate anything.
+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).
 
-You would leave that choice when you control which browser runs your code — an
-Electron app, a kiosk, a managed fleet — and need something it cannot give you:
-
-| Browser you can guarantee | Concurrent reads | Write-heavy workloads |
-|---|---|---|
-| None — the open web | `OPFSAnyContextVFS` if you can require Safari 26+; otherwise `IDBBatchAtomicVFS` | stay on `OPFSAdaptiveVFS` |
-| Chromium 121+ | already the case | `OPFSWriteAheadVFS` |
-| Firefox 111+ | `OPFSAnyContextVFS` | stay |
-| Safari 26+ / iPadOS 26+ | `OPFSAnyContextVFS` | stay |
-| iOS (iPhone) | none measured to help | stay |
-
-**Concurrent reads** covers both serving a read while a write transaction is open
-and running several reads at once under a pool: a VFS holding one exclusive
-access handle can do neither, because it is the same handle a second worker never
-gets. For how much any of this is worth on your own targets, run
-[the benchmark page](https://lalexdotcom.github.io/browser-sqlite/) — no timings
-appear in this file.
-
-<!-- BEGIN GENERATED VFS TABLE — edit VFS_CAPABILITIES in src/types.ts, then run `pnpm docs:vfs` -->
-
-| VFS | Builds | Browser compatibility | Pool size | Shared between connections | Survives close | Memory |
-|-----|--------|-----------------------|-----------|----------------------------|----------------|--------|
-| `OPFSAdaptiveVFS` **(recommended)** | [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 111+/153+ [(*)](#-reduced-mode)<br>Safari 15.4+/27+ [(*)](#-reduced-mode)<br>Android 109+/?<br>iOS 15.4+/27+ [(*)](#-reduced-mode) | Any | Yes | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `OPFSWriteAheadVFS` | [`sync`](#build-sync), [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 111+/153+ [(*)](#-reduced-mode)<br>Safari 15.4+/27+ [(*)](#-reduced-mode)<br>Android 109+/?<br>iOS 15.4+/27+ [(*)](#-reduced-mode) | Any | Yes | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `OPFSCoopSyncVFS` | [`sync`](#build-sync), [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 111+/153+<br>Safari 15.4+/27+<br>Android 109+/?<br>iOS 15.4+/27+ | Any | Yes | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `AccessHandlePoolVFS` | [`sync`](#build-sync), [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 111+/153+<br>Safari 15.4+/27+<br>Android 109+/?<br>iOS 15.4+/27+ | **1** — it cannot share access handles between connections | No | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `IDBBatchAtomicVFS` | [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 95+/153+<br>Safari 15.4+/27+<br>Android 92+/?<br>iOS 15.4+/27+ | Any | Yes | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `IDBMirrorVFS` | [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 95+/153+<br>Safari 15.4+/27+<br>Android 92+/?<br>iOS 15.4+/27+ | **1** — its pages are mirrored per worker and commits propagate asynchronously, so a larger pool reads stale data or fails outright | No | Yes | **Whole database in RAM**, multiplied by `poolSize` |
-| `OPFSAnyContextVFS` | [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 111+/153+<br>Safari 26+/27+<br>Android 109+/?<br>iOS 26+/27+ | Any | Yes | Yes | Page cache only, bounded by `PRAGMA cache_size` |
-| `MemoryVFS` | [`sync`](#build-sync), [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 95+/153+<br>Safari 15.4+/27+<br>Android 92+/?<br>iOS 15.4+/27+ | **1** — its pages live in the worker that opened them, so a larger pool would open independent databases that diverge silently | No | **No — volatile** | **Whole database in RAM**, multiplied by `poolSize` |
-| `MemoryAsyncVFS` | [`async`](#build-async), [`jspi`](#build-jspi) | Chrome 92+/137+<br>Firefox 95+/153+<br>Safari 15.4+/27+<br>Android 92+/?<br>iOS 15.4+/27+ | **1** — its pages live in the worker that opened them, so a larger pool would open independent databases that diverge silently | No | **No — volatile** | **Whole database in RAM**, multiplied by `poolSize` |
-
-<!-- END GENERATED VFS TABLE -->
-
-The **Browser compatibility** column is derived from documented platform support,
-not from our own test runs. It covers where the VFS stores data; which **builds**
-are reachable on each engine is a separate question, answered under
-[Builds](#builds) — the `Builds` column links straight to the build it names.
-
-#### (*) Reduced mode
-
-The VFS runs on that engine, but without `readwrite-unsafe` access handles: one
-exclusive handle rotated between workers instead of one held per connection. It
-is not a partial failure — `OPFSAdaptiveVFS` passes 102 of 104 browser tests on
-Firefox in exactly that mode.
-
-What it costs is pool concurrency under one specific shape. **On an engine
-without `readwrite-unsafe`, a VFS that rotates a single exclusive OPFS access
-handle cannot serve any other worker while a write transaction holds that
-handle** — the worker that took it does not give it back before the transaction
-ends, and the next acquisition blocks in the scheduler, before an `AbortSignal`
-is ever consulted. That covers `OPFSAdaptiveVFS` in reduced mode.
-`IDBMirrorVFS`, `OPFSAnyContextVFS` and `IDBBatchAtomicVFS` hold no such handle
-and are unaffected.
-
-`OPFSCoopSyncVFS` has the same symptom for a different reason, and it is **not**
-conditional on the engine — it never uses `readwrite-unsafe`, so it is never in
-reduced mode. See [Known Limitations](#known-limitations).
-
-**A long *read* does not produce this effect, except once per worker after a
-write.**
-
-#### `OPFSAnyContextVFS` and wa-sqlite
-
-This VFS needs a patched wa-sqlite to work on Safari. browser-sqlite ships that
-patch inside its own worker bundle — there is nothing for you to install or
-configure.
-
-### Builds
-
-Each VFS runs on one or more wa-sqlite WebAssembly builds. The `build` option
-selects one; omitted, the first build the VFS declares is used — `async` for the
-default VFS. A pair the VFS does not support throws a `SQLiteError` with code
-`INVALID_OPTION` at construction, naming the builds it does support. The pairing
-is declared in one place, `VFS_CAPABILITIES`, which is also what the `SQLiteVFS`
-type is derived from.
-
-A build carries its own engine requirement, independent of where the VFS stores
-data — so a VFS can be reachable in `sync` on an old browser and in `jspi` only
-on a much newer one.
+## Usage
 
-<!-- BEGIN GENERATED BUILD TABLE — edit FEATURE_SUPPORT in scripts/render-vfs-matrix.ts -->
+Read the [detailed API documentation](API.md) for the full description.
 
-#### Build `sync`
+```typescript
+import { createSQLiteClient } from 'browser-sqlite';
 
-| Chrome / Edge | Firefox | Safari | Chrome Android | Safari iOS |
-|---|---|---|---|---|
-| Any | Any | Any | Any | Any |
+const db = createSQLiteClient('myapp.sqlite', { vfs: 'OPFSAdaptiveVFS' });
 
-Plain synchronous WebAssembly. Needs nothing beyond baseline WASM, so it runs anywhere — but only VFS whose file operations are all synchronous can offer it.
+await db.write('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
+await db.write('INSERT INTO users (name) VALUES (?)', ['Alice']);
 
-#### Build `async`
+const users = await db.read<{ id: number; name: string }>('SELECT id, name FROM users');
 
-| Chrome / Edge | Firefox | Safari | Chrome Android | Safari iOS |
-|---|---|---|---|---|
-| Any | Any | Any | Any | Any |
+for await (const row of db.stream<{ id: number; name: string }>('SELECT * FROM users')) {
+  process(row);
+}
 
-Asyncify: the WASM stack is unwound and rewound around asynchronous file operations. Also needs nothing beyond baseline WASM. This is the default, and every VFS here can run on it.
+await db.close();
+```
 
-#### Build `jspi`
+[*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)
 
-| Chrome / Edge | Firefox | Safari | Chrome Android | Safari iOS |
-|---|---|---|---|---|
-| 137+ | 153+ | 27+ | Yes | 27+ |
+[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)
 
-JavaScript Promise Integration — the same asynchrony handled by the engine rather than by Asyncify. Opt-in, and no default uses it, so its narrower availability constrains nobody who does not ask for it.
+## Storage
 
+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.
 
-<!-- END GENERATED BUILD TABLE -->
+`OPFSWriteAheadVFS` and `OPFSAdaptiveVFS` are the recommended options.
 
-## Error handling
+[`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)
 
-Errors raised by this library are instances of `SQLiteError`, exported from the package entry point. Discriminate on `error.code` or `error.name` — they carry the same value, so `err.name` reads the way `'AbortError'` does on a DOM `AbortError`.
+## Guarantees
 
-| Code | When it is thrown |
-|------|------------------|
-| `NOT_A_READ_QUERY` | `read()`, `chunk()`, `stream()`, or `first()` was called with a statement that is not a provably readable query. A bare read pragma (`PRAGMA journal_mode`) is accepted; a pragma that assigns a value or takes an argument must go through `write()`. |
-| `CLIENT_CLOSED` | A query was queued after `close()` was called. |
-| `WORKER_CRASHED` | A pool worker died and the supervisor decided not to restart it. All queued and in-flight work on that slot is rejected. |
-| `TIMEOUT` | A worker did not post `ready` within `openTimeout` milliseconds. The most common cause is a database held under an exclusive lock by another tab or client. |
-| `PROTOCOL_ERROR` | A message was received from a worker that could not be deserialized (`messageerror`). The worker survives; only the in-flight request is rejected. |
-| `BUSY` | SQLite reported a lock conflict (`SQLITE_BUSY` or `SQLITE_LOCKED`); the numeric SQLite code is on `sqliteCode`. The operation is not retried. |
-| `READ_ONLY_TRANSACTION` | raised when a write statement, `bulkWrite()` or `output()` is used inside a transaction opened with `readOnly: true`. |
+### Reads run concurrently
 
-```typescript
-import { SQLiteError } from 'browser-sqlite';
-
-try {
-  await db.write('...');
-} catch (err) {
-  if (err instanceof SQLiteError) {
-    switch (err.code) {
-      case 'WORKER_CRASHED': /* restart or notify */ break;
-      case 'CLIENT_CLOSED':  /* client was shut down */ break;
-    }
-  }
-}
-```
+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.
 
-**Request timeouts.** The library adds no per-request timeout. To bound a query, pass `AbortSignal.timeout(ms)`:
+### Read-your-own-writes
 
-```typescript
-const rows = await db.read('SELECT * FROM large_table', [], {
-  signal: AbortSignal.timeout(5_000),
-});
-```
+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.
 
-**`close()` is async.** Always `await db.close()` — the returned promise settles once every worker has closed its database connection and been terminated. Discarding the promise means the caller cannot tell when teardown is complete.
+The one exception is [`IDBMirrorVFS`](VFS.md#idbmirrorvfs), which does not hold it across
+tabs.
 
-**Read methods reject write statements.** `read()`, `chunk()`, `stream()`, and `first()` reject any statement that is not a provably readable query, throwing `NOT_A_READ_QUERY`. A bare read pragma (`PRAGMA journal_mode`) is accepted; a pragma that assigns a value or takes an argument must go through `write()`.
+### Writes are serialized
 
-**Read-your-own-writes is guaranteed within a tab.** Once a write has resolved,
-any read issued afterwards — from that client or from any other client in the
-same tab on the same database — observes it, 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.
+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.
 
-**It is not guaranteed across tabs.** A write in one tab may not be visible to a
-read in another. No bound is claimed on how long that lasts.
+## Known Limitations
 
-**Nothing serializes writes between clients.** Two clients writing to one
-database concurrently can fail on a lock; the failure surfaces as
-`SQLiteError` with code `BUSY` and `sqliteCode` 5 or 6, and it is **not**
-retried — no `busy_timeout` is applied. This was true before the guarantee
-above existed; it matters now because the guarantee makes several clients on
-one database a reasonable thing to do.
+Some VFS have limitations of their own — see [the detailed VFS page](VFS.md#vfs-reference).
+What follows holds on all of them.
 
-## Requirements
+### Aborting a call
 
-browser-sqlite requires no special HTTP headers. OPFS access handles work in a plain worker context; cross-origin isolation is not needed. The default build needs no browser opt-in; only `build: 'jspi'` does, and that is an unrelated browser constraint, not a header requirement.
+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.
 
-Note: the "Coop" in `OPFSCoopSyncVFS` stands for *cooperative*, not the `Cross-Origin-Opener-Policy` header.
+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).
 
-## Known Limitations
+### Deleting a database
 
-- **`AccessHandlePoolVFS` requires `poolSize: 1`.** Passing `poolSize > 1` with this VFS throws synchronously at client creation time.
-- **`build: 'jspi'` is not available everywhere.** The [`jspi` build table](#build-jspi) carries the per-engine versions; it is generated, so it is the one place that stays current. The build is opt-in and no default uses it, so this constrains nobody who does not ask for it.
-- **`OPFSWriteAheadVFS` buys you nothing outside Chromium.** It opens access handles with `mode: 'readwrite-unsafe'`, which Firefox and Safari do not support — and which they ignore rather than reject, so it still works but falls back to the same reduced mode as `OPFSAdaptiveVFS` and serves no concurrent reads there. On **Safari 27 the `sync` build can also fail to reopen a database** — seen once in three runs, on macOS and on iPadOS. Use `OPFSAdaptiveVFS` outside Chromium.
-- **`OPFSCoopSyncVFS` does not read concurrently, and stalls unpredictably under a pool.** Unlike the other OPFS VFS it implements its own locking and silently ignores the `lockPolicy: 'shared'` this library constructs every VFS with, holding one *exclusive* access handle and rotating it between workers instead of one per connection. A read issued while a write transaction is open is **never served** — the pool acquisition blocks before any `AbortSignal` is consulted — where `IDBBatchAtomicVFS`, `IDBMirrorVFS` and `OPFSAnyContextVFS` serve it every time. A bulk insert either finishes promptly or **exceeds 30 seconds**, with no middle ground and no consistency across runs. None of this depends on `readwrite-unsafe`: unlike the reduced mode described above, it happens on Chromium too.
-- **Read-your-own-writes is guaranteed within a tab, not across tabs.** See the
-  caveat under [Error handling](#error-handling).
-- **Two clients writing at once are not serialized, and what the loser gets depends on the VFS.** Nothing here orders writes between clients or between tabs — SQLite's own locking decides, and it decides differently in the two modes above. Where each connection holds its own access handle, the second writer is refused at once with `BUSY`, and retrying is the remedy; `BEGIN` is deferred, so both transactions open cleanly and it is the first write *inside* that fails. Where one exclusive handle is rotated instead, the second writer is not refused at all — it waits for the file as long as the first one holds it, then goes through. **Pass a `signal` and the two read alike**: an error inside a budget you chose, rather than a wait you did not. **A `bulkWrite` that is refused or abandoned leaves a partial load, not a failed one** — it commits per batch, so everything before is in the database, and one further batch may still land after you gave up: the one already handed to a worker, which no signal can recall. Use `tx.bulkWrite` where you need all or nothing.
-- **A database that is open cannot be deleted**, in this tab or another. `deleteDatabase` takes the same origin-wide lock a client takes while opening, which prevents an open from interleaving with a delete, and reports `BUSY` rather than deleting under a live connection. A connection that already holds its handles cannot be revoked from this library — close every client on the database first.
-- **`deleteDatabase` can time out outside Chromium**, on `OPFSWriteAheadVFS` and `OPFSCoopSyncVFS` — an observation rather than a measured rate. The call fails to settle rather than reporting an error; it has never reported success without deleting. Both VFS rotate a single exclusive OPFS access handle where `readwrite-unsafe` is unavailable, the same shape as the reduced mode described above.
+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.
 
 ## Development
 

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;