browser-sqlite 1.0.0-rc.3

package/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/README.md

@@ -0,0 +1,161 @@
+# browser-sqlite
+
+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.
+
+## Install
+
+```bash
+npm install browser-sqlite
+# or
+pnpm add browser-sqlite
+```
+
+Requires a bundler that supports Web Workers with dynamic imports (Rsbuild, webpack 5, Vite 3+).
+
+## VFS Selection
+
+browser-sqlite delegates storage to a wa-sqlite Virtual File System (VFS). Choose based on browser support and storage requirements:
+
+| 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). |
+
+When `vfs` is omitted, `OPFSPermutedVFS` is used.
+
+For a detailed VFS comparison, see the [wa-sqlite VFS comparison](https://github.com/rhashimoto/wa-sqlite/tree/master/src/examples#vfs-comparison).
+
+## Usage
+
+### Initialize
+
+```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',
+  },
+});
+```
+
+`createSQLiteClient` spawns `poolSize` Web Worker threads immediately. Workers reach READY state asynchronously — queries made before workers are ready are queued automatically.
+
+### 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.
+
+### 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.
+
+### Stream (large result sets)
+
+```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[]
+}
+```
+
+`stream()` yields rows in chunks without buffering the full result set in memory.
+
+### One (first row)
+
+```typescript
+const user = await db.one<User>(
+  'SELECT * FROM users WHERE id = ?',
+  [42],
+);
+// user: User | undefined
+```
+
+`one()` automatically aborts after the first result row. Use it for lookups by primary key or unique field.
+
+### Advanced
+
+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
+
+### Close
+
+```typescript
+db.close();
+```
+
+Terminates all worker threads.
+
+## Requirements
+
+> **These HTTP headers are mandatory.** Without them, `new SharedArrayBuffer()` throws a `SecurityError` and browser-sqlite cannot initialize.
+
+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:
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+### Server configuration examples
+
+**Nginx**
+```nginx
+add_header Cross-Origin-Opener-Policy "same-origin";
+add_header Cross-Origin-Embedder-Policy "require-corp";
+```
+
+**Express**
+```javascript
+app.use((req, res, next) => {
+  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+  next();
+});
+```
+
+**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',
+  },
+},
+```
+
+## Known Limitations
+
+- **`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.

package/dist/esm/index.js

