@crvouga/sqlite-mem 0.2.0 → 1.1.0

package/AGENTS.md

@@ -107,9 +107,8 @@ Hot / large files: `parser/parser.ts`, `executor/select.ts`, `executor/dml.ts`.
 | `tests/fuzz/` | fast-check property tests (seeded); same two backends |
 | `tests/harness/` | Compare/normalize helpers + harness unit tests |
 | `tests/adapters/` | Wrappers for sqlite-mem and `bun:sqlite` |
-| `tests/browser/` | Playwright smoke only — **not** the SQL oracle |
 
-Examples of public API usage: `tests/contract/api/`, `tests/browser/run.ts`, `tests/contract/parameters/`, `tests/contract/determinism/`.
+Examples of public API usage: `tests/contract/api/`, `tests/contract/parameters/`, `tests/contract/determinism/`, `examples/react-vite`.
 
 ### Fuzz replay
 
@@ -148,7 +147,6 @@ bun run typecheck
 bun run test:sqlite-compat
 bun test                     # contract + fuzz + harness
 bun run build
-bun run test:browser         # Playwright smoke
 ```
 
 ## PR and commits

package/COMPATIBILITY.md

@@ -86,7 +86,7 @@ Reference: **SQLite 3.51.0** (`bun:sqlite`). Inventory: `bun run scripts/fts-ora
 bun run test:sqlite-compat   # requirements + gate + contract/fuzz/harness
 bun run inventory            # oracle function/module inventory
 bun run requirements         # refresh SQLite.org requirements + coverage
-bun run test:browser         # Playwright smoke (not the SQL oracle)
+bun run build && bun run verify-package  # ESM browser build + isomorphic pack gates
 ```
 
 Do not treat isolated unit tests of internal modules as proof of SQLite compatibility. The differential matrix runner is authoritative for SQL behavior; `test:sqlite-compat` is the release gate.

package/README.md

@@ -46,7 +46,7 @@ db.exec(`
   )
 `);
 
-db.exec(`INSERT INTO users (name) VALUES (?)`, ["Alice"]);
+db.prepare(`INSERT INTO users (name) VALUES (?)`).run("Alice");
 
 const users = db.query<{ id: number; name: string }>(`SELECT * FROM users`);
 console.log(users);
@@ -78,28 +78,27 @@ import { Database, SqliteError } from "@crvouga/sqlite-mem";
 interface DatabaseOptions {
   seed?: number | bigint;           // default 1 — PRNG for random() / randomblob()
   now?: Date | (() => Date);        // default 2000-01-01T00:00:00.000Z
-  prng?: Prng;                      // optional; overrides seed
 }
 
 interface Database {
   constructor(options?: DatabaseOptions);
-  exec(sql: string, params?: BindValue[]): void;
+  exec(sql: string): void;
   query<T = QueryRow>(sql: string, params?: BindValue[]): T[];
   prepare(sql: string): Statement;
   transaction<T>(fn: () => T): T;
   snapshot(): Uint8Array;
   restore(snapshot: Uint8Array): void;
   close(): void;
+  [Symbol.dispose]?(): void;        // alias for close() when Symbol.dispose exists
   readonly changes: number;
   readonly lastInsertRowid: number | bigint;
 }
 
 interface Statement {
-  bind(...params: BindValue[]): Statement;
   run(...params: BindValue[]): RunResult;
   all<T = QueryRow>(...params: BindValue[]): T[];
   get<T = QueryRow>(...params: BindValue[]): T | undefined;
-  result(...params: BindValue[]): ResultSet; // includes columns when zero rows
+  result(...params: BindValue[]): ResultSet; // includes columns + values when zero rows
 }
 
 interface RunResult {
@@ -110,46 +109,48 @@ interface RunResult {
 interface ResultSet {
   columns: string[];
   rows: QueryRow[];
-  values?: QueryValue[][];
+  values: QueryValue[][];           // always present (empty array for zero rows)
   changes: number;
   lastInsertRowid: number | bigint;
 }
 
 class SqliteError extends Error {
   readonly category: ErrorCategory; // syntax, no_such_table, constraint_unique, misuse, …
-  readonly sqliteCode?: string;
+  readonly sqliteCode: string;      // always set; default "SQLITE_ERROR"
+  readonly code: string;            // === sqliteCode (Node err.code convention)
 }
 ```
 
