@crvouga/mockingbird-service-postgres 1.4.0 → 1.5.0

package/dist/api/database.d.ts

@@ -2,10 +2,27 @@ 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";
+/** A timeline checkpoint without its retained snapshot value. */
+export interface HistoryCheckpoint {
+    id: string;
+    branch: string;
+    parent: string | null;
+    at: number;
+}
+/** Branch heads and checkpoints owned by the shared Timeline. */
+export interface DatabaseHistory {
+    readonly size: number;
+    head(branch?: string): HistoryCheckpoint | undefined;
+    branches(): Readonly<Record<string, string>>;
+    checkpoints(): readonly HistoryCheckpoint[];
+}
 /** Additive time-travel controls for read APIs. */
 export interface QueryOptions {
-    /** Execute against this immutable checkpoint instead of the live database. */
-    at?: Snapshot;
+    /**
+     * Execute against this immutable snapshot, or a timeline checkpoint id,
+     * instead of the live database.
+     */
+    at?: Snapshot | string;
 }
 /**
  * Pure TypeScript in-memory PostgreSQL database.
@@ -35,6 +52,8 @@ export declare class Database {
     private closed;
     private transactionSequence;
     private apiTransactionDepth;
+    private historyBranch;
+    private originId;
     constructor(options?: DatabaseOptions);
     /**
      * Execute SQL for its side effects. Multiple semicolon-separated statements
@@ -65,6 +84,19 @@ export declare class Database {
     snapshot(): Snapshot;
     /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
     checkpoint(): Snapshot;
+    /**
+     * Commit the live state onto `branch` (default: the branch this database follows).
+     * Does not switch the live database. Illegal inside a transaction.
+     */
+    record(branch?: string): HistoryCheckpoint;
+    /** Point `name` at a checkpoint without copying rows or switching the live database. */
+    fork(name: string, at?: string): HistoryCheckpoint;
+    /** Move `branch` to `id` and install that checkpoint as the live database. */
+    checkout(id: string, branch?: string): HistoryCheckpoint;
+    /** Return the live database to the origin checkpoint on `main`. */
+    reset(): HistoryCheckpoint;
+    /** Checkpoint ids and branch heads. Values stay inside the timeline. */
+    get history(): DatabaseHistory;
     /** 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. */