@@ -0,0 +1,424 @@
+import { defer } from "@lalex/promises";
+const FlagsIndexes = {
+    INIT_LOCK: 0
+};
+const WorkerLock = {
+    FREE: 0,
+    LOCKED: 1
+};
+const WorkerStatuses = {
+    EMPTY: -3,
+    NEW: -2,
+    INITIALIZING: -1,
+    INITIALIZED: 0,
+    READY: 10,
+    RESERVED: 49,
+    RUNNING: 50,
+    ABORTING: 99,
+    DONE: 100
+};
+const FLAGS_WORKER_STATUS_OFFSET = Math.max(...Object.values(FlagsIndexes)) + 1;
+class WorkerOrchestrator {
+    sharedArrayBuffer;
+    flags;
+    size;
+    constructor(init){
+        if ('number' == typeof init) this.sharedArrayBuffer = new SharedArrayBuffer((init + FLAGS_WORKER_STATUS_OFFSET) * Int32Array.BYTES_PER_ELEMENT);
+        else this.sharedArrayBuffer = init;
+        this.flags = new Int32Array(this.sharedArrayBuffer);
+        if ('number' == typeof init) {
+            this.size = init;
+            this.flags[FlagsIndexes.INIT_LOCK] = WorkerLock.FREE;
+            this.flags.fill(WorkerStatuses.EMPTY, FLAGS_WORKER_STATUS_OFFSET);
+        } else this.size = init.byteLength / Int32Array.BYTES_PER_ELEMENT - FLAGS_WORKER_STATUS_OFFSET;
+    }
+    lock() {
+        while(Atomics.compareExchange(this.flags, FlagsIndexes.INIT_LOCK, WorkerLock.FREE, WorkerLock.LOCKED) !== WorkerLock.FREE)Atomics.wait(this.flags, FlagsIndexes.INIT_LOCK, WorkerLock.LOCKED);
+    }
+    unlock() {
+        if (Atomics.compareExchange(this.flags, FlagsIndexes.INIT_LOCK, WorkerLock.LOCKED, WorkerLock.FREE) === WorkerLock.LOCKED) Atomics.notify(this.flags, FlagsIndexes.INIT_LOCK, 1);
+    }
+    setStatus(index, status, from) {
+        let oldValue;
+        const workerStatusIndex = index + FLAGS_WORKER_STATUS_OFFSET;
+        if (void 0 !== from) {
+            if (Atomics.compareExchange(this.flags, workerStatusIndex, from, status) === from) oldValue = from;
+        } else {
+            const oldStatus = Atomics.exchange(this.flags, workerStatusIndex, status);
+            if (oldStatus !== status) oldValue = oldStatus;
+        }
+        const success = void 0 !== oldValue;
+        return success;
+    }
+    getStatus(index) {
+        return Atomics.load(this.flags, index + FLAGS_WORKER_STATUS_OFFSET);
+    }
+}
+const isWriteQuery = (sql)=>/(INSERT|REPLACE|UPDATE|DELETE|CREATE|DROP|PRAGMA|ATTACH|DETACH)\s/gim.test(sql);
+const DEFAULT_POOL_SIZE = 2;
+let clientCount = 0;
+const DEFAULT_VFS = 'OPFSPermutedVFS';
+const createSQLiteClient = (file, clientOptions)=>{
+    const clientIndex = ++clientCount;
+    const clientPrefix = `${clientOptions?.name ?? 'SQLite'} ${clientIndex}`;
+    const poolSize = clientOptions?.poolSize ?? DEFAULT_POOL_SIZE;
+    const pool = [];
+    const orchestrator = new WorkerOrchestrator(poolSize);
+    const vfs = clientOptions?.vfs ?? DEFAULT_VFS;
+    if ('AccessHandlePoolVFS' === vfs && poolSize > 1) throw new Error('AccessHandlePoolVFS does not support pool sizes greater than 1');
+    const { state: debug, createRequestDebugState, createWorkerDebugState, createQueryDebugState } = {};
+    const createWorker = ()=>{
+        const deferredInit = defer();
+        const workerName = `${clientPrefix} / Worker ${pool.length + 1}`;
+        const index = pool.push(new Worker(new URL('./worker.ts', import.meta.url), {
+            name: workerName
+        })) - 1;
+        const worker = Object.assign(pool[index], {
+            index,
+            available: false
+        });
+        const state = createWorkerDebugState?.(index, workerName);
+        let currentCallId = 0;
+        let deferredChunk;
+        worker.onmessage = ({ data })=>{
+            const { callId, type } = data;
+            if (0 === callId && 'ready' === type) {
+                worker.available = true;
+                if (state) state.initializationTime = Date.now();
+                deferredInit.resolve(worker);
+            }
+            if (deferredChunk && callId === currentCallId) switch(type){
+                case 'chunk':
+                    if (state?.currentRequest?.currentQuery) state.currentRequest.currentQuery.firstRowTime ??= Date.now();
+                    deferredChunk.resolve(data.data);
+                    deferredChunk = defer();
+                    break;
+                case 'done':
+                    {
+                        const affected = data.affected;
+                        if (state?.currentRequest?.currentQuery) {
+                            state.currentRequest.currentQuery.affectedRows = affected;
+                            state.currentRequest.affectedRows += affected;
+                            state.currentRequest.currentQuery.endTime = Date.now();
+                        }
+                        deferredChunk.resolve(affected);
+                        deferredChunk = void 0;
+                        break;
+                    }
+                case 'error':
+                    {
+                        const error = new Error(data.message, {
+                            cause: data.cause
+                        });
+                        if (state?.currentRequest?.currentQuery) {
+                            state.currentRequest.currentQuery.error = error;
+                            state.currentRequest.currentQuery.endTime = Date.now();
+                        }
+                        deferredChunk.reject(error);
+                        deferredChunk = void 0;
+                        break;
+                    }
+            }
+        };
+        const query = async function*(sql, params, options) {
+            try {
+                worker.available = false;
+                if (deferredChunk) {
+                    console.error(`Previous query not finished on worker ${index + 1}`);
+                    throw new Error('Worker is already processing a query');
+                }
+                if (state?.currentRequest) {
+                    const queryState = createQueryDebugState?.(index, sql, params);
+                    state.currentRequest.currentQuery = queryState;
+                }
+                const { chunkSize = 500, signal } = options ?? {};
+                const signalAbortHandler = ()=>{
+                    orchestrator.setStatus(index, WorkerStatuses.ABORTING, WorkerStatuses.RUNNING);
+                };
+                signal?.addEventListener('abort', signalAbortHandler);
+                deferredChunk = defer();
+                worker.postMessage({
+                    type: 'query',
+                    callId: ++currentCallId,
+                    sql,
+                    params,
+                    options: {
+                        chunkSize
+                    }
+                });
+                while(deferredChunk){
+                    const chunk = await deferredChunk.promise;
+                    yield chunk;
+                }
+                signal?.removeEventListener('abort', signalAbortHandler);
+            } finally{
+                deferredChunk = void 0;
+                worker.available = true;
+            }
+        };
+        Object.assign(worker, {
+            query
+        });
+        worker.postMessage({
+            callId: 0,
+            type: 'open',
+            file,
+            flags: orchestrator.sharedArrayBuffer,
+            index,
+            vfs,
+            pragmas: clientOptions?.pragmas
+        });
+        return deferredInit.promise;
+    };
+    const readerRequestQueue = [];
+    const writerRequestQueue = [];
+    let currentWriterIndex = -1;
+    const acquireWorker = (write = false)=>{
+        if (write && currentWriterIndex > -1) {
+            const writer = pool[currentWriterIndex];
+            if (writer.available) return writer;
+            return;
+        }
+        const availableWorker = pool.find((w)=>{
+            if (w.available) return true;
+            return false;
+        });
+        if (availableWorker && write) currentWriterIndex = availableWorker.index;
+        return availableWorker;
+    };
+    const acquireNextWorker = async (write = false)=>{
+        const availableWorker = acquireWorker(write);
+        if (availableWorker) {
+            availableWorker.available = false;
+            return availableWorker;
+        }
+        const { promise, resolve } = defer();
+        if (write) {
+            if (debug) debug.queue.write++;
+            writerRequestQueue.push((worker)=>{
+                worker.available = false;
+                resolve(worker);
+            });
+        } else {
+            if (debug) debug.queue.read++;
+            readerRequestQueue.push((worker)=>{
+                worker.available = false;
+                resolve(worker);
+            });
+        }
+        return promise;
+    };
+    const getNextAvailableWorker = async (write = false)=>{
+        const requestState = createRequestDebugState?.();
+        const availableWorker = await acquireNextWorker(write);
+        requestState?.assign(availableWorker.index);
+        return pool[availableWorker.index];
+    };
+    const releaseWorker = (worker)=>{
+        const requestState = debug?.workers[worker.index]?.currentRequest;
+        if (requestState) requestState.releaseTime = Date.now();
+        if (writerRequestQueue.length) {
+            if (currentWriterIndex === worker.index || -1 === currentWriterIndex) {
+                if (debug) debug.queue.write--;
+                writerRequestQueue.shift()?.(worker);
+                return;
+            }
+        }
+        if (readerRequestQueue.length) {
+            if (currentWriterIndex === worker.index) currentWriterIndex = -1;
+            if (debug) debug.queue.read--;
+            readerRequestQueue.shift()?.(worker);
+            return;
+        }
+        orchestrator.setStatus(worker.index, WorkerStatuses.READY);
+    };
+    const readWorker = async (worker, sql, params, options)=>{
+        const result = [];
+        for await (const chunk of worker.query(sql, params, options))if ('number' != typeof chunk) result.push(...chunk);
+        return result;
+    };
+    const read = async (sql, params, options)=>{
+        const worker = await getNextAvailableWorker(isWriteQuery(sql));
+        try {
+            return await readWorker(worker, sql, params, options);
+        } finally{
+            releaseWorker(worker);
+        }
+    };
+    const streamWorker = async function*(worker, sql, params, options) {
+        for await (const chunk of worker.query(sql, params, options))if ('number' != typeof chunk) yield chunk;
+    };
+    const stream = async function*(sql, params, options) {
+        const worker = await getNextAvailableWorker(isWriteQuery(sql));
+        try {
+            for await (const chunk of streamWorker(worker, sql, params, options))yield chunk;
+        } finally{
+            releaseWorker(worker);
+        }
+    };
+    const writeWorker = async (worker, sql, params, options)=>{
+        const result = [];
+        let affected = 0;
+        for await (const chunk of worker.query(sql, params, options))if ('number' != typeof chunk) result.push(...chunk);
+        else affected = chunk;
+        return {
+            result,
+            affected
+        };
+    };
+    const write = async (sql, params, options)=>{
+        const worker = await getNextAvailableWorker(isWriteQuery(sql));
+        try {
+            return await writeWorker(worker, sql, params, options);
+        } finally{
+            releaseWorker(worker);
+        }
+    };
+    const oneWorker = async (worker, sql, params, options)=>{
+        let result;
+        const abortController = new AbortController();
+        for await (const chunk of streamWorker(worker, sql, params, {
+            ...options,
+            signal: abortController.signal,
+            chunkSize: 1
+        })){
+            result = chunk[0];
+            abortController.abort();
+            break;
+        }
+        return result;
+    };
+    const one = async (sql, params, options)=>{
+        const worker = await getNextAvailableWorker(isWriteQuery(sql));
+        try {
+            return await oneWorker(worker, sql, params, options);
+        } finally{
+            releaseWorker(worker);
+        }
+    };
+    const bulkWrite = (table, keys)=>{
+        const SQLITE_MAX_VARS = 32766;
+        const maxBufferSize = Math.floor(SQLITE_MAX_VARS / keys.length);
+        const buffer = [];
+        let writePromise = Promise.resolve(0);
+        const flush = ()=>{
+            const toInsert = [
+                ...buffer
+            ];
+            buffer.length = 0;
+            writePromise = writePromise.then((currentAffected)=>write(`INSERT INTO ${table} (${keys.join(',')}) VALUES ${toInsert.map(()=>`(${keys.map(()=>'?')})`)}`, toInsert.flatMap((data)=>keys.map((k)=>data[k]))).then(({ affected: chunkAffected })=>currentAffected + chunkAffected));
+        };
+        return {
+            enqueue: (data)=>{
+                buffer.push(data);
+                if (buffer.length >= maxBufferSize) flush();
+            },
+            close: ()=>{
+                if (buffer.length) flush();
+                return writePromise;
+            }
+        };
+    };
+    const output = (table, schema, options)=>{
+        const { enqueue, close } = bulkWrite(table, Object.keys(schema).filter((col)=>'object' != typeof schema[col] || !schema[col].generated));
+        const normalizedSchema = Object.entries(schema).map(([k, v])=>{
+            const type = 'string' == typeof v ? v : v.type;
+            const unique = 'object' == typeof v && !!v.unique;
+            const notnull = 'object' == typeof v && !!v.required;
+            const generated = 'object' == typeof v ? v.generated : void 0;
+            return {
+                name: k,
+                type,
+                unique,
+                notnull,
+                generated
+            };
+        });
+        const createTablePromise = write(`
+			DROP TABLE IF EXISTS ${table}
+		`).then(async ()=>{
+            await write(`
+				CREATE ${options?.temp ? 'TEMPORARY' : ''} TABLE ${table}(
+					${normalizedSchema.map(({ name, type, unique, notnull, generated })=>`${name} ${type} ${unique ? 'UNIQUE' : ''} ${notnull ? 'NOT NULL' : ''} ${generated ? `GENERATED ALWAYS AS ${generated}` : ''}`).join(',')}
+				)
+			`);
+        });
+        return {
+            enqueue: (data)=>{
+                createTablePromise.then(()=>enqueue(data));
+            },
+            close: ()=>createTablePromise.then(()=>close()).then(async (affected)=>{
+                    if (options?.indexes) for (const index of options.indexes){
+                        const columns = 'string' == typeof index ? [
+                            index
+                        ] : Array.isArray(index) ? index : 'object' == typeof index ? 'column' in index ? [
+                            index.column
+                        ] : index.columns : void 0;
+                        const unique = !Array.isArray(index) && 'object' == typeof index && !!index.unique;
+                        if (columns) await write(`CREATE ${unique ? 'UNIQUE' : ''} INDEX IF NOT EXISTS ${table}_${columns.join('_')}_${unique ? 'U' : 'IDX'} ON ${table}(${columns.join(',')})`);
+                    }
+                    return affected;
+                })
+        };
+    };
+    const transaction = async (callback, options)=>{
+        const { readOnly = false, autoCommit = true } = options ?? {};
+        const worker = await getNextAvailableWorker(!readOnly);
+        const checksql = (sql)=>{
+            if (readOnly && isWriteQuery(sql)) throw new Error('Cannot werite in read-only transaction');
+            return sql;
+        };
+        let done = false;
+        const db = {
+            read: (sql, ...args)=>readWorker(worker, checksql(sql), ...args),
+            write: (sql, ...args)=>writeWorker(worker, checksql(sql), ...args),
+            stream: (sql, ...args)=>streamWorker(worker, checksql(sql), ...args),
+            one: (sql, ...args)=>oneWorker(worker, checksql(sql), ...args),
+            commit: async ()=>{
+                done = true;
+                await oneWorker(worker, 'COMMIT');
+            },
+            rollback: async ()=>{
+                done = true;
+                await oneWorker(worker, 'ROLLBACK');
+            }
+        };
+        try {
+            await db.read('BEGIN');
+            const result = await callback(db);
+            if (!done) if (autoCommit) await db.commit();
+            else await db.rollback();
+            return result;
+        } catch (e) {
+            await db.rollback();
+            throw e;
+        } finally{
+            releaseWorker(worker);
+        }
+    };
+    const close = ()=>{
+        let worker = pool.shift();
+        while(void 0 !== worker){
+            worker.terminate();
+            worker = pool.shift();
+        }
+    };
+    Promise.all(Array.from({
+        length: poolSize
+    }).map(()=>createWorker().then((worker)=>worker))).then((allWorkers)=>{
+        for (const worker of allWorkers)releaseWorker(worker);
+    });
+    const api = {
+        read,
+        write,
+        stream,
+        one,
+        transaction,
+        bulkWrite,
+        output,
+        close,
+        debug
+    };
+    return api;
+};
+export { createSQLiteClient };