-Stick to `Database`, `Statement`, and `SqliteError` for application code. The package also exports lower-level helpers (`parse`, `tokenize`, `evalExpr`, snapshot codec pieces, `SqlValue` utilities) for advanced use.
+Stick to `Database`, `Statement`, and `SqliteError` for application code. Advanced internals (`parse`, `tokenize`, `evalExpr`, snapshot codec pieces, `SqlValue` utilities, `Prng`, …) are available only from `@crvouga/sqlite-mem/unstable` and are **exempt from semver**.
 
 ### Method semantics
 
 | Method | Behavior |
 | --- | --- |
-| `exec(sql, params?)` | Runs all semicolon-separated statements; **discards** row results (`void`). Read `db.changes` / `db.lastInsertRowid` afterward if needed. |
-| `query(sql, params?)` | Same parse/run; returns rows of the **last** statement that has columns. Earlier SELECTs in a multi-statement script are dropped. |
-| `prepare(sql)` | Parses immediately; AST is reused. `run` / `all` / `get` / `result` with args override prior `bind()`. |
-| `transaction(fn)` | If idle: `BEGIN` → `fn()` → `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. Nested SQL `BEGIN` still errors. |
+| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` / `db.lastInsertRowid` afterward if needed (counters reflect the **most recent** completed statement, matching SQLite). |
+| `query(sql, params?)` | **Single statement only** (trailing `;` is fine). Returns all rows. Multi-statement scripts throw `misuse`. |
+| `prepare(sql)` | **Single statement only**. Parses immediately; AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` on each call. |
+| `transaction(fn)` | If idle: `BEGIN` → `fn()` → `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. Nested SQL `BEGIN` still errors. `close()` inside `fn` throws `misuse`. |
 | `snapshot` / `restore` | Custom binary format (see below). |
-| `close()` | Idempotent; rolls back an open transaction; further ops throw `misuse`. |
+| `close()` | Idempotent; rolls back an open SQL transaction; further ops throw `misuse`. Also available as `[Symbol.dispose]` when supported. |
 
-SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty SQL throws `misuse` (`empty statement`).
+SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty / comment-only SQL on `prepare` / `query` throws `misuse` (`empty statement`), matching SQLite prepare failure.
 
 ### Parameter binding
 
 Supported styles: `?`, `?NNN`, `:name`, `@name`, `$name`.
 
-- The JS API takes a **positional array** (or rest args) only — there is **no** `bind({ name: value })`.
+- The JS API takes **rest args** (or a positional array into `query`) only — there is **no** sticky `bind()` and **no** `bind({ name: value })`.
 - Named parameters occupy slots in **first-occurrence order**; repeated names share one slot.
 - Prefixes are part of the name: `@x`, `$x`, and `:x` are **three different** parameters.
 - Names are lowercased for lookup (`:Left` ≡ `:left`).
 - Bindable: `null`, `string`, finite `number`, `bigint`, `boolean` → `0`/`1`, `Uint8Array` / `ArrayBuffer`.
-- Rejected: `undefined`, `Date`, plain objects, `NaN` / `Infinity`.
+- Rejected (`misuse`): `DataView`, typed-array views other than `Uint8Array`, `SharedArrayBuffer` / SAB-backed buffers.
+- Rejected (`datatype_mismatch`): `undefined`, `Date`, plain objects, `NaN` / `Infinity`.
 
 ```ts
 db.query(`SELECT ? AS a, :name AS b`, [1, "Alice"]);
-db.prepare(`SELECT @id AS id`).bind(42).get();
+db.prepare(`SELECT @id AS id`).get(42);
 ```
 
 ### Returned JavaScript types
