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

package/dist/client.d.ts

@@ -0,0 +1,221 @@
+import type { SQLiteChunkOptions, SQLiteQueryOptions } from './api';
+import { SQLiteError } from './errors';
+import { type ClientInspection } from './inspect';
+import { type SQLiteBuild, type SQLiteVFS } from './types';
+/**
+ * Configuration options for creating a SQLite client.
+ */
+export type CreateSQLiteClientOptions = {
+    /**
+     * A label for this client, never for the database — the database file is
+     * the FIRST argument to `createSQLiteClient`, and this option has no effect
+     * on what is opened or where.
+     *
+     * It is reported as `db.debug.name`, and prefixes the `debug` logger's
+     * console output as `"<name> <n>"`, where `n` counts the clients created in
+     * this tab. Neither form is unique across the origin: the counter is
+     * per-tab, so two tabs both produce `"SQLite 1"`.
+     *
+     * @defaultValue `"SQLite"`
+     */
+    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.
+     * A VFS that holds a single connection, or gains nothing from a second one,
+     * caps this at `1` (`OPFSCoopSyncVFS` among them), and passing more throws at
+     * construction time. Omitting it never throws: the default is capped to what
+     * the VFS allows.
+     * The environment can cap it too: `OPFSWriteAheadVFS` and `OPFSAdaptiveVFS`
+     * run on one worker wherever `readwrite-unsafe` is missing, with no error, and
+     * warn once only when this option was passed. `db.poolSize` reports the size
+     * the pool runs at.
+     * @defaultValue `2`, or the VFS's maximum when it is lower
+     */
+    poolSize?: number;
+    /**
+     * Which VFS stores the database. Required: a VFS decides *where* the bytes
+     * live, and a database written through one VFS is not visible through
+     * another. See Browser compatibility and recommendations in VFS.md.
+     */
+    vfs: SQLiteVFS;
+    /**
+     * Which wa-sqlite WebAssembly build to load. Defaults to the first entry of
+     * `VFS_CAPABILITIES[vfs]` — `sync` where the VFS supports it, since it is both the
+     * fastest and the most portable, otherwise `async`. `jspi` needs engine
+     * support; see the Builds section of VFS.md for versions.
+     *
+     * @throws at construction when the build is not one the chosen VFS supports.
+     */
+    build?: SQLiteBuild;
+    /**
+     * Where the workers fetch their `.wasm` from. **An escape hatch, not a
+     * setting**: omit it and resolution is exactly what it was before this
+     * option existed — the file is taken from beside `worker.js`, which is where
+     * the package ships it and where every bundler emits it.
+     *
+     * Reach for it only when the `.wasm` have been separated from `worker.js`:
+     * assets moved by hand with no bundler, or a build whose emitted URL is
+     * wrong at runtime.
+     *
+     * A **string is a directory**, resolved against the page — relative
+     * (`'wasm/'`), absolute (`'/static/wasm'`) or a full URL. A missing trailing
+     * slash is added. The file name comes from wa-sqlite itself, so one base
+     * serves whichever `build` is loaded.
+     *
+     * A **callback names one file** and receives the resolved `build`, for a
+     * bundler-emitted asset whose name carries a content hash:
+     * ```ts
+     * import wasmUrl from 'browser-sqlite/dist/worker/wa-sqlite.wasm?url';
+     * createSQLiteClient('app.db', { vfs, wasmUrl: () => wasmUrl });
+     * ```
+     * It is called once, at construction, and its answer is reused by every
+     * worker and every restart.
+     *
+     * Serving the `.wasm` from another origin has two requirements beyond this
+     * option, both enforced by the browser: the response needs CORS
+     * (`Access-Control-Allow-Origin`), since the glue fetches it, and it must
+     * carry `Content-Type: application/wasm` for streaming compilation.
+     *
+     * @throws at construction when the value cannot be parsed as a URL.
+     */
+    wasmUrl?: string | ((build: SQLiteBuild) => string);
+    /**
+     * 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>;
+    /**
+     * How many times a worker slot may be restarted after it has died.
+     * A slot that never reached readiness is never restarted — an initial
+     * failure is deterministic, and restarting only delays the diagnostic.
+     * The counter resets once the replacement has actually served a request.
+     * @defaultValue `1`
+     */
+    maxWorkerRestarts?: number;
+    /**
+     * Milliseconds a worker has to post `ready` after its `open` message is sent.
+     * On expiry the slot is failed immediately, with a message naming the cause
+     * the client roster supports: another live client of this library holding
+     * the database, or a holder the roster cannot see — a page reloaded without
+     * `close()`, another library, native code.
+     * @defaultValue `30_000`
+     */
+    openTimeout?: number;
+    /**
+     * Milliseconds the drain loop (in the query generator's `finally`) may run
+     * before the worker is presumed dead and the crash path is invoked.
+     * @defaultValue `60_000`
+     */
+    drainTimeout?: number;
+    /**
+     * Turns on the introspection subsystem exposed as `db.debug`, and the
+     * lifecycle log. A string is used as the log prefix; `true` falls back to the
+     * client name (`"<name> <index>"`), which already names the workers.
+     *
+     * @defaultValue undefined — no collection, no output, `db.debug` undefined.
+     */
+    debug?: string | boolean;
+    /**
+     * Called whenever a worker slot is permanently lost. Receives the slot index,
+     * the number of workers still alive after the loss, the pool's size
+     * (`db.poolSize`), and the error that killed the slot.
+     *
+     * Guaranteed to be called **before** the client is failed when the last slot
+     * is lost. Wrapped in try/catch — a throwing callback is reported through
+     * `logger.always.warn` and does not break the pool.
+     *
+     * @defaultValue undefined
+     */
+    onWorkerLost?: (event: WorkerLostEvent) => void;
+};
+/**
+ * What `onWorkerLost` receives. Named and exported rather than inlined in the
+ * option: a consumer whose handler is a standalone function needs to be able
+ * to type its parameter.
+ */
+export type WorkerLostEvent = {
+    /** Zero-based index of the lost slot. */
+    index: number;
+    /** Number of workers still alive after this loss. */
+    live: number;
+    /** The number of workers the pool runs — `db.poolSize`, not the `poolSize` option: the two differ where the environment caps the pool. */
+    size: number;
+    /** The error that killed the worker. */
+    cause: SQLiteError;
+};
+/**
+ * Creates a SQLite client backed by a pool of Web Workers, each running
+ * a wa-sqlite instance in a dedicated thread.
+ *
+ * @remarks
+ * **Browser requirements:** This client uses OPFS through Web Workers; no
+ * special HTTP headers are required and cross-origin isolation is not needed.
+ * The default `build` needs no browser opt-in; only `build: 'jspi'` does, and
+ * JSPI is Chromium-only — an unrelated constraint, not a header requirement.
+ *
+ * **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 - Pool and VFS configuration. Required: `vfs` has no
+ *   default, because a VFS decides where the database is written.
+ *   See {@link CreateSQLiteClientOptions} for field defaults.
+ * @returns A {@link SQLiteDB} object providing `read`, `write`, `chunk`,
+ *   `stream`, `first`, `transaction`, `bulkWrite`, `output`, and `close` methods.
+ *
+ * @throws {SQLiteError} With code `INVALID_OPTION` when `build` is not one of
+ *   the builds the chosen `vfs` supports. The message names the supported
+ *   builds; the pairing is declared once, in `VFS_CAPABILITIES`.
+ * @throws {SQLiteError} With code `INVALID_OPTION` when `poolSize` exceeds the
+ *   `maxPoolSize` the chosen `vfs` declares. The message names the cap and the
+ *   reason for it; both come from `VFS_CAPABILITIES`.
+ *
+ * @example
+ * ```typescript
+ * import { createSQLiteClient } from 'browser-sqlite';
+ *
+ * const db = createSQLiteClient('myapp.sqlite', {
+ *   vfs: 'OPFSAdaptiveVFS',
+ *   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) => {
+    chunk: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteChunkOptions) => AsyncGenerator<T[], void, unknown>;
+    read: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteChunkOptions) => Promise<T[]>;
+    write: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<{
+        result: T[];
+        affected: number;
+    }>;
+    stream: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteChunkOptions) => AsyncGenerator<T, void, unknown>;
+    first: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<T | undefined>;
+    transaction: <T = void>(callback: (db: import("./api").SQLiteTransactionDB) => Promise<T>, options?: import("./api").SQLiteTransactionOptions) => Promise<T>;
+    bulkWrite: <KEYS extends string>(table: string, keys: KEYS[], options?: import("./api").SQLiteBulkWriteOptions, before?: Promise<unknown>) => {
+        enqueue: (data: { [K in KEYS]: any; }) => Promise<void>;
+        close: () => Promise<number>;
+    };
+    output: <SCHEMA extends import("./api").Schema>(table: string, schema: SCHEMA, options?: import("./api").SQLiteOutputOptions<SCHEMA>) => {
+        enqueue: (data: import("./api").SQLiteOutputRow<SCHEMA>) => Promise<void>;
+        close: () => Promise<number>;
+    };
+    close: () => Promise<void>;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly name: string;
+    readonly file: string;
+    readonly vfs: "AccessHandlePoolVFS" | "IDBBatchAtomicVFS" | "IDBMirrorVFS" | "MemoryAsyncVFS" | "MemoryVFS" | "OPFSAdaptiveVFS" | "OPFSAnyContextVFS" | "OPFSCoopSyncVFS" | "OPFSWriteAheadVFS";
+    readonly build: SQLiteBuild;
+    readonly poolSize: number;
+    inspect: () => Promise<ClientInspection>;
+    debug: import("./debug").ClientDebugState | undefined;
+};

package/dist/credits.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The credit gate: back-pressure for chunk production, and the task turn that
+ * makes a worker reachable by `postMessage` while it is inside a query.
+ *
+ * Pure and Node-testable on purpose. B1 survived for months because the
+ * scheduler was reachable only through slow browser tests; this module has the
+ * same profile — subtle state transitions otherwise buried behind a worker, a
+ * VFS and a real database.
+ */
+/** One turn of the task queue. Injected so Node tests can drive it. */
+export type Tick = () => Promise<void>;
+/** Chunks a worker may send before waiting for a credit. Spec §3.4. */
+export declare const DEFAULT_CREDIT_WINDOW = 2;
+export type CreditGate = {
+    /** Begin a query: `window` credits, not stopped, credit counter cleared. */
+    reset: (callId: number, window: number) => void;
+    /** Add credits for `callId`. A stale `callId` is ignored (§5.4). */
+    grant: (callId: number, n: number) => void;
+    /** Stop the current query, waking any wait in progress (§5.1). */
+    stop: () => void;
+    /** Spend one credit. Always costs one task turn first. */
+    take: (callId: number) => Promise<'go' | 'stopped'>;
+    isStopped: () => boolean;
+    tick: Tick;
+};
+/**
+ * A task turn via MessageChannel. NOT setTimeout: nested setTimeout is clamped
+ * to 4 ms, which would cost seconds over a few hundred chunks (spec §3.1).
+ */
+export declare const createMessageChannelTick: () => Tick;
+export declare const createCreditGate: (tick: Tick) => CreditGate;