package/dist/esm/rslib.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@rslib/core").RslibConfig;
+export default _default;

package/dist/esm/rstest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@rstest/core").RstestConfig;
+export default _default;

package/dist/esm/src/client.d.ts

@@ -0,0 +1,332 @@
+import type { SQLiteVFS } from './types';
+/**
+ * Configuration options for creating a SQLite client.
+ */
+export type CreateSQLiteClientOptions = {
+    /**
+     * Database file name within the OPFS origin private file system.
+     * Each unique name maps to a distinct SQLite database file.
+     * @defaultValue `"SQLite"` prefix + auto-incremented client index
+     */
+    name?: string;
+    /**
+     * Number of Web Workers spawned in the pool at initialization.
+     * A larger pool allows more concurrent read operations but increases
+     * memory consumption and OPFS file handle usage.
+     * Must be `1` when using `AccessHandlePoolVFS` — any larger value throws at construction time.
+     * @defaultValue `2`
+     */
+    poolSize?: number;
+    /**
+     * Virtual File System implementation used for SQLite storage.
+     * Controls whether data is stored in OPFS, IndexedDB, or memory.
+     * See the README VFS Selection guide for a comparison.
+     * @defaultValue `'OPFSPermutedVFS'`
+     */
+    vfs?: SQLiteVFS;
+    /**
+     * SQLite PRAGMAs applied to each worker's database connection on open.
+     * Keys are PRAGMA names, values are their string representations.
+     * Example: `{ journal_mode: 'WAL', synchronous: 'NORMAL' }`.
+     * If omitted, no PRAGMAs are applied beyond SQLite defaults.
+     */
+    pragmas?: Record<string, string>;
+};
+/**
+ * Query execution options.
+ */
+type SQLiteQueryOptions<_T extends Record<string, unknown>> = {
+    id?: string;
+    chunkSize?: number;
+    signal?: AbortSignal;
+    debug?: string;
+};
+type SQLiteStreamOptions<T extends Record<string, unknown>> = SQLiteQueryOptions<T> & {
+    signal?: AbortSignal;
+};
+/**
+ * Main SQLite database API.
+ */
+export type SQLiteDB = {
+    /**
+     * Executes a SELECT query and returns all matching rows as an array.
+     *
+     * Read queries are dispatched to any available worker in the pool,
+     * enabling concurrent execution across multiple readers.
+     *
+     * @param sql - SQL query string. Must be a SELECT (or equivalent read) statement.
+     * @param params - Positional parameters bound to `?` placeholders.
+     * @param options - Optional query options (`chunkSize`, `signal`, `id`).
+     * @returns Promise resolving to an array of typed rows (`T[]`). Returns `[]` for empty results.
+     */
+    read: <T extends Record<string, unknown>>(sql: string, params?: any[], options?: SQLiteQueryOptions<T>) => Promise<T[]>;
+    /**
+     * Executes a DML or DDL statement (INSERT, UPDATE, DELETE, CREATE, DROP, etc.)
+     * and returns both any result rows and the number of affected rows.
+     *
+     * Write queries are serialized through a single dedicated writer worker.
+     * Concurrent writes queue behind each other — only one write executes at a time.
+     *
+     * @param sql - SQL statement. Any statement recognized as a write by `isWriteQuery`.
+     * @param params - Positional parameters bound to `?` placeholders.
+     * @param options - Optional query options (`chunkSize`, `signal`, `id`).
+     * @returns Promise resolving to `{ result: T[], affected: number }` where
+     *   `affected` is the SQLite `changes()` count for the statement.
+     */
+    write: <T extends Record<string, unknown>>(sql: string, params?: any[], options?: SQLiteQueryOptions<T>) => Promise<{
+        result: T[];
+        affected: number;
+    }>;
+    /**
+     * Executes a query and yields result rows in chunks via an async generator.
+     * Memory-efficient for large result sets — rows are not buffered in full.
+     *
+     * @remarks
+     * **Worker held for full generator lifetime.** A pool worker is acquired when
+     * the generator is created and released only when the generator is fully
+     * exhausted or the caller uses `break`. Failing to exhaust the generator
+     * starves the pool. Always use `for await...of` to completion or `break` to exit.
+     *
+     * @param sql - SQL query string.
+     * @param params - Positional parameters bound to `?` placeholders.
+     * @param options - Optional options including `chunkSize` (default `500`),
+     *   `signal` (AbortSignal to cancel), and `id`.
+     * @returns AsyncGenerator yielding `T[]` chunks of at most `chunkSize` rows.
+     */
+    stream: <T extends Record<string, unknown>>(sql: string, params?: any[], options?: SQLiteStreamOptions<T>) => AsyncGenerator<T[]>;
+    /**
+     * Executes a query and returns the first row, or `undefined` if no rows match.
+     * Internally uses `chunkSize: 1` and aborts after the first result chunk.
+     *
+     * @remarks
+     * Intended for SELECT queries. Using `one()` with a write statement (INSERT, UPDATE)
+     * routes to the write worker and still executes the DML — use `write()` for mutations.
+     *
+     * @param sql - SQL query string.
+     * @param params - Positional parameters bound to `?` placeholders.
+     * @param options - Optional query options (`id`). `chunkSize` and `signal` are managed internally.
+     * @returns Promise resolving to the first row as `T`, or `undefined` if no rows.
+     */
+    one: <T extends Record<string, unknown>>(sql: string, params?: any[], options?: SQLiteQueryOptions<T>) => Promise<T | undefined>;
+    /**
+     * Executes a callback within a SQLite transaction, providing a scoped
+     * `TransactionDB` with `read`, `write`, `stream`, and `one` methods.
+     *
+     * The worker is held exclusively for the transaction's duration.
+     * On callback success: auto-commits if `autoCommit` is `true` (default).
+     * On callback error: rolls back automatically.
+     * The callback may call `db.commit()` or `db.rollback()` manually.
+     *
+     * @param callback - Async function receiving a `TransactionDB` instance.
+     * @param options - `readOnly` (default `false`) prevents write statements;
+     *   `autoCommit` (default `true`) commits on callback success.
+     * @returns Promise resolving to the value returned by `callback`.
+     */
+    transaction: <T = void>(callback: (db: any) => Promise<T>, options?: {
+        readOnly?: boolean;
+        autoCommit?: boolean;
+    }) => Promise<T>;
+    /**
+     * Creates a buffered bulk-insert utility that batches rows to stay within
+     * SQLite's variable limit (`SQLITE_MAX_VARS = 32766`).
+     *
+     * Call `enqueue()` for each row to insert, then `close()` to flush the
+     * remaining buffer and await completion.
+     *
+     * @param table - Target table name.
+     * @param keys - Column names for the INSERT statement.
+     * @returns Object with:
+     *   - `enqueue(data)` — buffers a row, flushing automatically when the buffer fills.
+     *   - `close()` — flushes remaining rows and resolves with total affected row count.
+     */
+    bulkWrite: <KEYS extends string>(table: string, keys: KEYS[]) => {
+        enqueue: (data: Record<KEYS, any>) => void;
+        close: () => Promise<number>;
+    };
+    /**
+     * Schema-driven table replacement: drops the existing table, creates a new one
+     * from the provided schema, bulk-inserts all enqueued rows, then creates indexes.
+     *
+     * Useful for full-refresh ETL patterns where a table is rebuilt from scratch.
+     *
+     * @param table - Table name to drop and recreate.
+     * @param schema - Column definition map. Values are SQL type strings or
+     *   objects with `{ type, required?, unique?, generated? }`.
+     * @param options - `indexes` array and `temp` flag for TEMPORARY tables.
+     * @returns Object with `enqueue(data)` and `close()` following the same
+     *   contract as {@link SQLiteDB.bulkWrite}.
+     */
+    output: <SCHEMA extends Record<string, any>>(table: string, schema: SCHEMA, options?: any) => {
+        enqueue: (data: any) => void;
+        close: () => Promise<number>;
+    };
+    /**
+     * Terminates all workers in the pool.
+     *
+     * @remarks
+     * **OPFS files are NOT deleted.** `close()` calls `worker.terminate()` on each
+     * pool worker — it does not remove any OPFS database files. Files created by
+     * browser-sqlite persist in the origin's private file system across page loads.
+     * To delete OPFS files, use the `navigator.storage.getDirectory()` API directly.
+     */
+    close: () => void;
+    /**
+     * Internal diagnostic handle. Not part of the stable public API.
+     * Shape is subject to change without notice.
+     * @internal
+     */
+    debug: unknown;
+};
+/**
+ * Creates a SQLite client backed by a pool of Web Workers, each running
+ * a wa-sqlite instance in a dedicated thread.
+ *
+ * @remarks
+ * **Browser requirements (COOP/COEP):** This function constructs a
+ * `SharedArrayBuffer` for cross-thread worker synchronization. Browsers
+ * require the page to be served with the following HTTP headers:
+ * ```
+ * Cross-Origin-Opener-Policy: same-origin
+ * Cross-Origin-Embedder-Policy: require-corp
+ * ```
+ * Without these headers, `new SharedArrayBuffer()` throws a `SecurityError`
+ * and the pool will never initialize.
+ *
+ * **Worker pool side effect:** Calling this function immediately spawns
+ * `poolSize` Web Worker threads and begins asynchronous database
+ * initialization. Workers become queryable once they emit a `ready` message.
+ *
+ * @param file - SQLite database file name within the OPFS origin.
+ *   Each distinct name corresponds to a separate database file.
+ * @param clientOptions - Optional pool and VFS configuration.
+ *   See {@link CreateSQLiteClientOptions} for field defaults.
+ * @returns A {@link SQLiteDB} object providing `read`, `write`, `stream`,
+ *   `one`, `transaction`, `bulkWrite`, `output`, and `close` methods.
+ *
+ * @throws {Error} When `vfs` is `'AccessHandlePoolVFS'` and `poolSize` is
+ *   greater than `1`. AccessHandlePoolVFS does not support concurrent access
+ *   handles — set `poolSize: 1` explicitly when using this VFS.
+ *
+ * @example
+ * ```typescript
+ * import { createSQLiteClient } from 'browser-sqlite';
+ *
+ * const db = createSQLiteClient('myapp.sqlite', {
+ *   poolSize: 3,
+ *   vfs: 'OPFSPermutedVFS',
+ *   pragmas: { journal_mode: 'WAL', synchronous: 'NORMAL' },
+ * });
+ *
+ * const users = await db.read<{ id: number; name: string }>(
+ *   'SELECT id, name FROM users WHERE active = ?',
+ *   [1],
+ * );
+ * ```
+ */
+export declare const createSQLiteClient: (file: string, clientOptions?: CreateSQLiteClientOptions) => {
+    read: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions<T>) => Promise<T[]>;
+    write: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions<T>) => Promise<{
+        result: T[];
+        affected: number;
+    }>;
+    stream: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions<T>) => AsyncGenerator<T[], void, unknown>;
+    one: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: Omit<SQLiteQueryOptions<T>, "chunkSize" | "signal">) => Promise<T | undefined>;
+    transaction: <T = void>(callback: (db: Pick<SQLiteDB, "one" | "read" | "write" | "stream"> & {
+        commit: () => Promise<void>;
+        rollback: () => Promise<void>;
+    }) => Promise<T>, options?: {
+        readOnly?: boolean;
+        autoCommit?: boolean;
+    }) => Promise<T>;
+    bulkWrite: <KEYS extends string>(table: string, keys: KEYS[]) => {
+        enqueue: (data: { [K in KEYS]: any; }) => void;
+        close: () => Promise<number>;
+    };
+    output: <SCHEMA extends Record<string, string | {
+        type: string;
+        generated?: string;
+        required?: boolean;
+        unique?: boolean;
+    }>>(table: string, schema: SCHEMA, options?: {
+        indexes?: (keyof SCHEMA | (keyof SCHEMA)[] | ({
+            unique?: boolean;
+        } & ({
+            column: keyof SCHEMA;
+        } | {
+            columns: (keyof SCHEMA)[];
+        })))[] | undefined;
+        temp?: boolean;
+    }) => {
+        enqueue: (data: { [K in keyof SCHEMA as SCHEMA[K] extends {
+            generated: string;
+        } ? never : K]: any; }) => void;
+        close: () => Promise<number>;
+    };
+    close: () => void;
+    debug: {
+        readonly file: string;
+        readonly vfs: SQLiteVFS;
+        readonly pragmas: Record<string, string>;
+        readonly name: string;
+        readonly queue: {
+            write: number;
+            read: number;
+        };
+        workers: {
+            index: number;
+            name: string;
+            creationTime: number;
+            initializationTime?: number;
+            requests: {
+                startTime: number;
+                acquireTime?: number;
+                releaseTime?: number;
+                affectedRows: number;
+                queries: {
+                    sql: string;
+                    params?: any[];
+                    startTime: number;
+                    firstRowTime?: number;
+                    endTime?: number;
+                    error?: any;
+                    affectedRows: number;
+                }[];
+                currentQuery?: {
+                    sql: string;
+                    params?: any[];
+                    startTime: number;
+                    firstRowTime?: number;
+                    endTime?: number;
+                    error?: any;
+                    affectedRows: number;
+                };
+            }[];
+            currentRequest?: {
+                startTime: number;
+                acquireTime?: number;
+                releaseTime?: number;
+                affectedRows: number;
+                queries: {
+                    sql: string;
+                    params?: any[];
+                    startTime: number;
+                    firstRowTime?: number;
+                    endTime?: number;
+                    error?: any;
+                    affectedRows: number;
+                }[];
+                currentQuery?: {
+                    sql: string;
+                    params?: any[];
+                    startTime: number;
+                    firstRowTime?: number;
+                    endTime?: number;
+                    error?: any;
+                    affectedRows: number;
+                };
+            };
+            readonly status: string;
+        }[];
+    };
+};
+export {};