@@ -166,12 +167,13 @@ Duplicate column names collapse in row objects (last write wins). Use `stmt.resu
 
 ### Snapshots
 
-- Format magic `SQLM` — **not** a portable `.sqlite` file and not loadable by the SQLite CLI.
+- Format magic `SQLM` followed by an explicit little-endian format-version `u32` — **not** a portable `.sqlite` file and not loadable by the SQLite CLI.
 - Round-trips ordinary tables, views, indexes, change counters, PRNG state, and clock.
 - **Not** encoded: triggers, ATTACH’d schemas, virtual tables (FTS / RTREE / …), `userVersion`.
 - Cannot `restore()` while a transaction is open.
 - `restore()` replaces `now` with a fixed clock from the snapshot (a live `() => Date` is overwritten).
-- Equivalent databases produce byte-identical snapshots (schema/rows sorted).
+- Equivalent databases produce byte-identical snapshots (schema/rows sorted) **within a single library version**.
+- **Compatibility policy:** newer library versions can always restore older snapshots; older libraries cannot restore newer format versions (`snapshot_version` / `SQLITE_FORMAT`). Corrupt magic yields a distinct error.
 
 ## Determinism
 
@@ -179,7 +181,7 @@ The engine is deterministic by default. Invariants:
 
 | Source | Default | Override / notes |
 | --- | --- | --- |
-| `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` or `{ prng }` |
+| `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` |
 | `date('now')` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) })` |
 | Table scans | Rowid order | Same order after `snapshot`/`restore` |
 | Snapshots | Sorted schema/rows + PRNG state + clock | Restored into PRNG and `now` |
