@crvouga/mockingbird-service-sqlite 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog — @crvouga/mockingbird-service-sqlite
 
-## 0.2.0 (2026-09-22)
+## 1.0.0 (2026-09-24)
+
+### ⚠️ Breaking changes
+
+- vendor branding for every service; purge internal mocks and consumer names ([f689534](https://github.com/crvouga/mockingbird/commit/f6895343543550dafcb7d76b426cae7635e03226))
+
+## 0.3.0 (2026-09-22)
+
+### Features
+
+- add deterministic time travel and branching ([a6c341f](https://github.com/crvouga/mockingbird/commit/a6c341f9476f09227a1be4fe830942e4f60c17d9))
+
+## 0.2.0 (2026-09-21)
 
 ### Features
 

package/README.md

@@ -148,10 +148,11 @@ wrapped `bun:sqlite`) also satisfies the port.
 | Method | Behaviour |
 | --- | --- |
 | `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` / `db.lastInsertRowid` afterwards 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`. |
+| `query(sql, params?, { at? }?)` | **Single statement only** (trailing `;` is fine). Returns all rows. `at` queries an immutable checkpoint without changing live state. Multi-statement scripts throw `misuse`. |
 | `prepare(sql)` | **Single statement only**. Parses immediately; the 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. A nested SQL `BEGIN` still errors. `close()` inside `fn` throws `misuse`. |
 | `snapshot()` | Freeze a reusable `Snapshot` template (no encode). Illegal inside a transaction. |
+| `checkpoint()` / `branch(at?)` | Name a COW snapshot as a checkpoint; open an isolated branch from it (or current state). |
 | `Snapshot.open()` | Copy-on-write fork from a template. The 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 copy-on-write. |
@@ -305,10 +306,12 @@ interface DatabaseOptions {
 class Database {
   constructor(options?: DatabaseOptions)
   exec(sql: string): void
-  query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[]
+  query<T = QueryRow>(sql: string, params?: readonly BindValue[], options?: { at?: Snapshot }): T[]
   prepare(sql: string): Statement
   transaction<T>(fn: () => T): T
   snapshot(): Snapshot
+  checkpoint(): Snapshot
+  branch(at?: Snapshot): Database
   close(): void                             // also [Symbol.dispose] when available
   readonly changes: number
   readonly lastInsertRowid: number | bigint

package/dist/api/database.d.ts

@@ -2,6 +2,11 @@ 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";
+/** Additive time-travel controls for read APIs. */
+export interface QueryOptions {
+    /** Execute against this immutable checkpoint instead of the live database. */
+    at?: Snapshot;
+}
 /**
  * Pure TypeScript in-memory SQLite database.
  *
@@ -53,7 +58,7 @@ export declare class Database {
      * @returns All result rows.
      * @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[];
+    query<T = QueryRow>(sql: string, params?: readonly BindValue[], options?: QueryOptions): T[];
     /**
      * Compile a single SQL statement into a reusable {@link Statement}.
      *
@@ -81,6 +86,10 @@ export declare class Database {
      * @throws {SqliteError} If the database is closed or a transaction is open.
      */
     snapshot(): Snapshot;
+    /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
+    checkpoint(): Snapshot;
+    /** Open a copy-on-write branch from `at`, or from the current state when omitted. */
+    branch(at?: Snapshot): Database;
     /**
      * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
      *

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  *
  * @module
  */
-export { Database, type DatabaseOptions, Snapshot } from "./api/database.js";
+export { Database, type DatabaseOptions, type QueryOptions, Snapshot } 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";

package/dist/index.js

@@ -15848,8 +15848,9 @@ var Database = class {
    * @returns All result rows.
    * @throws {SqliteError} If the database is closed, `sql` is not a single statement, or execution fails.
    */
-  query(sql, params = []) {
+  query(sql, params = [], options = {}) {
     this.assertOpen();
+    if (options.at) return options.at.open().query(sql, params);
     return this.prepareSingle(sql).all(...params);
   }
   /**
@@ -15917,6 +15918,15 @@ var Database = class {
     }
     return captureSnapshot(this.state, this.prng, this.now, this.seed, this.randomMode, this.systemClock);
   }
+  /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
+  checkpoint() {
+    return this.snapshot();
+  }
+  /** Open a copy-on-write branch from `at`, or from the current state when omitted. */
+  branch(at = this.snapshot()) {
+    this.assertOpen();
+    return at.open();
+  }
   /**
    * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
    *