package/dist/esm/src/debug.d.ts

@@ -0,0 +1,52 @@
+import type { CreateSQLiteClientOptions } from './client';
+import { type WorkerOrchestrator } from './orchestrator';
+import type { SQLiteVFS } from './types';
+export declare const debugSQLQuery: (sql: string, params?: any[]) => string;
+export declare const statusToLabel: (status: number) => string;
+type QueryDebugState = {
+    sql: string;
+    params?: any[];
+    startTime: number;
+    firstRowTime?: number;
+    endTime?: number;
+    error?: any;
+    affectedRows: number;
+};
+type RequestDebugState = {
+    startTime: number;
+    acquireTime?: number;
+    releaseTime?: number;
+    affectedRows: number;
+    queries: QueryDebugState[];
+    currentQuery?: QueryDebugState;
+};
+type WorkerDebugState = {
+    index: number;
+    name: string;
+    creationTime: number;
+    initializationTime?: number;
+    requests: RequestDebugState[];
+    currentRequest?: RequestDebugState;
+    readonly status: string;
+};
+type ClientDebugState = {
+    readonly file: string;
+    readonly vfs: SQLiteVFS;
+    readonly pragmas: Record<string, string>;
+    readonly name: string;
+    readonly queue: {
+        write: number;
+        read: number;
+    };
+    workers: WorkerDebugState[];
+};
+export declare const createClientDebug: (file: string, orchestrator: WorkerOrchestrator, clientOptions: Required<Pick<CreateSQLiteClientOptions, "vfs" | "pragmas" | "name">>) => {
+    readonly state: ClientDebugState;
+    readonly createWorkerDebugState: (index: number, name: string) => WorkerDebugState;
+    readonly createRequestDebugState: () => {
+        state: RequestDebugState;
+        assign: (index: number) => void;
+    };
+    readonly createQueryDebugState: (workerIndex: number, sql: string, params?: any[]) => QueryDebugState;
+};
+export {};

