@lunora/replica 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/packem_shared/{local-mirror.d-BUeOe5KC.d.mts → local-mirror.d-DL1XJBB3.d.mts}

@@ -28,16 +28,29 @@ type RowChange = {
 interface TableDiff {
   /** Ordered row changes — insert/update/delete, earliest first. */
   readonly changes: ReadonlyArray<RowChange>;
+  /**
+  * Optional stable identity for this diff, distinct from `timestamp`
+  * (multiple diffs can legitimately share a millisecond, so `timestamp`
+  * alone is not a unique diff identity). Used by `deriveInsertId` in
+  * `apply-diff.ts` to derive deterministic row ids for id-less inserts:
+  * replaying the SAME diff (same `id`) must always mint the SAME id,
+  * while two DIFFERENT diffs emitted in the same millisecond must not
+  * alias onto the same one. `createTableDiff` auto-generates one when
+  * omitted; diffs built as plain object literals (bypassing the helper)
+  * simply fall back to `timestamp` for that derivation.
+  */
+  readonly id?: string;
   /** Logical table name (matches the schema table name). */
   readonly table: string;
   /** Monotonic server timestamp (ms since epoch) when this diff was emitted. */
   readonly timestamp: number;
 }
 /**
-* Create a {@link TableDiff} with a snapshot of the current time.
+* Create a {@link TableDiff} with a snapshot of the current time and a
+* fresh stable `id` (unless one is explicitly provided).
 * @experimental
 */
-declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => TableDiff;
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number, id?: string) => TableDiff;
 /**
 * Return `true` when the diff contains no row changes.
 * @experimental
@@ -212,6 +225,37 @@ interface AppendOptions {
   readonly parentSeqNum?: Seq;
   /** Session identifier within the client. */
   readonly sessionId?: string;
