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

package/dist/api.d.ts

@@ -10,23 +10,25 @@
  * caller passes to a query, and what comes back.
  */
 import type { ClientDebugState } from './debug';
+import type { ClientInspection } from './inspect';
+import type { SQLiteBuild, SQLiteVFS } from './types';
 /**
  * Marks an options type as carrying an abort signal.
  *
- * The name is the point. `options?: OptionsWithSignal<…>` says at the signature
+ * The name is the point. `options?: Interruptible<…>` says at the signature
  * that the method can be abandoned, where a bare alias would make a reader open
  * the type to find out. Every abortable option type in this file is built from
  * it, so `signal` is documented once and cannot drift between them.
  *
  * Not the bare `Abortable` that `@types/node` uses: this reads as an options
  * bag augmented with one member — `PropsWithChildren`, not an adjective — which
- * is what it is both wrapped, `OptionsWithSignal<{ chunkSize?: number }>`, and
- * alone, `options?: OptionsWithSignal`.
+ * is what it is both wrapped, `Interruptible<{ chunkSize?: number }>`, and
+ * alone, `options?: Interruptible`.
  *
  * `T = unknown` rather than `Record<string, never>`: intersecting with the
  * latter collapses `signal` to `never` and makes it unassignable.
  */
-export type OptionsWithSignal<T = unknown> = T & {
+export type Interruptible<T = unknown> = T & {
     /**
      * Aborts the work. Rejects with `signal.reason` — your reason, not an error
      * of this library's making.
@@ -37,11 +39,26 @@ export type OptionsWithSignal<T = unknown> = T & {
      * `bulkWrite()` leaves the batches already written in place; an aborted
      * `output()` is observationally a no-op, dropping its staging table and
      * touching nothing else.
+     *
+     * Whether it also stops the statement SQLite is already executing depends on
+     * your build and your page: see the Interrupting a call section of API.md.
      */
     signal?: AbortSignal | undefined;
+    /**
+     * Milliseconds from the call within which it must finish, after which it is
+     * aborted and rejected with `OPERATION_TIMEOUT`. It is wall clock: time your
+     * own code spends — between two chunks of a `stream()`, inside a
+     * `transaction()` callback, between two `enqueue()` calls — counts against
+     * it, as does time spent waiting for a pool worker or for another tab's
+     * write lock.
+     *
+     * It aborts through the same path a `signal` does, so the same limit applies:
+     * see the Interrupting a call section of API.md.
+     */
+    timeout?: number | undefined;
 };
 /** Options every query method accepts. */
-export type SQLiteQueryOptions = OptionsWithSignal;
+export type SQLiteQueryOptions = Interruptible;
 /**
  * Options for the methods that cross the worker boundary in chunks.
  *
@@ -50,7 +67,7 @@ export type SQLiteQueryOptions = OptionsWithSignal;
  * ahead of the consumer. On `stream()` that is the only lever on how many rows
  * are in flight.
  */
-export type SQLiteChunkOptions = OptionsWithSignal<{
+export type SQLiteChunkOptions = Interruptible<{
     /** Rows per chunk. Defaults to 500. */
     chunkSize?: number;
 }>;
@@ -80,9 +97,9 @@ export type SQLiteWriteResult<T extends Record<string, unknown>> = {
  * That window is short on a VFS holding one access handle per connection, and
  * it is not on a VFS rotating a single exclusive one: there such a statement
  * waits for whichever client holds the file, and your signal cannot shorten
- * that wait. See the reduced mode described under VFS Selection.
+ * that wait. See the reduced mode described in VFS.md.
  */
-export type SQLiteTransactionOptions = OptionsWithSignal<{
+export type SQLiteTransactionOptions = Interruptible<{
     /** Rejects write statements with `READ_ONLY_TRANSACTION`. Defaults to false. */
     readOnly?: boolean;
     /** Commits when the callback resolves. Defaults to true. */
@@ -102,7 +119,7 @@ export type Index<SCHEMA extends Schema> = keyof SCHEMA | (keyof SCHEMA)[] | ({
 } | {
     columns: (keyof SCHEMA)[];
 }));
-export type SQLiteOutputOptions<SCHEMA extends Schema> = OptionsWithSignal<{
+export type SQLiteOutputOptions<SCHEMA extends Schema> = Interruptible<{
     indexes?: Index<SCHEMA>[];
     /** Rows queued for writing above which `enqueue()` defers. See `SQLiteBulkWriteOptions`. */
     queueSize?: number | undefined;
@@ -126,7 +143,7 @@ export type SQLiteOutputOptions<SCHEMA extends Schema> = OptionsWithSignal<{
  * 1 is raised to 1: a batch always holds at least one row, so a lower cap could
  * never be satisfied.
  */
-export type SQLiteBulkWriteOptions = OptionsWithSignal<{
+export type SQLiteBulkWriteOptions = Interruptible<{
     /** Rows queued for writing above which `enqueue()` defers. */
     queueSize?: number | undefined;
 }>;
@@ -200,7 +217,7 @@ export type SQLiteQueryAPI = {
      * @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?: unknown[], options?: OptionsWithSignal) => Promise<SQLiteWriteResult<T>>;
+    write: <T extends Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<SQLiteWriteResult<T>>;
     /**
      * 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.
@@ -253,7 +270,7 @@ export type SQLiteQueryAPI = {
      * @param options - Optional query options (`signal`).
      * @returns Promise resolving to the first row as `T`, or `undefined` if no rows.
      */
-    first: <T extends Record<string, unknown>>(sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<T | undefined>;
+    first: <T extends Record<string, unknown>>(sql: string, params?: unknown[], options?: SQLiteQueryOptions) => Promise<T | undefined>;
     /**
      * Creates a buffered bulk-insert utility that batches rows to stay within
      * SQLite's variable limit (`SQLITE_MAX_VARS = 32766`).
@@ -362,6 +379,31 @@ export type SQLiteDB = SQLiteQueryAPI & {
      * check what your chosen VFS actually writes.
      */
     close: () => Promise<void>;
+    /** This client's UUID, unique across the origin. */
+    readonly id: string;
+    /** This client's label, index included — what its log lines are prefixed with. */
+    readonly name: string;
+    /** The database file, normalized: the identity every lock name is built on. */
+    readonly file: string;
+    readonly vfs: SQLiteVFS;
+    /** The build actually loaded, resolved by `defaultBuildFor` when not passed. */
+    readonly build: SQLiteBuild;
+    /**
+     * The number of workers the pool runs: `poolSize` as requested, capped by
+     * the VFS and by the environment. Exact once every worker has opened or
+     * declined; every query waits for that, so it is settled by the time any
+     * query returns.
+     */
+    readonly poolSize: number;
+    /**
+     * Who else is live on this database, right now, in every tab of this origin.
+     *
+     * A snapshot, stale the instant it resolves: it informs a UI and never
+     * authorizes an action. Poll it if you want it to move — each call is a fresh
+     * census costing well under a tenth of a millisecond, and it takes no lock,
+     * so it cannot slow a query down.
+     */
+    inspect: () => Promise<ClientInspection>;
     /**
      * Internal diagnostic handle. Not part of the stable public API.
      * Shape is subject to change without notice.
@@ -372,5 +414,13 @@ export type SQLiteDB = SQLiteQueryAPI & {
 export type SQLiteTransactionDB = SQLiteQueryAPI & {
     commit: () => Promise<void>;
     rollback: () => Promise<void>;
+    /**
+     * Aborted when this transaction fails or is abandoned — its own signal or
+     * timeout, close(), an abandoned write, or an error the callback lets
+     * escape — with the value `transaction()` rejects with. Never aborted when
+     * it succeeds. Hand it to work of your own the callback awaits, such as a
+     * `fetch`, so that work stops with the transaction.
+     */
+    readonly signal: AbortSignal;
 };
 export {};

package/dist/bulk.d.ts

@@ -29,6 +29,21 @@ export declare const createBulk: (shared: {
     read: ReadFn;
     write: WriteFn;
     transaction: TransactionFn;
+    /**
+     * Takes this batch's place in the caller's statement queue, SYNCHRONOUSLY,
+     * at the moment `flush()` commits to it — from `close()` or from the
+     * `enqueue()` that filled the buffer. `started` is what was issued before
+     * it; `done()` gives the place back.
+     *
+     * Supplied by a transaction, where every statement shares one connection.
+     * The client path supplies none: there each statement takes its own lease.
+     * Without it the batch posts a microtask after `flush()` returns, so a
+     * statement issued AFTER it runs first — a stale read rather than an error.
+     */
+    reserve?: () => {
+        started: Promise<void>;
+        done: () => void;
+    };
 }) => {
     bulkWrite: <KEYS extends string>(table: string, keys: KEYS[], options?: SQLiteBulkWriteOptions, before?: Promise<unknown>) => {
         enqueue: (data: { [K in KEYS]: any; }) => Promise<void>;

package/dist/client.d.ts

@@ -1,35 +1,50 @@
-import type { OptionsWithSignal, SQLiteChunkOptions } from './api';
+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 = {
     /**
-     * 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
+     * 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.
-     * Must be `1` when using `AccessHandlePoolVFS` — any larger value throws at construction time.
-     * @defaultValue `2`
+     * 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 the README's VFS Selection guide.
+     * 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 README's Builds section for versions.
+     * support; see the Builds section of VFS.md for versions.
      *
      * @throws at construction when the build is not one the chosen VFS supports.
      */
@@ -83,8 +98,10 @@ export type CreateSQLiteClientOptions = {
     maxWorkerRestarts?: number;
     /**
      * Milliseconds a worker has to post `ready` after its `open` message is sent.
-     * On expiry the slot is failed immediately — the most common cause is a
-     * database held under an exclusive lock by another tab or client.
+     * 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;
@@ -97,15 +114,15 @@ export type CreateSQLiteClientOptions = {
     /**
      * 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 prefix (`"<name> <index>"`), which already names the workers.
+     * 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 requested pool size,
-     * and the error that killed the slot.
+     * 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
@@ -125,7 +142,7 @@ export type WorkerLostEvent = {
     index: number;
     /** Number of workers still alive after this loss. */
     live: number;
-    /** The requested pool size (`poolSize` option). */
+    /** 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;
@@ -164,7 +181,6 @@ export type WorkerLostEvent = {
  * import { createSQLiteClient } from 'browser-sqlite';
  *
  * const db = createSQLiteClient('myapp.sqlite', {
- *   poolSize: 3,
  *   vfs: 'OPFSAdaptiveVFS',
  *   pragmas: { journal_mode: 'WAL', synchronous: 'NORMAL' },
  * });
@@ -176,14 +192,14 @@ export type WorkerLostEvent = {
  * ```
  */
 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, any>;
-    read: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<T[]>;
-    write: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<{
+    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, any>;
-    first: <T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: unknown[], options?: OptionsWithSignal) => Promise<T | undefined>;
+    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>;
@@ -194,5 +210,12 @@ export declare const createSQLiteClient: (file: string, clientOptions: CreateSQL
         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/delete.d.ts

@@ -24,9 +24,11 @@ export type DeleteDatabaseOptions = {
 /**
  * Deletes a database and the two siblings SQLite may leave beside it.
  *
- * Deleting a database that is not there is success — SQLite's own `xDelete`
- * behaves the same way, and a caller who wanted it gone has got what they
- * asked for.
+ * 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
@@ -35,8 +37,12 @@ export type DeleteDatabaseOptions = {
  *
  * @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} `BUSY` when the database is open or being opened, in
- *   this tab or another. A connection already holding its handles cannot be
+ * @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

@@ -12,6 +12,8 @@
  * 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.
  *
@@ -23,19 +25,47 @@
  * 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 in this realm for this database. */
+    /** 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 `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.
+ * 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: (file: string) => Epochs;
+export declare const epochsFor: (vfs: SQLiteVFS, file: string, locks: Locks) => Epochs;
 /**
  * Where a worker's `seen` lands after the write it just served.
  *

package/dist/errors.d.ts

@@ -2,19 +2,58 @@
  * 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.
  */
-export type SQLiteErrorCode = 'NOT_A_READ_QUERY' | 'CLIENT_CLOSED' | 'WORKER_CRASHED' | 'TIMEOUT' | 'PROTOCOL_ERROR' | 'INVALID_IDENTIFIER' | 'INVALID_OPTION' | 'INVALID_PRAGMA' | 'BULK_WRITE_FAILED' | 'BUSY' | 'READ_ONLY_TRANSACTION';
+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. `BUSY` covers both SQLITE_BUSY (5)
-     * and SQLITE_LOCKED (6); this is how a caller tells them apart.
+     * 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?: number;
+    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?: number;
+        sqliteCode?: SQLiteResultCode;
+        sqliteExtendedCode?: SQLiteExtendedResultCode | (number & {});
+        timeout?: number;
     });
 }
 /**

package/dist/index.d.ts

@@ -3,4 +3,6 @@ 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';