@@ -82,6 +114,9 @@ export declare class Database {
     copyFrom(sql: string, data: string): number;
     /** Rows affected by the most recent INSERT / UPDATE / DELETE. */
     get changes(): number;
+    private historyError;
+    private captureLive;
+    private install;
     private prepareSingle;
 }
 export { Snapshot } from "./snapshot.js";

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 QueryOptions, type RegisterFunctionOptions, Snapshot, } from "./api/database.js";
+export { Database, type DatabaseHistory, type DatabaseOptions, type HistoryCheckpoint, 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

@@ -1,3 +1,164 @@
+// ../../core/dist/timeline.js
+var BRANCH_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var Timeline = class {
+  maxCheckpoints;
+  now;
+  makeId;
+  nodes = /* @__PURE__ */ new Map();
+  heads = /* @__PURE__ */ new Map();
+  /** Unreferenced nodes in the exact order they became collectible. */
+  evictable = /* @__PURE__ */ new Set();
+  /** Branch heads plus explicit retainers. Absent means zero. */
+  references = /* @__PURE__ */ new Map();
+  explicitPins = /* @__PURE__ */ new Map();
+  sequence = 0;
+  constructor(options = {}) {
+    const max = options.maxCheckpoints ?? 1e3;
+    if (!Number.isSafeInteger(max) || max < 1)
+      throw new RangeError("maxCheckpoints must be a positive integer");
+    this.maxCheckpoints = max;
+    this.now = options.now ?? (() => this.sequence);
+    this.makeId = options.id ?? ((sequence) => `cp_${sequence.toString(36).padStart(8, "0")}`);
+  }
+  /** Capture a new immutable value and move `branch` to it. */
+  commit(value, options = {}) {
+    const branch = options.branch ?? "main";
+    this.assertBranch(branch);
+    const parent = options.parent === void 0 ? this.heads.get(branch) ?? null : options.parent;
+    if (parent !== null && !this.nodes.has(parent))
+      throw new RangeError(`no checkpoint ${parent}`);
+    const id = this.makeId(++this.sequence);
+    if (this.nodes.has(id))
+      throw new RangeError(`duplicate checkpoint id ${id}`);
+    const checkpoint = Object.freeze({ id, branch, parent, at: this.now(), value });
+    this.nodes.set(id, checkpoint);
+    this.moveHead(branch, id);
+    this.collect(this.maxCheckpoints);
+    return checkpoint;
+  }
+  /** Create a branch pointer without copying its checkpoint value. */
+  fork(branch, options = {}) {
+    this.assertBranch(branch);
+    if (this.heads.has(branch))
+      throw new RangeError(`branch already exists: ${branch}`);
+    const from = options.from ?? this.heads.get("main");
+    if (from === void 0)
+      return void 0;
+    const checkpoint = this.get(from);
+    this.moveHead(branch, checkpoint.id);
+    return checkpoint;
+  }
+  /** Move a branch pointer to an existing checkpoint. */
+  checkout(branch, id) {
+    this.assertBranch(branch);
+    const checkpoint = this.get(id);
+    this.moveHead(branch, checkpoint.id);
+    return checkpoint;
+  }
+  get(id) {
+    const checkpoint = this.nodes.get(id);
+    if (!checkpoint)
+      throw new RangeError(`no checkpoint ${id}`);
+    return checkpoint;
+  }
+  head(branch = "main") {
+    const id = this.heads.get(branch);
+    return id === void 0 ? void 0 : this.get(id);
+  }
+  hasBranch(branch) {
+    return this.heads.has(branch);
+  }
+  branches() {
+    return Object.freeze(Object.fromEntries([...this.heads].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+  }
+  checkpoints() {
+    return [...this.nodes.values()];
+  }
+  /** Number of retained checkpoints without allocating an array. */
+  get size() {
+    return this.nodes.size;
+  }
+  /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+  retain(id) {
+    const checkpoint = this.get(id);
+    this.explicitPins.set(id, (this.explicitPins.get(id) ?? 0) + 1);
+    this.addReference(id);
+    return checkpoint;
+  }
+  /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+  release(id) {
+    if (!this.nodes.has(id))
+      return false;
+    const pins = this.explicitPins.get(id) ?? 0;
+    if (pins === 0)
+      return false;
+    if (pins === 1)
+      this.explicitPins.delete(id);
+    else
+      this.explicitPins.set(id, pins - 1);
+    this.removeReference(id);
+    this.collect(this.maxCheckpoints);
+    return true;
+  }
+  deleteBranch(branch) {
+    if (branch === "main")
+      throw new RangeError("cannot delete main branch");
+    const previous = this.heads.get(branch);
+    const deleted = this.heads.delete(branch);
+    if (previous !== void 0)
+      this.removeReference(previous);
+    this.collect(this.maxCheckpoints);
+    return deleted;
+  }
+  /**
+   * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+   * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+   * storage dependency, so a retained node remains usable after pruning.
+   */
+  gc(max = this.maxCheckpoints) {
+    if (!Number.isSafeInteger(max) || max < 1)
+      throw new RangeError("max must be a positive integer");
+    const removed = [];
+    this.collect(max, removed);
+    return removed;
+  }
+  collect(max, removed) {
+    while (this.nodes.size > max && this.evictable.size > 0) {
+      const id = this.evictable.values().next().value;
+      this.evictable.delete(id);
+      this.nodes.delete(id);
+      removed?.push(id);
+    }
+  }
+  moveHead(branch, id) {
+    const previous = this.heads.get(branch);
+    if (previous === id)
+      return;
+    if (previous !== void 0)
+      this.removeReference(previous);
+    this.heads.set(branch, id);
+    this.addReference(id);
+  }
+  addReference(id) {
+    this.references.set(id, (this.references.get(id) ?? 0) + 1);
+    this.evictable.delete(id);
+  }
+  removeReference(id) {
+    const next = (this.references.get(id) ?? 0) - 1;
+    if (next > 0)
+      this.references.set(id, next);
+    else {
+      this.references.delete(id);
+      if (this.nodes.has(id))
+        this.evictable.add(id);
+    }
+  }
+  assertBranch(branch) {
+    if (!BRANCH_PATTERN.test(branch))
+      throw new RangeError(`branch must match ${BRANCH_PATTERN}`);
+  }
+};
+
 // src/errors/error.ts
 var CATEGORY_TO_SQLSTATE = {
   syntax: "42601",
@@ -23111,6 +23272,9 @@ var ADOPT = /* @__PURE__ */ Symbol("postgres-mem.adopt");
 function isAdopted(value) {
   return ADOPT in value;
 }
+function project(point) {
+  return { id: point.id, branch: point.branch, parent: point.parent, at: point.at };
+}
 var Database = class {
   /** @internal Engine catalog, tables, session settings. */
   state;
@@ -23131,6 +23295,10 @@ var Database = class {
   closed = false;
   transactionSequence = 0;
   apiTransactionDepth = 0;
+  /** @internal Shared checkpoint DAG. Omitted from published declarations. */
+  timeline;
+  historyBranch = "main";
+  originId = "";
   constructor(options = {}) {
     if (isAdopted(options)) {
       this.seed = options.seed;
@@ -23143,16 +23311,23 @@ var Database = class {
       this.state.prng = this.prng;
       this.state.clock = () => this.now();
       this.transactions = txManagerFor(this.state);
-      return;
+    } else {
+      this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
+      this.randomMode = options.random ?? "deterministic";
+      this.systemClock = options.now === "system";
+      this.int8Mode = options.int8 ?? "bigint";
+      this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
+      this.now = resolveClock(options.now);
+      this.state = new DatabaseState(this.prng, () => this.now());
+      this.transactions = txManagerFor(this.state);
     }
-    this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
-    this.randomMode = options.random ?? "deterministic";
-    this.systemClock = options.now === "system";
-    this.int8Mode = options.int8 ?? "bigint";
-    this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
-    this.now = resolveClock(options.now);
-    this.state = new DatabaseState(this.prng, () => this.now());
-    this.transactions = txManagerFor(this.state);
+    this.timeline = new Timeline({
+      now: () => this.now().getTime(),
+      ...options.maxCheckpoints !== void 0 ? { maxCheckpoints: options.maxCheckpoints } : {}
+    });
+    const origin = this.timeline.commit(this.captureLive());
+    this.originId = origin.id;
+    this.timeline.retain(origin.id);
   }
   /**
    * Execute SQL for its side effects. Multiple semicolon-separated statements
@@ -23207,7 +23382,15 @@ var Database = class {
   /** Execute a single-statement query and return all rows keyed by column name. */
   query(sql, params = [], options = {}) {
     this.assertOpen();
-    if (options.at) return options.at.open().query(sql, params);
+    const at = options.at;
+    if (typeof at === "string") {
+      try {
+        return this.timeline.get(at).value.open().query(sql, params);
+      } catch (error) {
+        this.historyError(error);
+      }
+    }
+    if (at) return at.open().query(sql, params);
     return this.prepareSingle(sql).all(...params);
   }
   /** Compile a single SQL statement into a reusable {@link Statement}. */
@@ -23255,23 +23438,77 @@ var Database = class {
    * {@link Snapshot.open} for a copy-on-write fork.
    */
   snapshot() {
+    const point = this.record(this.historyBranch);
+    return this.timeline.get(point.id).value;
+  }
+  /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
+  checkpoint() {
+    return this.snapshot();
+  }
+  /**
+   * Commit the live state onto `branch` (default: the branch this database follows).
+   * Does not switch the live database. Illegal inside a transaction.
+   */
+  record(branch = this.historyBranch) {
     this.assertOpen();
     if (this.transactions.inTransaction) {
       throw pgError("transaction_state", "cannot snapshot during a transaction", "25P01");
     }
-    return captureSnapshot(
-      this.state,
-      this.prng,
-      this.now,
-      this.seed,
-      this.randomMode,
-      this.systemClock,
-      this.int8Mode
-    );
+    try {
+      return project(this.timeline.commit(this.captureLive(), { branch }));
+    } catch (error) {
+      this.historyError(error);
+    }
   }
-  /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
-  checkpoint() {
-    return this.snapshot();
+  /** Point `name` at a checkpoint without copying rows or switching the live database. */
+  fork(name, at) {
+    this.assertOpen();
+    try {
+      const point = this.timeline.fork(name, at !== void 0 ? { from: at } : {});
+      if (!point) throw pgError("misuse", "no checkpoint to fork from", "XX000");
+      return project(point);
+    } catch (error) {
+      if (error instanceof PostgresError) throw error;
+      this.historyError(error);
+    }
+  }
+  /** Move `branch` to `id` and install that checkpoint as the live database. */
+  checkout(id, branch = this.historyBranch) {
+    this.assertOpen();
+    if (this.transactions.inTransaction) {
+      throw pgError("transaction_state", "cannot checkout during a transaction", "25P01");
+    }
+    try {
+      const point = this.timeline.checkout(branch, id);
+      this.historyBranch = branch;
+      this.install(point.value);
+      return project(point);
+    } catch (error) {
+      this.historyError(error);
+    }
+  }
+  /** Return the live database to the origin checkpoint on `main`. */
+  reset() {
+    return this.checkout(this.originId, "main");
+  }
+  /** Checkpoint ids and branch heads. Values stay inside the timeline. */
+  get history() {
+    const timeline = this.timeline;
+    return {
+      get size() {
+        return timeline.size;
+      },
+      head(branch) {
+        const point = timeline.head(branch);
+        return point ? project(point) : void 0;
+      },
+      branches() {
+        return timeline.branches();
+      },
+      checkpoints() {
+        return timeline.checkpoints().map(project);
+      }
+    };
   }
   /** Open a copy-on-write branch from `at`, or from the current state when omitted. */
   branch(at = this.snapshot()) {
@@ -23316,6 +23553,26 @@ var Database = class {
   assertOpen() {
     if (this.closed) throw pgError("misuse", "Database is closed", "XX000");
   }
+  historyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw pgError("misuse", message, "XX000");
+  }
+  captureLive() {
+    return captureSnapshot(
+      this.state,
+      this.prng,
+      this.now,
+      this.seed,
+      this.randomMode,
+      this.systemClock,
+      this.int8Mode
+    );
+  }
+  install(snapshot) {
+    this.state.restoreFrom(snapshot.state.cloneShallow());
+    this.prng.setState(snapshot.prngState);
+    if (!this.systemClock) this.now = fixedClock(new Date(snapshot.nowMs));
+  }
   prepareSingle(sql) {
     const statements = parse(sql);
     if (statements.length === 0) {