+  /**
+  * Override the entry's `timestamp` instead of stamping `Date.now()` at
+  * append time.
+  *
+  * Used by callers (e.g. {@link import("./event-source").EventSource | EventSource})
+  * that must commit the EXACT entry a reducer already observed — a
+  * second, independently-drawn `Date.now()` at append time could produce
+  * a persisted entry a timestamp-dependent reducer cannot reproduce on
+  * replay.
+  */
+  readonly timestamp?: number;
+}
+/**
+* Options for constructing an {@link EventLog}.
+* @experimental
+*/
+interface EventLogOptions {
+  /**
+  * Cap the number of entries retained in memory (REPLICA-06). When an
+  * append would exceed the cap, the OLDEST entries are evicted (ring
+  * buffer) — a `getSince`/`getFrom` call for a watermark below the oldest
+  * retained `seq` then returns only what's left, silently missing
+  * anything evicted.
+  *
+  * `undefined` (the default) preserves the original unbounded behavior.
+  * Set this only when you have another durable source of truth for
+  * anything older than the cap (a snapshot, a server-side `EventLogDO`) —
+  * see {@link EventLog#truncateBelow} for the caller-driven equivalent
+  * tied to snapshot persistence.
+  */
+  readonly maxEntries?: number;
 }
 /**
 * An append-only, in-memory event log for local event sourcing.
@@ -226,6 +270,7 @@ interface AppendOptions {
 */
 declare class EventLog {
   #private;
+  constructor(options?: EventLogOptions);
   /**
   * Append a new entry to the log.
   *
@@ -254,6 +299,10 @@ declare class EventLog {
   * This is the restore counterpart of {@link EventLog#snapshot}.
   * Restores `headSeq` from the snapshot so auto-parenting continues
   * after restore.
+  *
+  * Runs `#enforceCap()` after restoring so a snapshot captured under a
+  * different (or no) `maxEntries` can never leave this log over its
+  * configured capacity.
   */
   load(snapshot: EventLogSnapshot): void;
   /**
@@ -289,6 +338,24 @@ declare class EventLog {
   /** Remove all entries (primarily for testing). */
   clear(): void;
   /**
+  * Discard all entries with `seq < floorSeq` (REPLICA-06).
+  *
+  * `headSeq`/`nextSeq` are untouched (they're independent counters), so
+  * appends after a truncation continue the same sequence uninterrupted.
+  *
+  * **Caller-driven, not automatic**: only call this after the truncated
+  * range has already been durably captured elsewhere (a snapshot, a
+  * server-side `EventLogDO`) — truncating without such a floor makes any
+  * future `getSince`/`getFrom`/`EventSource.replayFromLog` call for a
+  * watermark below `floorSeq` silently miss the discarded entries. This is
+  * the hook the caller ties to snapshot persistence; the log itself has no
+  * concept of "already durably persisted".
+  *
+  * `floorSeq` must be a non-negative safe integer — `NaN` would make
+  * every comparison false and silently clear the entire log.
+  */
+  truncateBelow(floorSeq: number): void;
+  /**
   * Return an async generator that yields every entry starting from
   * `fromSeq` (default `0` = all entries).
   *
@@ -314,6 +381,18 @@ interface LocalMirrorOptions {
   /** Platform-specific SQLite adapter. */
   readonly db: SqliteAdapter;
   /**
+  * Cap the mirror's internal {@link EventLog} to this many entries
+  * (REPLICA-06). Every applied diff is recorded in the log — with no cap,
+  * a long-running client accumulates one entry per diff forever.
+  *
+  * `undefined` (the default) preserves unbounded retention. Set this when
+  * catch-up replication only ever needs a bounded recent window; older
+  * entries are silently evicted (oldest-first) once the cap is exceeded.
+  * See {@link EventLog#truncateBelow} for caller-driven truncation tied to
+  * a snapshot instead.
+  */
+  readonly maxEventLogEntries?: number;
+  /**
   * Table schemas the mirror should manage.
   *
   * On first use the mirror creates any missing tables automatically
@@ -399,6 +478,13 @@ declare class LocalMirror {
   */
   get db(): SqliteAdapter;
   /**
+  * Monotonically increasing version counter, bumped on every operation
+  * that changes mirrored data (`applyDiff`, `clearData`). Use this — not
+  * `eventLog.size` — as a `useSyncExternalStore` snapshot so operations
+  * that don't append to the log still trigger a re-render.
+  */
+  get version(): number;
+  /**
   * Apply a server-side diff to the local SQLite mirror.
   *
   * The diff is applied in a transaction and recorded in the event log
@@ -420,6 +506,11 @@ declare class LocalMirror {
   /**
   * Delete every row from all known tables (preserves the event log
   * and schema). Useful when re-syncing from scratch.
+  *
+  * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
+  * (REPLICA-09) even though nothing is appended to the event log — a
+  * consumer keyed only on `eventLog.size` would otherwise never learn the
+  * mirror was cleared and keep rendering deleted rows.
   */
   clearData(): void;
   /**
@@ -436,4 +527,4 @@ declare class LocalMirror {
   */
   get mirroredTables(): ReadonlyArray<string>;
 }
-export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogSnapshot as b, LocalMirrorOptions as c, classifyChanges as d, createTableDiff as e, diffSize as f, isDiffEmpty as g, isGlobalSeq as h, isClientSeq as i, isInputEvent as j, mergeDiffs as m };
+export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogOptions as b, EventLogSnapshot as c, LocalMirrorOptions as d, classifyChanges as e, createTableDiff as f, diffSize as g, isDiffEmpty as h, isClientSeq as i, isGlobalSeq as j, isInputEvent as k, mergeDiffs as m };

package/dist/react.d.mts

