@crvouga/mockingbird-service-sqlite 1.2.0 → 1.3.0

package/dist/api/database.d.ts

@@ -2,10 +2,27 @@ 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";
+/** 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 SQLite database.
@@ -34,6 +51,8 @@ export declare class Database {
     private transactionSequence;
     /** Depth of active {@link transaction} callbacks (not SQL BEGIN). */
     private apiTransactionDepth;
+    private historyBranch;
+    private originId;
     /**
      * Create an empty in-memory database.
      *
@@ -88,6 +107,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;
     /**
@@ -115,6 +147,9 @@ export declare class Database {
      * @throws {SqliteError} If the database is closed.
      */
     get totalChanges(): number;
+    private historyError;
+    private captureLive;
+    private install;
     private prepareSingle;
 }
 export { Snapshot } from "./snapshot.js";

package/dist/index.d.ts

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

@@ -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/index.ts
 var SqliteError = class extends Error {
   /** Coarse error class (constraint vs syntax vs missing object, …). */
@@ -15800,6 +15961,10 @@ var Database = class {
   transactionSequence = 0;
   /** Depth of active {@link transaction} callbacks (not SQL BEGIN). */
   apiTransactionDepth = 0;
+  /** @internal Shared checkpoint DAG. Omitted from published declarations. */
+  timeline;
+  historyBranch = "main";
+  originId = "";
   /**
    * Create an empty in-memory database.
    *
@@ -15814,15 +15979,22 @@ var Database = class {
       this.now = options.now;
       this.state = options.state;
       this.transactions = new TransactionManager(this.state, this.prng);
-      return;
+    } else {
+      this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
+      this.randomMode = options.random ?? "deterministic";
+      this.systemClock = options.now === "system";
+      this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
+      this.now = resolveClock(options.now);
+      this.state = new DatabaseState();
+      this.transactions = new TransactionManager(this.state, this.prng);
     }
-    this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
-    this.randomMode = options.random ?? "deterministic";
-    this.systemClock = options.now === "system";
-    this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
-    this.now = resolveClock(options.now);
-    this.state = new DatabaseState();
-    this.transactions = new TransactionManager(this.state, this.prng);
+    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 (DDL/DML). Multiple statements are allowed.
@@ -15850,7 +16022,15 @@ var Database = class {
    */
   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);
   }
   /**
@@ -15912,15 +16092,77 @@ var Database = class {
    * @throws {SqliteError} If the database is closed or a transaction is open.
    */
   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 new SqliteError("cannot snapshot during a transaction", "transaction");
     }
-    return captureSnapshot(this.state, this.prng, this.now, this.seed, this.randomMode, this.systemClock);
+    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 new SqliteError("no checkpoint to fork from", "misuse");
+      return project(point);
+    } catch (error) {
+      if (error instanceof SqliteError) 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 new SqliteError("cannot checkout during a transaction", "transaction");
+    }
+    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()) {
@@ -15976,6 +16218,18 @@ var Database = class {
   assertOpen() {
     if (this.closed) throw new SqliteError("Database is closed", "misuse");
   }
+  historyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SqliteError(message, "misuse");
+  }
+  captureLive() {
+    return captureSnapshot(this.state, this.prng, this.now, this.seed, this.randomMode, this.systemClock);
+  }
+  install(snapshot) {
+    this.state.replaceWith(snapshot.state.cloneShallow(), { adopt: true });
+    this.prng.setState(snapshot.prngState);
+    if (!this.systemClock) this.now = fixedClock(new Date(snapshot.nowMs));
+  }
   prepareSingle(sql) {
     const units = parseUnits(sql);
     if (units.length === 0) {
@@ -16005,6 +16259,9 @@ if (typeof disposeKey === "symbol") {
 function isAdopted(value) {
   return ADOPT in value;
 }
+function project(point) {
+  return { id: point.id, branch: point.branch, parent: point.parent, at: point.at };
+}
 function createAdoptedDatabase(opts) {
   return new Database({
     [ADOPT]: true,