package/dist/{esm/src/debug.d.ts → debug.d.ts}

@@ -1,16 +1,16 @@
 import type { CreateSQLiteClientOptions } from './client';
-import { type WorkerOrchestrator } from './orchestrator';
+import type { PoolWorker } from './pool';
 import type { SQLiteVFS } from './types';
-export declare const debugSQLQuery: (sql: string, params?: any[]) => string;
-export declare const statusToLabel: (status: number) => string;
+export declare const debugSQLQuery: (sql: string, params?: unknown[]) => string;
 type QueryDebugState = {
     sql: string;
-    params?: any[];
+    params?: unknown[] | undefined;
     startTime: number;
     firstRowTime?: number;
     endTime?: number;
-    error?: any;
+    error?: unknown;
     affectedRows: number;
+    prepared: number;
 };
 type RequestDebugState = {
     startTime: number;
@@ -29,24 +29,35 @@ type WorkerDebugState = {
     currentRequest?: RequestDebugState;
     readonly status: string;
 };
-type ClientDebugState = {
+export type ClientDebugState = {
     readonly file: string;
     readonly vfs: SQLiteVFS;
     readonly pragmas: Record<string, string>;
     readonly name: string;
     readonly queue: {
-        write: number;
-        read: number;
+        readonly read: number;
+        readonly write: number;
+        /**
+         * Callers suspended on the pool's readiness gate, waiting for the pool to
+         * exist rather than for a free worker. They sit in neither wait queue, so
+         * `read` and `write` are both 0 while they wait — during startup, and
+         * during the retry round that follows a failed open.
+         */
+        readonly gated: number;
     };
     workers: WorkerDebugState[];
 };
-export declare const createClientDebug: (file: string, orchestrator: WorkerOrchestrator, clientOptions: Required<Pick<CreateSQLiteClientOptions, "vfs" | "pragmas" | "name">>) => {
+export declare const createClientDebug: (file: string, pool: (PoolWorker | undefined)[], clientOptions: Required<Pick<CreateSQLiteClientOptions, 'vfs' | 'pragmas' | 'name'>>, stats: () => {
+    read: number;
+    write: number;
+    gated: number;
+}) => {
     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;
+    readonly createQueryDebugState: (workerIndex: number, sql: string, params?: unknown[]) => QueryDebugState;
 };
 export {};

package/dist/delete.d.ts

@@ -0,0 +1,48 @@
+import { type SQLiteBuild, type SQLiteVFS } from './types';
+export type DeleteDatabaseOptions = {
+    /**
+     * Which VFS holds the database. Required for the same reason it is required
+     * on `createSQLiteClient`: a VFS decides where the bytes live, so deleting
+     * without naming one deletes in the wrong store — or nowhere, while
+     * reporting success.
+     */
+    vfs: SQLiteVFS;
+    /**
+     * Which wa-sqlite build to load. It does **not** affect where the database
+     * lives; it is here only because a VFS runs solely on the builds it
+     * declares, and one of them must be loaded to instantiate the VFS at all.
+     * @defaultValue the first build the VFS declares
+     */
+    build?: SQLiteBuild;
+    /**
+     * Where the worker fetches its `.wasm`, with the same meaning as on
+     * `createSQLiteClient`. A deployment that needs it to open a database needs
+     * it to delete one.
+     */
+    wasmUrl?: string | ((build: SQLiteBuild) => string);
+};
+/**
+ * Deletes a database and the two siblings SQLite may leave beside it.
+ *
+ * Deleting a database that is not there REJECTS with `DATABASE_NOT_FOUND`.
+ * This paragraph said the opposite until 2026-09-16 — that absence was success,
+ * as SQLite's own `xDelete` treats it — but the probe in `deleteDatabaseFiles`
+ * has always reported absence, and `delete.test.ts` pins that with a falsifier.
+ * The doc was the stale half, and it ships in the published `.d.ts`.
+ *
+ * Nothing a VFS keeps for itself is touched: not the IndexedDB store, which is
+ * shared by every database that VFS holds on this origin, and not the
+ * `AccessHandlePoolVFS` directory, whose files *are* its reusable capacity.
+ * The bytes of the named database are freed in both cases.
+ *
+ * @throws {SQLiteError} `INVALID_OPTION` when `vfs` is missing or the `build`
+ *   is not one the VFS supports — synchronously in spirit, as a rejection here.
+ * @throws {SQLiteError} `DATABASE_IN_USE` when the database is open, in this
+ *   tab or another. A connection already holding its handles cannot be
+ *   revoked from here; see the README's Known Limitations.
+ * @throws {SQLiteError} `BUSY` when the database is being opened or deleted
+ *   elsewhere. Try again in a moment.
+ * @throws {SQLiteError} `DATABASE_NOT_FOUND` when there is no such database.
+ *   A caller deleting speculatively should catch this one code.
+ */
+export declare const deleteDatabase: (file: string, options: DeleteDatabaseOptions) => Promise<void>;

package/dist/epochs.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The commit epoch: a monotonic integer per database, counting commits
+ * performed in this realm. Its absolute value means nothing — only the
+ * comparison with a worker's `seen` does.
+ *
+ * The registry lives in the realm-wide symbol registry rather than in a module
+ * variable on purpose. A module singleton is unique only when the bundler
+ * loads one copy of the module; `Symbol.for` is unique per realm whatever the
+ * bundler did. That is what makes "two clients in one tab see each other" true
+ * by construction.
+ *
+ * The `v1` suffix separates incompatible shapes. Bump it ONLY if the shape
+ * changes — bumping it per release recreates the fragmentation it prevents.
+ */
+import type { Locks } from './locks';
+import type { SQLiteVFS } from './types';
+/**
+ * The statement the barrier runs and discards.
+ *
+ * Measured 2026-08-20 in the forced configuration: 6/6 correct. `SELECT 1`
+ * touches no page and is 6/6 stale; `PRAGMA data_version` and
+ * `PRAGMA schema_version` are 8/8 stale; so is waiting. Only a statement that
+ * opens a real read transaction on the file refreshes the connection's cached
+ * page 1 — and it must be a SEPARATE statement, because the one that triggers
+ * the refresh still returns the stale result.
+ */
+export declare const BARRIER_SQL = "SELECT count(*) FROM sqlite_master";
+/**
+ * The marker a realm holds to publish the epoch it last committed.
+ *
+ * Held in SHARED mode: many realms may hold one name at once, so publishing
+ * never waits and two realms can never collide on a number. Nobody reads the
+ * lock — the NAME is the state, which is why this beats a BroadcastChannel:
+ * there is no message that can still be in flight.
+ */
+export declare const epochLockName: (ns: string, file: string, n: number) => string;
+/**
+ * The highest epoch any realm in this origin has published under `prefix`.
+ *
+ * The tail after the prefix must be ALL digits, which is stricter than a
+ * prefix match plus `lastIndexOf(':')` and is the point: a normalized file may
+ * contain a colon (`new URL('./a:b', 'file://').pathname` is `a:b`), so the
+ * loose form would read another database's epoch as this one's.
+ */
+export declare const maxEpochIn: (heldNames: string[], prefix: string) => number;
+export type Epochs = {
+    /** The number of commits observed for this database, floor included. */
+    current: () => number;
+    /** Records one commit and returns the new epoch. */
+    bump: () => number;
+    /** Raises the local floor. Never lowers it. */
+    raiseTo: (n: number) => void;
+    /** The highest epoch published by any realm in this origin. */
+    originMax: () => Promise<number>;
+    /** Publishes `n` for this realm, replacing its previous marker. */
+    publish: (n: number) => Promise<void>;
+};
+/**
+ * Handles onto the counter for `(namespace, file)`, which MUST already be
+ * normalized by `normalizeDatabaseFile`. Entries are never removed: deleting
+ * one would restart the counter at 0, and a worker still alive with `seen = 5`
+ * would then read `5 > 0`, believe itself current forever, and serve stale
+ * data.
+ *
+ * The cell is realm-wide, so every client in a tab shares one counter AND one
+ * marker — publication is per realm, not per client.
+ */
+export declare const epochsFor: (vfs: SQLiteVFS, file: string, locks: Locks) => Epochs;
+/**
+ * Where a worker's `seen` lands after the write it just served.
+ *
+ * `target` is the epoch captured when its lease was granted; `next` is the
+ * epoch its own commit produced. Advancing requires both conditions:
+ *
+ * - `seen === target`: the worker was actually observing from `target` when its
+ *   lease was granted. If the worker was already behind (`seen < target`), it
+ *   must not be marked current regardless of what it just committed.
+ * - `next === target + 1`: the commit is the immediate successor of `target`.
+ *   If another client committed during our lease, `next` skipped; our
+ *   connection never observed that commit and must stay marked behind.
+ *
+ * Marking a connection current when it is not is the only class of bug this
+ * design must make impossible.
+ */
+export declare const advanceSeen: (seen: number, target: number, next: number) => number;

package/dist/errors.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Every failure this library raises on its own behalf. A caller discriminates
+ * on `code`, or on `name` — they carry the same value, so `err.name` reads the
+ * way `'AbortError'` does on the DOMException an aborted signal throws.
+ * `DATABASE_IN_USE` is this library's own: a database that a live client holds,
+ * as opposed to `BUSY`, which covers a transient conflict worth retrying.
+ * `DATABASE_NOT_FOUND` is raised only by `deleteDatabase`: there is nothing at
+ * that name to delete. `createSQLiteClient` creates what is absent, so it has
+ * no such case.
+ * `UNSUPPORTED` means the platform cannot answer the question — raised by
+ * `inspectDatabase` where Web Locks is missing, because reporting zero clients
+ * there would be indistinguishable from a database nobody holds.
+ * `OPERATION_TIMEOUT` is the `timeout` a caller set on a call being spent. It is
+ * deliberately not `TIMEOUT`, which means a deadline this library imposed on
+ * itself — a worker that never became ready, a deletion that did not complete.
+ * `STATEMENT_FAILED` is a statement SQLite refused or failed for any reason
+ * but a lock conflict — a constraint, a syntax error, a full disk. `message` is
+ * SQLite's own; `sqliteCode` carries its result code, and `sqliteExtendedCode`
+ * its subtype when SQLite reports one.
+ */
+import type { SQLiteExtendedResultCode, SQLiteResultCode } from './sqlite-codes';
+export type SQLiteErrorCode = 'NOT_A_READ_QUERY' | 'CLIENT_CLOSED' | 'WORKER_CRASHED' | 'TIMEOUT' | 'PROTOCOL_ERROR' | 'INVALID_IDENTIFIER' | 'INVALID_OPTION' | 'INVALID_PRAGMA' | 'BULK_WRITE_FAILED' | 'BUSY' | 'STATEMENT_FAILED' | 'DATABASE_IN_USE' | 'DATABASE_NOT_FOUND' | 'READ_ONLY_TRANSACTION' | 'UNSUPPORTED' | 'WORKER_BUSY' | 'OPERATION_TIMEOUT' | 'TRANSACTION_CLOSED';
+export declare class SQLiteError extends Error {
+    readonly code: SQLiteErrorCode;
+    /**
+     * SQLite's own numeric result code, present only when the failure came from
+     * SQLite rather than from this library. Always the PRIMARY code. `BUSY`
+     * covers both SQLITE_BUSY (5) and SQLITE_LOCKED (6); this is how a caller
+     * tells them apart. Typed `SQLiteResultCode` (D10): since `sqliteCodeOf`,
+     * it is always a primary code of the bundled SQLite, so comparing it with
+     * an extended code does not compile.
+     */
+    readonly sqliteCode?: SQLiteResultCode;
+    /**
+     * SQLite's extended result code, present only when a statement SQLite ran
+     * failed WITH A SUBTYPE — `STATEMENT_FAILED` or `BUSY` from a query, never
+     * an open or a delete: 2067 (`SQLITE_EXTENDED_CODES.CONSTRAINT_UNIQUE`)
+     * under `sqliteCode` 19. Absent when SQLite has no subtype for the failure
+     * (a full disk, a syntax error), since `sqliteCode` already says it. For a
+     * subtype SQLite reports, `(sqliteExtendedCode & 0xff) === sqliteCode` is
+     * SQLite's own guarantee, not something this library enforces: the client
+     * deliberately lets a differing value through (a 0 from a wrong read).
+     * Typed open (`SQLiteExtendedResultCode | (number & {})`, D10): D9 lets a
+     * wrong read through, which a strict type would misdescribe.
+     */
+    readonly sqliteExtendedCode?: SQLiteExtendedResultCode | (number & {});
+    /**
+     * The `timeout` that was exceeded, in milliseconds. Present only on
+     * `OPERATION_TIMEOUT`, so a log need not parse the message for it.
+     */
+    readonly timeout?: number;
+    constructor(code: SQLiteErrorCode, message: string, options?: {
+        cause?: unknown;
+        sqliteCode?: SQLiteResultCode;
+        sqliteExtendedCode?: SQLiteExtendedResultCode | (number & {});
+        timeout?: number;
+    });
+}
+/**
+ * A batch failed. Raised by `bulkWrite().close()` and by `output().close()`.
+ *
+ * The counters exist because the old behaviour was silent: batches were chained
+ * on one shared promise, so after a rejection every later `.then` was skipped —
+ * while their rows had already been spliced out of the buffer (B5). A caller now
+ * learns how much of its data reached the database.
+ */
+export declare class SQLiteBulkWriteError extends SQLiteError {
+    readonly rowsWritten: number;
+    readonly rowsNotWritten: number;
+    constructor(message: string, counts: {
+        rowsWritten: number;
+        rowsNotWritten: number;
+    }, options?: {
+        cause?: unknown;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './api';
+export { detectFeatures, missingFeature } from './capabilities';
+export * from './client';
+export * from './delete';
+export * from './errors';
+export { type ClientInspection, type DatabaseClient, type DatabaseInspection, type InspectDatabaseOptions, type InspectionBase, inspectDatabase, } from './inspect';
+export { SQLITE_CODES, SQLITE_EXTENDED_CODES, type SQLiteExtendedResultCode, type SQLiteResultCode, } from './sqlite-codes';
+export { defaultBuildFor, type PlatformFeature, type SQLiteBuild, type SQLiteVFS, VFS_CAPABILITIES, type VFSCapability, type VFSLayout, type VFSMemoryModel, type VFSStorage, } from './types';