@crvouga/sqlite-mem 1.8.1 → 1.10.0

package/AGENTS.md

@@ -154,4 +154,4 @@ bun run build
 
 ## PR and commits
 
-Use [Conventional Commits](https://www.conventionalcommits.org/) for commits and PR titles (enforced in CI). Prefer squash merges with a conventional title. Releasing is automated via semantic-release — see [README.md](README.md#releasing).
+Use [Conventional Commits](https://www.conventionalcommits.org/) for commits and PR titles (enforced on PRs). Prefer squash merges with a conventional title so the npm bump is `feat` → minor / `fix` → patch. Direct pushes to `main` with any other subject still publish a patch. See [README.md](README.md#releasing).

package/README.md

@@ -1,5 +1,7 @@
 # sqlite-mem
 
+[npm](https://www.npmjs.com/package/@crvouga/sqlite-mem) · [GitHub](https://github.com/crvouga/sqlite-mem)
+
 Pure TypeScript, completely in-memory SQLite implementation aiming for **full SQLite3 SQL dialect parity** (same statements → same results).
 
 - Runs in modern browsers and Node.js / Bun
@@ -41,7 +43,7 @@ Requires Node.js ≥ 20 or Bun ≥ 1.1. The published package is **ESM only** (`
 ## Usage
 
 ```ts
-import { Database } from "@crvouga/sqlite-mem";
+import { Database, Snapshot } from "@crvouga/sqlite-mem";
 
 const db = new Database();
 
@@ -57,9 +59,10 @@ db.prepare(`INSERT INTO users (name) VALUES (?)`).run("Alice");
 const users = db.query<{ id: number; name: string }>(`SELECT * FROM users`);
 console.log(users);
 
-const snap = db.snapshot();
-const db2 = new Database();
-db2.restore(snap);
+const seed = db.snapshot();
+const db2 = seed.open();
+const bytes = seed.encode();
+const db3 = Snapshot.decode(bytes).open();
 ```
 
 All methods are **synchronous** — do not `await` them. Browser and Node/Bun share the same in-memory JS surface (no filesystem; `ATTACH` opens a new empty in-memory schema, not a file).
@@ -79,7 +82,7 @@ From the repo root after that install: `bun run example`.
 ## API
 
 ```ts
-import { Database, SqliteError } from "@crvouga/sqlite-mem";
+import { Database, Snapshot, SqliteError } from "@crvouga/sqlite-mem";
 
 interface DatabaseOptions {
   seed?: number | bigint;                 // default 1 — ignored when random is "os"
@@ -93,8 +96,7 @@ interface Database {
   query<T = QueryRow>(sql: string, params?: BindValue[]): T[];
   prepare(sql: string): Statement;
   transaction<T>(fn: () => T): T;
-  snapshot(): Uint8Array;
-  restore(snapshot: Uint8Array): void;
+  snapshot(): Snapshot;
   close(): void;
   [Symbol.dispose]?(): void;        // alias for close() when Symbol.dispose exists
   readonly changes: number;
@@ -121,6 +123,12 @@ interface ResultSet {
   lastInsertRowid: number | bigint;
 }
 
+class Snapshot {
+  open(options?: DatabaseOptions): Database;
+  encode(): Uint8Array;
+  static decode(bytes: Uint8Array): Snapshot;
+}
+
 class SqliteError extends Error {
   readonly category: ErrorCategory; // syntax, no_such_table, constraint_unique, misuse, …
   readonly sqliteCode: string;      // always set; default "SQLITE_ERROR"
@@ -128,7 +136,7 @@ class SqliteError extends Error {
 }
 ```
 
-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**.
+Stick to `Database`, `Snapshot`, `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
 
@@ -138,7 +146,10 @@ Stick to `Database`, `Statement`, and `SqliteError` for application code. Advanc
 | `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). |
+| `snapshot()` | Freeze a reusable {@link Snapshot} template (no encode). Illegal inside a transaction. |
+| `Snapshot.open()` | Copy-on-write fork from a template. Parent stays open. |
+| `Snapshot.encode()` | Lazy SQLM blob for persistence / worker boot (computed once, cached). |
+| `Snapshot.decode(bytes)` | Decode a blob once per `Uint8Array` (WeakMap); later `open()` calls are CoW. |
 | `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 / comment-only SQL on `prepare` / `query` throws `misuse` (`empty statement`), matching SQLite prepare failure.
@@ -174,13 +185,17 @@ Duplicate column names collapse in row objects (last write wins). Use `stmt.resu
 
 ### Snapshots
 
+- `db.snapshot()` returns a frozen in-memory {@link Snapshot}. Per-test isolation should `seed.open()` (copy-on-write, ~µs). Encoded bytes are **lazy** via `snapshot.encode()`.
 - 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.
+- Round-trips ordinary tables, views, indexes (SQLM v4 compact index keys; v3 persisted full `IndexStore`; v1/v2 blobs rebuild indexes on hydrate), 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). `{ now: "system" }` stays live after restore.
-- 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.
+- Cannot `snapshot()` while a transaction is open.
+- `Snapshot.decode(bytes)` does not mutate the input `Uint8Array`. The same buffer object is decoded once (WeakMap) and later opens are CoW.
+- `open()` shares frozen tables until either side writes; idle `open().snapshot().encode()` is byte-identical to `snapshot().encode()`.
+- `open()` uses a fixed clock from the snapshot unless you pass `{ now: "system" }`, which stays live.
+- Equivalent databases produce byte-identical `encode()` output (schema/rows sorted) **within a single library version**.
+- Per-test isolation (CI-tier, 200 users + 800 items): `Snapshot.open` ~µs; `encode()` / `decode().open()` is the persistence path. See [benchmarks/PERFORMANCE.md](benchmarks/PERFORMANCE.md).
+- **Compatibility policy:** newer library versions can always decode older snapshots; older libraries cannot decode newer format versions (`snapshot_version` / `SQLITE_FORMAT`). Corrupt magic yields a distinct error.
 
 ## Determinism
 
@@ -189,9 +204,9 @@ The engine is deterministic by default. Invariants:
 | Source | Default | Override / notes |
 | --- | --- | --- |
 | `random()` / `randomblob()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` or `{ random: "os" }` for CSPRNG (not rolled back / not restored) |
-| `date('now')` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })` — `"system"` is wall clock and is **not** frozen by `restore()` |
-| Table scans | Rowid order | Same order after `snapshot`/`restore` |
-| Snapshots | Sorted schema/rows + PRNG state + clock | Restored into PRNG and `now` |
+| `date('now')` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })` — `"system"` is wall clock and is **not** frozen by `open()` |
+| Table scans | Rowid order | Same order after `snapshot`/`open` |
+| Snapshots | Sorted schema/rows + PRNG state + clock | Applied by `open()` into PRNG and `now` |
 | Transactions | PRNG rolls back with `ROLLBACK`/`SAVEPOINT` | Matches data rollback |
 | Numbers | IEEE `-0` canonicalized to `+0` | Bind, affinity, and arithmetic |
 
@@ -238,7 +253,7 @@ This is **not** a drop-in replacement for `sql.js`, `@sqlite.org/sqlite-wasm`, o
 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: "system" }` or `{ now: () => new Date() }`. Default is year 2000. `restore()` freezes a snapshot clock except when constructed with `"system"`.
+5. **`'now'` is not wall-clock** unless you pass `{ now: "system" }` or `{ now: () => new Date() }`. Default is year 2000. `open()` freezes a snapshot clock except when constructed with `"system"`.
 6. **`random()` is seeded**, not OS entropy, unless you pass `{ random: "os" }`. Snapshots restore the seeded PRNG; OS entropy is not rewound.
 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()`.
@@ -274,16 +289,16 @@ Publishing is fully automated. You never bump `version` or run `npm publish` by
 
 ### How a release happens
 
-1. Push or merge to `main` with [Conventional Commits](https://www.conventionalcommits.org/).
+1. Push or merge to `main`. Prefer [Conventional Commits](https://www.conventionalcommits.org/) so the bump is `feat` → minor / `fix` → patch / `BREAKING` → major; any other subject still publishes a patch.
 2. CI runs commitlint, format/lint/typecheck, build, package verification, tests, browser smoke, and benchmarks.
 3. If every gate is green, [semantic-release](https://semantic-release.gitbook.io/) analyzes commits since the last git tag, bumps semver, publishes to npm, and creates a GitHub Release.
 
 | Commit | Version bump |
 | --- | --- |
-| `fix: …` | patch (`0.1.0` → `0.1.1`) |
-| `feat: …` | minor (`0.1.0` → `0.2.0`) |
-| `feat!: …` or `BREAKING CHANGE:` footer | major (`0.2.0` → `1.0.0`) |
-| `docs:`, `chore:`, `refactor:`, `test:`, … | no release |
+| `fix: …` / `perf: …` | patch (`1.9.0` → `1.9.1`) |
+| `feat: …` | minor (`1.9.0` → `1.10.0`) |
+| `feat!: …` or `BREAKING CHANGE:` footer | major (`1.10.0` → `2.0.0`) |
+| any other message on `main` (including Cursor-style subjects) | patch |
 
 Examples:
 
@@ -292,8 +307,7 @@ feat: add window function support
 fix: handle NULL in UNIQUE constraints
 feat!: rename snapshot() return type
 
-chore: tweak CI timeouts
-docs: clarify determinism table
+Refactor AdoptedDatabase interface   # still publishes a patch
 ```
 
 PR titles must also follow Conventional Commits (enforced in CI). Prefer squash merges with a conventional title.
@@ -327,7 +341,7 @@ Do this once so CI can publish. Full checklist: **[docs/SECRETS.md](./docs/SECRE
 
 Validate the checklist anytime with `bun run secrets:doctor`.
 
-After that, every green push to `main` with releasable commits updates npm automatically.
+After that, every green push to `main` updates npm automatically (`feat`/`fix`/`BREAKING` pick the bump; anything else is a patch).
 
 ## License
 

package/compat/divergences.json

@@ -11,8 +11,8 @@
     {
       "id": "snapshot-sqlm",
       "scope": "snapshot",
-      "predicate": "snapshot() bytes are SQLM, not a .sqlite file",
-      "specifiedBehavior": "Custom codec; logical Dump after restore matches pre-snapshot Dump.",
+      "predicate": "snapshot().encode() bytes are SQLM, not a .sqlite file",
+      "specifiedBehavior": "Custom codec; logical Dump after Snapshot.open matches pre-snapshot Dump.",
       "pinnedBy": ["SNP-hdr-01", "SNP-rt-01"]
     },
     {
@@ -82,7 +82,7 @@
       "id": "snapshot-exclusions",
       "scope": "snapshot",
       "predicate": "triggers, ATTACH, virtual tables, and user_version are not in SQLM",
-      "specifiedBehavior": "restore() outcome is pinned per omitted feature.",
+      "specifiedBehavior": "decode().open() outcome is pinned per omitted feature.",
       "pinnedBy": ["SNP-omit-01", "SNP-omit-02", "SNP-omit-03", "SNP-omit-04", "TRG-snap-01", "ATT-snap-01", "FTS-snap-01"]
     },
     {
@@ -116,8 +116,8 @@
     {
       "id": "user-version-snapshot",
       "scope": "pragma",
-      "predicate": "user_version is not restored from SQLM",
-      "specifiedBehavior": "PRAGMA user_version after restore is the default unless re-set.",
+      "predicate": "user_version is not encoded in SQLM",
+      "specifiedBehavior": "PRAGMA user_version after decode().open() is the default unless re-set.",
       "pinnedBy": ["PRG-beh-05", "SNP-omit-04"]
     },
     {

package/compat/scenarios.ts

@@ -371,7 +371,7 @@ const TAIL: CatalogSection[] = [
       ["now-03", "column DEFAULT CURRENT_TIMESTAMP", D, "README"],
       ["now-04", "now system tracks wall clock", D, "README"],
       ["now-05", "now fn called per statement", D, "README"],
-      ["now-06", "restore freezes clock", D, "README"],
+      ["now-06", "open freezes clock", D, "README"],
     ]),
     section("JSN", "JSON", true, [
       ["json-01", "json() minify/validate"],
@@ -756,15 +756,21 @@ const TAIL: CatalogSection[] = [
       ["hdr-02", "corrupt magic error"],
       ["hdr-03", "truncated blob error"],
       ["hdr-04", "future version snapshot_version"],
-      ["txn-01", "restore during txn errors"],
-      ["rep-01", "restore replaces entire state"],
-      ["now-01", "restore keeps system clock live", D],
-      ["now-02", "restore overwrites Date fn", D],
-      ["rng-01", "restore with random os does not rewind", D],
+      ["txn-01", "snapshot during txn errors"],
+      ["now-01", "open with system clock stays live", D],
+      ["now-02", "open overwrites Date fn with snapshot clock", D],
+      ["rng-01", "open with random os does not rewind", D],
       ["omit-01", "triggers not encoded", D],
       ["omit-02", "ATTACH not encoded", D],
       ["omit-03", "virtual tables not encoded", D],
       ["omit-04", "user_version not encoded", D],
+      ["open-01", "Snapshot.open CoW fork"],
+      ["open-02", "encode does not mutate; decode reuses buffer"],
+      ["prop-01", "snapshot restore idempotence", F, undefined, ["tests/fuzz/snapshot.test.ts"]],
+      ["prop-02", "insert-then-delete probe preservation", F, undefined, ["tests/fuzz/snapshot.test.ts"]],
+      ["prop-03", "index probe equivalence after restore", F, undefined, ["tests/fuzz/snapshot.test.ts"]],
+      ["obj-01", "object round-trip corpus", F, undefined, ["tests/contract/snapshots/objects.test.ts"]],
+      ["obj-02", "view and index probes after restore", F, undefined, ["tests/contract/snapshots/views-indexes.test.ts"]],
     ]),
     section("DET", "Determinism invariants", true, [
       ["seed-01", "same seed identical random streams", D],
@@ -828,9 +834,10 @@ const TAIL: CatalogSection[] = [
       ["robust-01", "SqliteError-only / timeout / SQLM bit-flip", F],
       ["slt-01", "sqllogictest vendor corpus differential", F],
       ["dst-01", "mixed dump-after-each DST engine", F],
-      ["prop-01", "snapshot restore idempotence", P],
-      ["prop-02", "insert then delete snapshot bytes", P],
-      ["prop-03", "index-added vs index-free equivalence", P],
+      ["snap-01", "snapshot restore probe fuzz", F, undefined, ["tests/fuzz/snapshot.test.ts"]],
+      ["prop-01", "classifyDiff equal outcome", P, undefined, ["tests/contract/catalog/fzz.test.ts"]],
+      ["prop-02", "classifyDiff failure outcome", P, undefined, ["tests/contract/catalog/fzz.test.ts"]],
+      ["prop-03", "classifyDiff known-divergence outcome", P, undefined, ["tests/contract/catalog/fzz.test.ts"]],
       ["prop-04", "transaction throw never ran", P],
       ["prop-05", "exec a;b equivalent split exec", P],
       ["seed-01", "default seed 0x5a17e0e1", F],

package/dist/api/database.d.ts

@@ -1,5 +1,6 @@
 import { type DatabaseOptions, type RandomMode } from "../runtime/index.js";
 import type { BindValue, QueryRow } from "../types/value.js";
+import { type Snapshot } from "./snapshot.js";
 import { Statement } from "./statement.js";
 /**
  * Pure TypeScript in-memory SQLite database.
@@ -72,24 +73,14 @@ export declare class Database {
      */
     transaction<T>(fn: () => T): T;
     /**
-     * Serialize schema, rows, PRNG state, and clock into a custom snapshot blob.
+     * Freeze this database into a reusable {@link Snapshot} template.
      *
-     * This is not a `.sqlite` file. Restore it with {@link restore}.
+     * Does not encode SQLM bytes. Call {@link Snapshot.encode} to persist, or
+     * {@link Snapshot.open} for a copy-on-write fork.
      *
-     * @throws {SqliteError} If the database is closed.
-     */
-    snapshot(): Uint8Array;
-    /**
-     * 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.
+     * @throws {SqliteError} If the database is closed or a transaction is open.
      */
-    restore(snapshot: Uint8Array): void;
+    snapshot(): Snapshot;
     /**
      * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
      *
@@ -117,4 +108,5 @@ export declare class Database {
     get totalChanges(): number;
     private prepareSingle;
 }
+export { Snapshot } from "./snapshot.js";
 export type { DatabaseOptions };

package/dist/api/snapshot.d.ts

@@ -0,0 +1,21 @@
+import { type DatabaseOptions } from "../runtime/index.js";
+import { type Database } from "./database.js";
+/**
+ * Frozen in-memory database template. {@link open} is a copy-on-write fork.
+ * Encoded SQLM bytes are produced lazily via {@link encode}.
+ */
+export declare class Snapshot {
+    private cachedBytes;
+    /** Encoded SQLM blob. Computed once; never mutates a buffer passed to {@link decode}. */
+    encode(): Uint8Array;
+    /**
+     * Copy-on-write database from this frozen template. Does not re-encode or re-decode.
+     */
+    open(options?: DatabaseOptions): Database;
+    /**
+     * Decode `bytes` once and freeze the result. The same `Uint8Array` object
+     * returns the same {@link Snapshot} (WeakMap), so later {@link open} calls
+     * are copy-on-write forks after the first hydrate.
+     */
+    static decode(bytes: Uint8Array): Snapshot;
+}

package/dist/constraints/check.d.ts

@@ -1,11 +1,11 @@
 import type { Expr } from "../ast/nodes.js";
 import type { IndexStore } from "../indexes/index.js";
 import type { Row, Rowid } from "../storage/row.js";
-import type { ColumnInfo, Table } from "../storage/table.js";
+import type { Table } from "../storage/table.js";
 import type { SqlValue } from "../types/value.js";
 export type CheckEvaluator = (expr: Expr, row: Row) => SqlValue;
-export declare function checkNotNull(columns: readonly ColumnInfo[], row: Row, tableName?: string): void;
-export declare function checkPrimaryKey(columns: readonly ColumnInfo[], row: Row, tableName?: string): void;
+export declare function checkNotNull(table: Table, row: Row): void;
+export declare function checkPrimaryKey(table: Table, row: Row): void;
 export declare function checkUnique(index: IndexStore, values: readonly SqlValue[], rowid?: Rowid): void;
 export declare function checkExpressions(expressions: readonly Expr[], row: Row, evaluate: CheckEvaluator, constraintName?: string): void;
 export declare function checkTableConstraints(table: Table, row: Row, evaluate: CheckEvaluator): void;

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  *
  * @module
  */
-export { Database, type DatabaseOptions } from "./api/database.js";
+export { Database, Snapshot, type DatabaseOptions } from "./api/database.js";
 export { type RunResult, Statement } from "./api/statement.js";
 export { type ErrorCategory, SqliteError } from "./errors/index.js";
 export type { ResultSet } from "./executor/result.js";