package/dist/esm/src/index.d.ts

@@ -0,0 +1 @@
+export * from './client';

package/dist/esm/src/orchestrator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Worker orchestrator for SQLite worker pool synchronization.
+ *
+ * Responsibilities:
+ * - Establish an initialization lock to serialize worker database initialization
+ * - Track worker status transitions throughout their lifecycle
+ */
+export declare const WorkerStatuses: {
+    readonly EMPTY: -3;
+    readonly NEW: -2;
+    readonly INITIALIZING: -1;
+    readonly INITIALIZED: 0;
+    readonly READY: 10;
+    readonly RESERVED: 49;
+    readonly RUNNING: 50;
+    readonly ABORTING: 99;
+    readonly DONE: 100;
+};
+export type WorkerStatus = (typeof WorkerStatuses)[keyof typeof WorkerStatuses];
+/**
+ * Worker pool orchestrator using SharedArrayBuffer for cross-thread synchronization.
+ *
+ * Key features:
+ * - Serializes worker initialization via an atomic lock to prevent database conflicts
+ * - Tracks individual worker status using atomic operations for thread-safe state management
+ *
+ * @remarks
+ * **Worker lifecycle state machine (per slot):**
+ *
+ * ```
+ * EMPTY (-3)         — slot allocated; Worker object not yet created by client.ts
+ *    │
+ * NEW (-2)           — Worker thread started; 'open' message not yet sent
+ *    │
+ * INITIALIZING (-1)  — 'open' message sent; worker calling orchestrator.lock()
+ *    │                  to serialize VFS + SQLite DB initialization across the pool
+ * INITIALIZED (0)    — DB opened; orchestrator.unlock() called; about to post 'ready'
+ *    │
+ * READY (10)         — worker available for queries; pool is queryable from client.ts
+ *    │
+ * RUNNING (50)       — worker executing a query (set by worker.ts via Atomics)
+ *    │
+ * ABORTING (99)      — AbortSignal fired; worker.ts checks this flag in the step loop
+ *    │                  and exits early; transitions to DONE after the current step
+ * DONE (100)         — query finished (normal or aborted); client calls releaseWorker()
+ *                       which sets status back to READY via setStatus()
+ * ```
+ *
+ * Note: `RESERVED (49)` is defined but intentionally unused in v1.
+ * The `INITIALIZED (0)` state is transient — the worker moves to `READY` atomically
+ * inside the `finally` block of `open()` in `worker.ts`.
+ */
+export declare class WorkerOrchestrator {
+    readonly sharedArrayBuffer: SharedArrayBuffer;
+    private flags;
+    readonly size: number;
+    /**
+     * Creates a new orchestrator instance.
+     * @param init - Pool size (creates new SharedArrayBuffer) or existing SharedArrayBuffer
+     */
+    constructor(init: number | SharedArrayBuffer);
+    /**
+     * Acquire initialization lock.
+     * Workers call this during startup to serialize database initialization.
+     * Uses busy-wait with Atomics.wait() for blocking.
+     */
+    lock(): void;
+    /**
+     * Release initialization lock.
+     * Notifies one waiting worker that the lock is now available.
+     */
+    unlock(): void;
+    /**
+     * Update worker status atomically.
+     * @param index - Worker index in the pool
+     * @param status - New status to set
+     * @param from - Optional: expected current status for conditional update (CAS)
+     * @returns true if status was successfully updated
+     */
+    setStatus(index: number, status: WorkerStatus, from?: WorkerStatus): boolean;
+    /**
+     * Get current worker status.
+     * @param index - Worker index in the pool
+     * @returns Current worker status
+     */
+    getStatus(index: number): WorkerStatus;
+}

