@crvouga/mockingbird-service-postgres 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog — @crvouga/mockingbird-service-postgres
 
-## 0.2.0 (2026-09-22)
+## 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

@@ -157,11 +157,12 @@ back as PostgreSQL text (node-postgres parses timestamps to `Date` and JSON to o
 | --- | --- |
 | `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` afterwards if needed (reflects the **most recent** completed DML statement). Dump-only `DO` blocks and `ALTER TABLE ... SET (` storage parameters are no-ops. |
 | `registerFunction(spec)` | Install a JavaScript scalar. Not stored in PGMM snapshots; `open()` of a live snapshot copies the implementation by reference. |
-| `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` / `textResult` on each call. |
 | `transaction(fn)` | If idle: `BEGIN`, `fn()`, `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. A nested SQL `BEGIN` inside is a no-op warning like PostgreSQL. `close()` inside `fn` throws `misuse`. |
 | `copyFrom(sql, data)` | Executes `COPY table [(cols)] FROM STDIN` with `data` as the copy-in payload (text or csv per the COPY options). Returns rows copied. `COPY ... TO STDOUT` output is returned as result rows by `query`. |
 | `snapshot()` | Freeze a reusable `Snapshot` template (no encode). Illegal inside a transaction (`25P01`). |
+| `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 PGMM 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. |
@@ -313,11 +314,13 @@ class Database {
   exec(sql: string): void
   registerFunction(spec: { name: string; args: string[]; returns: string; strict?: boolean;
                            fn: (...args: JsValue[]) => JsValue }): 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
   copyFrom(sql: string, data: string): number   // COPY t FROM STDIN payload (\copy analog)
   snapshot(): Snapshot
+  checkpoint(): Snapshot
+  branch(at?: Snapshot): Database
   close(): void                                  // also [Symbol.dispose] when available
   readonly changes: number                       // rows affected by the most recent INSERT/UPDATE/DELETE
   readonly seed: number | bigint

package/dist/api/database.d.ts

@@ -2,6 +2,11 @@ import { type DatabaseOptions, type Int8Mode, type RandomMode } from "../runtime
 import type { BindValue, JsValue, QueryRow } from "./bind.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 PostgreSQL database.
  *
@@ -44,7 +49,7 @@ export declare class Database {
      */
     registerFunction(spec: RegisterFunctionOptions): void;
     /** Execute a single-statement query and return all rows keyed by column name. */
-    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}. */
     prepare(sql: string): Statement;
     /**
@@ -58,6 +63,10 @@ export declare class Database {
      * {@link Snapshot.open} for a copy-on-write fork.
      */
     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. Idempotent. */
     close(): void;
     /**

package/dist/index.d.ts

@@ -23,6 +23,6 @@
  */
 import "./serialization/codec.js";
 export type { BindValue, JsValue, QueryRow } from "./api/bind.js";
-export { Database, type DatabaseOptions, type RegisterFunctionOptions, Snapshot } from "./api/database.js";
+export { Database, type DatabaseOptions, type QueryOptions, type RegisterFunctionOptions, Snapshot, } from "./api/database.js";
 export { type ResultSet, type RunResult, Statement } from "./api/statement.js";
 export { type ErrorCategory, PostgresError } from "./errors/error.js";

package/dist/index.js

@@ -22214,8 +22214,9 @@ var Database = class {
     schema.functions.set(name, existing);
   }
   /** Execute a single-statement query and return all rows keyed by column name. */
-  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);
   }
   /** Compile a single SQL statement into a reusable {@link Statement}. */
@@ -22277,6 +22278,15 @@ var Database = class {
       this.int8Mode
     );
   }
+  /** 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. Idempotent. */
   close() {
     if (this.closed) return;