@@ -194,6 +196,15 @@ SQLITE_MEM_FUZZ_SEED=12345 bun test tests/fuzz
 SQLITE_MEM_FUZZ_SEED=12345 SQLITE_MEM_FUZZ_PATH='0:1' bun test tests/fuzz  # exact replay
 ```
 
+## Stability policy
+
+The exports of the main entry (`@crvouga/sqlite-mem`) are **frozen**:
+
+- **Never** outside a major: removals, renames, signature changes, or changes to documented behavior of the stable surface.
+- **Allowed in minors:** additions (new methods, new optional `DatabaseOptions` fields, new `ErrorCategory` values). Consumers that `switch` on `category` must include a default case — new categories may appear without a major bump.
+- **`@crvouga/sqlite-mem/unstable`** is exempt from semver and may change or disappear in any release.
+- **Snapshots:** newer library → can restore older blobs; older library → cannot restore newer format versions; byte-identical snapshot guarantee holds only within one library version.
+
 ## Compatibility notes for integrators
 
 Goal: drop-in SQL behavior vs SQLite **3.51.0**. Full matrix: [COMPATIBILITY.md](COMPATIBILITY.md).
@@ -205,20 +216,21 @@ Goal: drop-in SQL behavior vs SQLite **3.51.0**. Full matrix: [COMPATIBILITY.md]
 - FTS3/4/5 — largely implemented; shadow-table change counters intentionally diverge; some edges partial
 - `EXPLAIN` / `EXPLAIN QUERY PLAN` — stub shapes, not real bytecode
 - `INDEXED BY` / `NOT INDEXED` — parsed and discarded
-- Unknown `PRAGMA` succeeds with an empty result (SQLite-like); storage/journal/WAL pragmas N/A or no-op
+- Unknown statement `PRAGMA` succeeds with an empty result (SQLite-like). All oracle-exposed `pragma_*` eponymous TVFs are supported (`SELECT * FROM pragma_table_info('t')`, bare `FROM pragma_database_list`, …). Storage/journal getters return bun `:memory:`-compatible defaults.
 
 ## Common pitfalls
 
 1. **Do not `await`** — the API is sync.
-2. **No named-object binds** — use positional arrays in declaration order.
-3. **Multi-statement `query`** returns only the last result set with columns.
-4. **`exec` returns `void`** — use `db.changes` / `stmt.run()` for counters.
+2. **No named-object binds and no sticky `bind()`** — pass positional rest args / arrays in declaration order to `query` / `run` / `all` / `get` / `result`.
+3. **`query` / `prepare` are single-statement only** — multi-statement scripts belong in `exec()` (which does not take bind parameters).
+4. **`exec` returns `void` and takes no params** — use `db.prepare(…).run(…)` or `db.query(…)` for binds; use `db.changes` / `stmt.run()` for counters.
 5. **`'now'` is not wall-clock** unless you pass `{ now: () => new Date() }`. Default is year 2000.
 6. **`random()` is seeded**, not OS entropy; snapshots restore the PRNG.
 7. **Snapshots are not `.sqlite` files** and do not round-trip FTS / triggers / ATTACH.
 8. **No better-sqlite3 extras** — no `iterate`, `pluck`/`raw`, `safeIntegers` option, `pragma()` helper, `loadExtension`, or SQLite-file `serialize()`.
-9. **Do not bind `Date` objects** — store unixepoch integers or ISO text.
+9. **Do not bind `Date` objects** — store unixepoch integers or ISO text. Do not bind `DataView` / non-`Uint8Array` typed arrays.
 10. **Do not use `Number.isInteger` for SQL REAL vs INTEGER** — use SQL `typeof()`.
+11. **Do not import `@crvouga/sqlite-mem/unstable` in application code** unless you accept breakage in any release.
 
 Working examples beyond this README: `examples/react-vite`, `tests/contract/api/`, `tests/contract/parameters/`, `tests/browser/run.ts`.
 

package/dist/api/database.d.ts

@@ -14,15 +14,17 @@ import { Statement } from "./statement.js";
  *
  * const db = new Database();
  * db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)");
- * db.exec("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+ * db.prepare("INSERT INTO users (name) VALUES (?)").run("Alice");
  * const users = db.query<{ id: number; name: string }>("SELECT * FROM users");
  * ```
  */
 export declare class Database {
-    /** Seed used to construct the PRNG when `options.prng` is omitted. */
+    /** Seed used to construct the PRNG. */
     readonly seed: number | bigint;
     private closed;
     private transactionSequence;
+    /** Depth of active {@link transaction} callbacks (not SQL BEGIN). */
+    private apiTransactionDepth;
     /**
      * Create an empty in-memory database.
      *
@@ -32,33 +34,34 @@ export declare class Database {
     /**
      * Execute SQL for its side effects (DDL/DML). Multiple statements are allowed.
      *
+     * Does not accept bind parameters — use {@link prepare} or {@link query}.
+     *
      * @param sql - SQL to run (semicolon-separated statements are ok).
-     * @param params - Bound parameters for `?` / `:name` placeholders.
-     * @throws {SqliteError} If the database is closed or the SQL fails.
+     * @throws {SqliteError} If the database is closed, extra arguments are passed, or the SQL fails.
      */
-    exec(sql: string, params?: readonly BindValue[]): void;
+    exec(sql: string): void;
     /**
-     * Execute a query and return all rows as objects keyed by column name.
+     * Execute a single-statement query and return all rows as objects keyed by column name.
      *
      * @typeParam T - Row shape. Defaults to {@link QueryRow}.
-     * @param sql - SQL SELECT (or any statement that produces a result set).
+     * @param sql - A single SQL statement (trailing `;` is fine).
      * @param params - Bound parameters for `?` / `:name` placeholders.
      * @returns All result rows.
-     * @throws {SqliteError} If the database is closed or the SQL fails.
+     * @throws {SqliteError} If the database is closed, `sql` is not a single statement, or execution fails.
      */
     query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[];
     /**
-     * Compile `sql` into a reusable {@link Statement}.
+     * Compile a single SQL statement into a reusable {@link Statement}.
      *
-     * @param sql - SQL to prepare.
-     * @throws {SqliteError} If the database is closed or `sql` cannot be parsed.
+     * @param sql - A single SQL statement (trailing `;` is fine). Multi-statement scripts are rejected.
+     * @throws {SqliteError} If the database is closed or `sql` cannot be prepared as one statement.
      */
     prepare(sql: string): Statement;
     /**
      * Run `fn` inside a transaction. Commits on success; rolls back if `fn` throws.
      *
      * Nested calls use SAVEPOINTs so an inner failure does not abort the outer
-     * transaction.
+     * transaction. Calling {@link close} from inside `fn` throws `misuse`.
      *
      * @param fn - Work to run while the transaction is open.
      * @returns The value returned by `fn`.
@@ -77,6 +80,8 @@ export declare class Database {
      * Replace this database's contents with a blob from {@link snapshot}.
      *
      * Restores PRNG state and the clock when the snapshot includes them (v2).
+     * Newer library versions can restore older snapshots; older libraries cannot
+     * restore newer format versions.
      *
      * @param snapshot - Bytes previously returned by {@link snapshot}.
      * @throws {SqliteError} If the database is closed, a transaction is open, or the blob is invalid.
@@ -85,7 +90,8 @@ export declare class Database {
     /**
      * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
      *
-     * Rolls back an open transaction, if any.
+     * Rolls back an open SQL transaction, if any. Throws if called from inside
+     * a {@link transaction} callback.
      */
     close(): void;
     /**
@@ -100,5 +106,6 @@ export declare class Database {
      * @throws {SqliteError} If the database is closed.
      */
     get lastInsertRowid(): number | bigint;
+    private prepareSingle;
 }
 export type { DatabaseOptions };