@@ -1,4 +1,4 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-BUeOe5KC.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-DL1XJBB3.mjs";
 import "./packem_shared/types.d-BuAWjEY5.mjs";
 /**
 * Options for the {@link useLocalQuery} hook.

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-Cd8tAg-W.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-ByIjd7sW.js";
 import "./packem_shared/types.d-BuAWjEY5.js";
 /**
 * Options for the {@link useLocalQuery} hook.

package/dist/react.mjs

@@ -2,8 +2,8 @@ import { useSyncExternalStore } from 'react';
 
 const useLocalQuery = (mirror, sql, params, _options) => {
   const subscribe = (onStoreChange) => mirror.onChange(onStoreChange);
-  const getSnapshot = () => mirror.eventLog.size;
-  const getServerSnapshot = () => mirror.eventLog.size;
+  const getSnapshot = () => mirror.version;
+  const getServerSnapshot = () => mirror.version;
   useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
   try {
     return mirror.query(sql, params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/EventLog-zMy7AYP4.mjs

@@ -1,162 +0,0 @@
-class EventLog {
-  #entries = [];
-  #nextSeq = 0;
-  // eslint-disable-next-line unicorn/no-null -- public contract uses `null` for an empty log head
-  #headSeq = null;
-  append(typeOrEvent, payload, tableDiffs, options) {
-    const type = typeof typeOrEvent === "string" ? typeOrEvent : typeOrEvent.type;
-    const pl = typeof typeOrEvent === "string" ? payload : typeOrEvent.payload;
-    let diffs;
-    let resolvedOptions;
-    if (typeof typeOrEvent === "string") {
-      diffs = tableDiffs;
-      resolvedOptions = options;
-    } else {
-      diffs = void 0;
-      resolvedOptions = payload;
-    }
-    const parentSeqNumber = resolvedOptions?.parentSeqNum ?? this.#headSeq ?? void 0;
-    const seq = this.#nextSeq;
-    this.#nextSeq += 1;
-    const entry = {
-      seq,
-      type,
-      payload: pl,
-      timestamp: Date.now(),
-      tableDiffs: diffs,
-      clientId: resolvedOptions?.clientId,
-      sessionId: resolvedOptions?.sessionId,
-      parentSeqNum: parentSeqNumber
-    };
-    this.#entries.push(entry);
-    this.#headSeq = entry.seq;
-    return entry;
-  }
-  /**
-   * Atomically append multiple events to the log.
-   *
-   * All events are assigned sequential global sequence numbers and
-   * automatically wired as a causal chain (each event's `parentSeqNum`
-   * points to the previous event in the batch, or to the log head for
-   * the first event).
-   * @param events An array of events to commit atomically.
-   * @returns The newly created entries in order.
-   */
-  commitAll(events) {
-    if (events.length === 0) {
-      return [];
-    }
-    const entries = [];
-    for (const event of events) {
-      const { type } = event;
-      const payload = "payload" in event ? event.payload : void 0;
-      const ts = "timestamp" in event ? event.timestamp : Date.now();
-      const parentSeqNumber = entries.at(-1)?.seq ?? this.#headSeq ?? void 0;
-      const seq = this.#nextSeq;
-      this.#nextSeq += 1;
-      const entry = {
-        seq,
-        type,
-        payload,
-        timestamp: ts,
-        parentSeqNum: parentSeqNumber
-      };
-      this.#entries.push(entry);
-      entries.push(entry);
-    }
-    this.#headSeq = entries.at(-1)?.seq ?? this.#headSeq;
-    return entries;
-  }
-  /**
-   * Replace the log contents with a previously captured snapshot.
-   * This is the restore counterpart of {@link EventLog#snapshot}.
-   * Restores `headSeq` from the snapshot so auto-parenting continues
-   * after restore.
-   */
-  load(snapshot) {
-    this.#entries = [...snapshot.entries];
-    this.#nextSeq = snapshot.nextSeq;
-    this.#headSeq = snapshot.headSeq;
-  }
-  // ── Queries ───────────────────────────────────────────────────────
-  /**
-   * Return **all** entries whose `seq >= sinceSeq`.
-   * Useful for catch-up: "give me everything since my last watermark".
-   */
-  getSince(sinceSeq) {
-    if (sinceSeq <= 0) {
-      return [...this.#entries];
-    }
-    const first = this.#entries.findIndex((entry) => entry.seq >= sinceSeq);
-    return first === -1 ? [] : this.#entries.slice(first);
-  }
-  /**
-   * Paginated read starting at `fromSeq`.
-   * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
-   * entries exist beyond the requested page.
-   */
-  getFrom(fromSeq, limit = 50) {
-    const first = this.#entries.findIndex((entry) => entry.seq >= fromSeq);
-    if (first === -1) {
-      return { entries: [], hasMore: false };
-    }
-    const slice = this.#entries.slice(first, first + limit);
-    return {
-      entries: slice,
-      hasMore: first + limit < this.#entries.length
-    };
-  }
-  /**
-   * Return all entries as a snapshot suitable for serialisation.
-   */
-  snapshot() {
-    return {
-      entries: [...this.#entries],
-      nextSeq: this.#nextSeq,
-      headSeq: this.#headSeq
-    };
-  }
-  /** Number of entries currently in the log. */
-  get size() {
-    return this.#entries.length;
-  }
-  /** The next sequence number that will be assigned. */
-  get nextSeq() {
-    return this.#nextSeq;
-  }
-  /** Return `true` when there are no entries. */
-  get isEmpty() {
-    return this.#entries.length === 0;
-  }
-  /**
-   * The sequence number of the last (most recent) entry, or `null`
-   * when the log is empty. Used internally for auto-parenting and
-   * exposed for consumers that need the causal head.
-   */
-  get headSeq() {
-    return this.#headSeq;
-  }
-  /** Remove all entries (primarily for testing). */
-  clear() {
-    this.#entries = [];
-    this.#nextSeq = 0;
-    this.#headSeq = null;
-  }
-  /**
-   * Return an async generator that yields every entry starting from
-   * `fromSeq` (default `0` = all entries).
-   *
-   * Because `EventLog` is purely in-memory, the generator yields all
-   * matching entries synchronously on first iteration and then completes.
-   * For a streaming / push-based variant see {@link EventSource.events}.
-   */
-  // eslint-disable-next-line @typescript-eslint/require-await -- kept async so callers can uniformly `for await` over any event stream
-  async *events(fromSeq = 0) {
-    const entries = this.getSince(fromSeq);
-    for (const entry of entries) {
-      yield entry;
-    }
-  }
-}
-
-export { EventLog };

package/dist/packem_shared/applyDiff-BtbIl1D3.mjs

@@ -1,40 +0,0 @@
-const applyDiff = (current, diff) => {
-  const next = new Map(current);
-  for (const change of diff.changes) {
-    switch (change.type) {
-      case "delete": {
-        next.delete(change.id);
-        break;
-      }
-      case "insert": {
-        const rawId = change.data.id;
-        const id = typeof rawId === "string" || typeof rawId === "number" ? String(rawId) : crypto.randomUUID();
-        next.set(id, { ...change.data, id });
-        break;
-      }
-      case "update": {
-        const existing = next.get(change.id);
-        if (existing) {
-          next.set(change.id, { ...existing, ...change.data });
-        }
-        break;
-      }
-    }
-  }
-  return next;
-};
-const applyDiffs = (current, diffs) => {
-  let result = new Map(current);
-  for (const diff of diffs) {
-    result = applyDiff(result, diff);
-  }
-  return result;
-};
-const applyDiffToSnapshot = (snapshot, diff) => {
-  const next = new Map(snapshot);
-  const tableMap = next.get(diff.table) ?? /* @__PURE__ */ new Map();
-  next.set(diff.table, applyDiff(tableMap, diff));
-  return next;
-};
-
-export { applyDiff, applyDiffToSnapshot, applyDiffs };