package/dist/esm/src/types.d.ts

@@ -0,0 +1,83 @@
+export type SQLiteClientCallData = {
+    type: 'open';
+    file: string;
+    workerIndex: number;
+    url?: string;
+    flag: SharedArrayBuffer;
+} | {
+    type: 'sql';
+    sql: string;
+    params?: any[];
+    options?: {
+        debug?: boolean;
+        chunkSize?: number;
+    };
+} | {
+    type: 'abort';
+};
+export type SQLiteCLientCallParams<K extends SQLiteClientCallData['type']> = Omit<Extract<SQLiteClientCallData, {
+    type: K;
+}>, 'type'>;
+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;
+};
+export type ClientMessageData = {
+    type: 'open';
+    file: string;
+    flags: SharedArrayBuffer;
+    index: number;
+    vfs?: SQLiteVFS;
+    pragmas?: Record<string, string>;
+} | {
+    type: 'query';
+    callId: number;
+    sql: string;
+    params: any[];
+    options?: SQLOptions;
+};
+export type WorkerMessageData = {
+    type: 'ready';
+    callId: number;
+} | {
+    type: 'chunk';
+    callId: number;
+    data: any[];
+} | {
+    type: 'done';
+    callId: number;
+    affected: number;
+} | {
+    type: 'error';
+    callId: number;
+    message: string;
+    cause?: unknown;
+};
+export type SQLiteVFS = 'OPFSPermutedVFS' | 'OPFSAdaptiveVFS' | 'OPFSCoopSyncVFS' | 'AccessHandlePoolVFS' | 'IDBBatchAtomicVFS';
+export {};