package/dist/api/statement.d.ts

@@ -10,9 +10,9 @@ export interface RunResult {
 /**
  * Prepared SQL statement bound to a {@link Database}.
  *
- * Create with {@link Database.prepare}. Extra arguments to {@link run},
- * {@link all}, {@link get}, or {@link result} override values from {@link bind};
- * otherwise the last `bind()` parameters are used.
+ * Create with {@link Database.prepare}. Pass bind values as rest arguments to
+ * {@link run}, {@link all}, {@link get}, or {@link result} on each call
+ * (stateless — there is no sticky `bind()`).
  *
  * @example
  * ```ts
@@ -28,25 +28,15 @@ export interface RunResult {
 export declare class Statement {
     private readonly database;
     private readonly sql;
-    private bound;
     private namedPlan;
     private env;
     private statements;
     private schemaVersion;
     private constructor();
-    /**
-     * Store parameters for later {@link run} / {@link all} / {@link get} / {@link result}.
-     *
-     * Supports positional `?` / `?NNN` and named `:name` / `@name` / `$name` placeholders.
-     *
-     * @param params - Values to bind, in placeholder order.
-     * @returns `this` for chaining.
-     */
-    bind(...params: BindValue[]): Statement;
     /**
      * Execute for side effects (INSERT / UPDATE / DELETE / DDL).
      *
-     * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+     * @param params - Bind values for this call only.
      * @returns Mutation counters for this execution.
      * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
      */
@@ -55,7 +45,7 @@ export declare class Statement {
      * Execute and return every result row as an object keyed by column name.
      *
      * @typeParam T - Row shape. Defaults to {@link QueryRow}.
-     * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+     * @param params - Bind values for this call only.
      * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
      */
     all<T = QueryRow>(...params: BindValue[]): T[];
@@ -65,7 +55,7 @@ export declare class Statement {
      * Use this when you need metadata for an empty result (column names with zero rows).
      * {@link all} only returns row objects.
      *
-     * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+     * @param params - Bind values for this call only.
      * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
      */
     result(...params: BindValue[]): ResultSet;
@@ -73,7 +63,7 @@ export declare class Statement {
      * Execute and return the first row, or `undefined` if there are no rows.
      *
      * @typeParam T - Row shape. Defaults to {@link QueryRow}.
-     * @param params - If provided, override the last {@link bind}; otherwise bound values are used.
+     * @param params - Bind values for this call only.
      * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
      */
     get<T = QueryRow>(...params: BindValue[]): T | undefined;

package/dist/errors/index.d.ts

@@ -1,8 +1,15 @@
-/** Coarse classification of {@link SqliteError} for catch-site branching. */
-export type ErrorCategory = "syntax" | "no_such_table" | "no_such_column" | "constraint_unique" | "constraint_primary" | "constraint_notnull" | "constraint_check" | "constraint_foreign" | "constraint" | "transaction" | "datatype_mismatch" | "unsupported" | "misuse" | "other";
+/** Coarse classification of {@link SqliteError} for catch-site branching.
+ *
+ * New categories may be added in minor releases. Consumers that switch on
+ * `category` must include a default case.
+ */
+export type ErrorCategory = "syntax" | "no_such_table" | "no_such_column" | "constraint_unique" | "constraint_primary" | "constraint_notnull" | "constraint_check" | "constraint_foreign" | "constraint" | "transaction" | "datatype_mismatch" | "unsupported" | "misuse" | "snapshot_version" | "other" | (string & {});
 /**
  * Engine error. `name` is always `"SqliteError"`.
  *
+ * `sqliteCode` and Node's conventional `code` property are always set (default
+ * `"SQLITE_ERROR"` when no more specific code applies).
+ *
  * @example
  * ```ts
  * import { Database, SqliteError } from "@crvouga/sqlite-mem";
@@ -20,12 +27,14 @@ export type ErrorCategory = "syntax" | "no_such_table" | "no_such_column" | "con
 export declare class SqliteError extends Error {
     /** Coarse error class (constraint vs syntax vs missing object, …). */
     readonly category: ErrorCategory;
-    /** Optional SQLite result-code name such as `SQLITE_CONSTRAINT`. */
-    readonly sqliteCode?: string;
+    /** SQLite result-code name such as `SQLITE_CONSTRAINT_UNIQUE`. */
+    readonly sqliteCode: string;
+    /** Same value as {@link sqliteCode} (Node `err.code` convention). */
+    readonly code: string;
     /**
      * @param message - Human-readable error text.
      * @param category - Coarse class; defaults to `"other"`.
-     * @param sqliteCode - Optional SQLite result-code name.
+     * @param sqliteCode - SQLite result-code name; defaults to `"SQLITE_ERROR"`.
      */
     constructor(message: string, category?: ErrorCategory, sqliteCode?: string);
 }

package/dist/executor/pragma-engine.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared PRAGMA query engine used by statement-form `PRAGMA …` and `pragma_*` TVFs.
+ */
+import type { Expr } from "../ast/nodes.js";
+import { type SqlValue } from "../types/value.js";
+import type { ExecutionEnv } from "./env.js";
+export interface PragmaQueryResult {
+    columns: string[];
+    rows: SqlValue[][];
+}
+/** Oracle-exposed pragma_* TVF base names (without the `pragma_` prefix). */
+export declare const PRAGMA_TVF_NAMES: readonly ["analysis_limit", "application_id", "auto_vacuum", "automatic_index", "busy_timeout", "cache_size", "cache_spill", "cell_size_check", "checkpoint_fullfsync", "collation_list", "compile_options", "count_changes", "data_version", "database_list", "default_cache_size", "defer_foreign_keys", "empty_result_callbacks", "encoding", "foreign_key_check", "foreign_key_list", "foreign_keys", "freelist_count", "full_column_names", "fullfsync", "function_list", "hard_heap_limit", "ignore_check_constraints", "index_info", "index_list", "index_xinfo", "integrity_check", "journal_mode", "journal_size_limit", "legacy_alter_table", "locking_mode", "max_page_count", "module_list", "optimize", "page_count", "page_size", "pragma_list", "query_only", "quick_check", "read_uncommitted", "recursive_triggers", "reverse_unordered_selects", "schema_version", "secure_delete", "short_column_names", "soft_heap_limit", "synchronous", "table_info", "table_list", "table_xinfo", "temp_store", "threads", "trusted_schema", "user_version", "writable_schema"];
+/** Full pragma name list for `pragma_pragma_list` (includes names without TVFs). */
+export declare const PRAGMA_LIST_NAMES: string[];
+export declare function isPragmaTvfName(name: string): boolean;
+/**
+ * Query a pragma by name with optional SQL values (TVF args or evaluated statement args).
+ * Read-only — writers stay in {@link executePragma}.
+ */
+export declare function queryPragma(name: string, args: readonly SqlValue[], env: ExecutionEnv): PragmaQueryResult;
+/** Evaluate a statement-form pragma argument expression to a SQL value list. */
+export declare function evalPragmaArgs(expr: Expr | null, env: ExecutionEnv): SqlValue[];
+export declare function evalPragmaSetValue(expr: Expr, env: ExecutionEnv): SqlValue;
+export declare function coercePragmaInt(value: SqlValue): number;
+export declare function coercePragmaTruthy(value: SqlValue): boolean;

package/dist/executor/result.d.ts

@@ -5,8 +5,8 @@ export interface ResultSet {
     columns: string[];
     /** Named rows. Duplicate column names keep the last value. */
     rows: QueryRow[];
-    /** Positional rows preserve duplicate result-column names for internal use. */
-    values?: QueryValue[][];
+    /** Positional rows; always present (empty array when there are zero rows). */
+    values: QueryValue[][];
     /** Rows changed by the most recent mutating statement in this execution. */
     changes: number;
     /** Rowid of the most recent INSERT in this execution. */

package/dist/functions/pragma-tvf.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Register all oracle-exposed `pragma_*` eponymous table-valued functions.
+ * Imported for side effects from table-valued / select.
+ */
+import { isPragmaTvfName } from "../executor/pragma-engine.js";
+/** Idempotent registration of every oracle `pragma_*` TVF. */
+export declare function ensurePragmaTvfsRegistered(): void;
+export { isPragmaTvfName };

package/dist/functions/table-valued-registry.d.ts

@@ -0,0 +1,11 @@
+import type { ExecutionEnv, ScopeRow } from "../executor/env.js";
+import type { SqlValue } from "../types/value.js";
+export interface TableValuedResult {
+    columns: string[];
+    rows: ScopeRow[];
+}
+export type TableValuedFn = (args: SqlValue[], alias: string | null, env: ExecutionEnv) => TableValuedResult;
+export declare function registerTableValuedFunction(name: string, fn: TableValuedFn): void;
+export declare function getTableValuedFunction(name: string): TableValuedFn | undefined;
+export declare function listRegisteredTableValuedFunctions(): string[];
+export declare function hasRegisteredTableValuedFunction(name: string): boolean;

package/dist/functions/table-valued.d.ts

@@ -1,8 +1,8 @@
 import type { Expr } from "../ast/nodes.js";
 import type { ExecutionEnv, ScopeRow } from "../executor/env.js";
-export interface TableValuedResult {
-    columns: string[];
-    rows: ScopeRow[];
-}
+import { registerTableValuedFunction, type TableValuedResult } from "./table-valued-registry.js";
+export type { TableValuedResult };
+export { registerTableValuedFunction };
 export declare function evaluateTableFunction(name: string, args: Expr[], alias: string | null, env: ExecutionEnv, scope?: ScopeRow | null, parent?: import("../expressions/context.js").EvalContext): TableValuedResult;
 export declare function listTableValuedFunctions(): string[];
+export declare function hasTableValuedFunction(name: string): boolean;

package/dist/index.d.ts

@@ -5,29 +5,23 @@
  * Deterministic by default (`random()` seed `1`, `'now'` = `2000-01-01T00:00:00.000Z`).
  * Zero WASM, native bindings, or filesystem.
  *
+ * Advanced / internal helpers live under `@crvouga/sqlite-mem/unstable` and are
+ * exempt from semver.
+ *
  * @example
  * ```ts
  * import { Database } from "@crvouga/sqlite-mem";
  *
  * const db = new Database();
  * db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)");
- * db.exec("INSERT INTO t (name) VALUES (?)", ["Ada"]);
+ * db.prepare("INSERT INTO t (name) VALUES (?)").run("Ada");
  * const rows = db.query<{ id: number; name: string }>("SELECT * FROM t");
  * ```
  *
  * @module
  */
-export * from "./api/database.js";
+export { Database, type DatabaseOptions } from "./api/database.js";
 export { Statement, type RunResult } from "./api/statement.js";
-export type { Expr } from "./ast/nodes.js";
 export { SqliteError, type ErrorCategory } from "./errors/index.js";
 export type { ResultSet } from "./executor/result.js";
-export type { EvalContext } from "./expressions/context.js";
-export { evalExpr } from "./expressions/eval.js";
-export { globMatch, likeMatch } from "./expressions/like.js";
-export { tokenize, type Token, type TokenKind } from "./lexer/tokenize.js";
-export { parse, type ParsedStatement } from "./parser/index.js";
-export { type Clock, DEFAULT_DATABASE_SEED, DEFAULT_NOW, deriveSeed, fixedClock, Prng, resolveClock, } from "./runtime/index.js";
-export { type DecodedSnapshot, decodeDatabaseState, encodeDatabaseState, type SnapshotRuntime, } from "./serialization/index.js";
-export type { DatabaseState } from "./storage/database-state.js";
-export { type Affinity, affinityFromTypeName, applyAffinity, asSqlJsonText, asSqlReal, type BindValue, canonicalizeNumber, cloneSqlValue, coerceToNumber, compareSql, isSqlJsonText, isSqlReal, isTruthySql, type QueryRow, type QueryValue, SqlJsonText, SqlReal, type SqlValue, type StorageClass, sqlValueEquals, storageClassOf, toInteger, typeofSql, utf8Decode, utf8Encode, } from "./types/value.js";
+export type { BindValue, QueryRow, QueryValue } from "./types/value.js";