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

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

@@ -1,332 +0,0 @@
-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/index.d.ts

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

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

@@ -1,87 +0,0 @@
-/**
- * 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

@@ -1,83 +0,0 @@
-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

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