package/dist/esm/src/utils.d.ts

@@ -0,0 +1,6 @@
+export declare const sqlParams: () => {
+    addParam: (v: any) => string;
+    addParamArray: (values: any[]) => string;
+    params: any[];
+};
+export declare const isWriteQuery: (sql: string) => boolean;

package/dist/esm/src/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "browser-sqlite",
+	"version": "1.0.0-rc.3",
+	"description": "Browser SQLite with concurrent read / serial write isolation, backed by Web Workers and wa-sqlite",
+	"author": "LAlex",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lalexdotcom/browser-sqlite.git"
+	},
+	"bugs": {
+		"url": "https://github.com/lalexdotcom/browser-sqlite/issues"
+	},
+	"homepage": "https://github.com/lalexdotcom/browser-sqlite#readme",
+	"keywords": [
+		"sqlite",
+		"browser",
+		"web-worker",
+		"opfs",
+		"wa-sqlite",
+		"wasm",
+		"shared-array-buffer"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/esm/index.d.ts",
+			"import": "./dist/esm/index.js",
+			"default": "./dist/esm/index.js"
+		}
+	},
+	"types": "./dist/esm/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rslib build",
+		"check": "biome check --write",
+		"lint": "biome lint",
+		"dev": "rslib build --watch",
+		"format": "biome format --write",
+		"prepare": "simple-git-hooks",
+		"test": "rstest",
+		"test:watch": "rstest --watch",
+		"test:unit": "rstest --project unit",
+		"test:browser": "rstest --project browser"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.6",
+		"@rslib/core": "^0.20.0",
+		"@rstest/adapter-rslib": "^0.2.1",
+		"@rstest/browser": "0.9.4",
+		"@rstest/core": "^0.9.0",
+		"@types/node": "^24.12.0",
+		"lint-staged": "^16.4.0",
+		"playwright": "1.58.2",
+		"simple-git-hooks": "^2.13.1",
+		"typescript": "^5.9.3"
+	},
+	"lint-staged": {
+		"*.{js,ts,jsx,tsx,mjs,cjs}": [
+			"biome check --write --no-errors-on-unmatched"
+		]
+	},
+	"simple-git-hooks": {
+		"pre-commit": "npx lint-staged && pnpm test && pnpm exec tsc --noEmit"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"simple-git-hooks"
+		]
+	},
+	"private": false,
+	"dependencies": {
+		"@lalex/promises": "^1.2.0",
+		"wa-sqlite": "github:rhashimoto/wa-sqlite#v1.0.9"
+	},
+	"packageManager": "pnpm@10.31.0"
+}