@lunora/replica 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/EventSource-DfV4VoRD.mjs

@@ -0,0 +1,195 @@
+import { EventEmitter } from './EventEmitter-CMZfct03.mjs';
+import { EventLog } from './EventLog-zMy7AYP4.mjs';
+
+class EventSource {
+  // eslint-disable-next-line unicorn/prefer-event-target -- EventEmitter is the library's typed public API
+  emitter = new EventEmitter();
+  log = new EventLog();
+  #state;
+  #reducer;
+  #replayed = false;
+  #unknownEventHandling;
+  /**
+   * Watermark over the EXTERNAL source log: the highest source `seq` already
+   * applied by {@link EventSource.replayFromLog}, or `-1` when nothing has been applied.
+   * Tracked separately from `this.log.nextSeq` (the destination log, which
+   * `applyEvent` and each replay append advance independently) so a repeated
+   * `replayFromLog` neither skips unseen source entries nor reprocesses
+   * already-applied ones.
+   */
+  #lastAppliedSeq = -1;
+  constructor(initialState, reducer, options) {
+    this.#state = { ...initialState };
+    this.#reducer = reducer;
+    this.#unknownEventHandling = options?.unknownEventHandling ?? "warn";
+  }
+  // ── Public API ────────────────────────────────────────────────────
+  /**
+   * The current derived state. Read-only snapshot; mutate through events.
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * Whether the initial replay from an existing log has completed.
+   */
+  get replayed() {
+    return this.#replayed;
+  }
+  applyEvent(typeOrEvent, payload, options) {
+    let type;
+    let pl;
+    let resolvedOptions;
+    if (typeof typeOrEvent === "string") {
+      type = typeOrEvent;
+      pl = payload;
+      resolvedOptions = options;
+    } else {
+      type = typeOrEvent.type;
+      pl = typeOrEvent.payload;
+      resolvedOptions = payload;
+    }
+    const entry = this.log.append(type, pl, void 0, resolvedOptions);
+    this.#applyEntry(entry);
+    return entry;
+  }
+  /**
+   * Replay all entries from an existing {@link EventLog} to bootstrap
+   * the current state.
+   *
+   * Idempotent across calls: only source entries past the `#lastAppliedSeq`
+   * watermark are applied, so re-invoking picks up just the new entries.
+   * @param log The external log to replay from.
+   */
+  replayFromLog(log) {
+    const entries = log.getSince(this.#lastAppliedSeq + 1);
+    for (const entry of entries) {
+      try {
+        this.#state = this.#reducer(this.#state, entry);
+        this.log.append(entry.type, entry.payload, entry.tableDiffs, {
+          clientId: entry.clientId,
+          sessionId: entry.sessionId,
+          parentSeqNum: entry.parentSeqNum
+        });
+      } catch (error) {
+        this.emitter.emit("replay-error", {
+          entry,
+          error: error instanceof Error ? error : new Error(String(error))
+        });
+      } finally {
+        this.#lastAppliedSeq = entry.seq;
+      }
+    }
+    this.#replayed = true;
+    this.emitter.emit("ready", { entryCount: this.log.size });
+  }
+  /**
+   * Reset the runtime to a base state, optionally resuming from a watermark.
+   *
+   * Useful after loading a snapshot from the DO: pass the snapshot's state as
+   * `initialState` and its highest applied source `seq` as `resumeFromSeq`, so
+   * the next {@link replayFromLog} applies ONLY the events after the snapshot
+   * (`getSince(resumeFromSeq + 1)`) rather than replaying the whole log on top
+   * of the snapshot — which would double-apply non-idempotent reducers.
+   *
+   * Omit `resumeFromSeq` (default `-1`) for a full reset that replays from the
+   * beginning.
+   * @param initialState The base state to reset to (e.g. a loaded snapshot).
+   * @param resumeFromSeq Highest source `seq` already baked into `initialState`, or `-1` to replay all.
+   */
+  reset(initialState, resumeFromSeq = -1) {
+    this.#state = { ...initialState };
+    this.#lastAppliedSeq = resumeFromSeq;
+    this.#replayed = resumeFromSeq >= 0;
+  }
+  /**
+   * Return an async generator that yields every event as it is applied,
+   * starting from the events currently in the log and continuing with
+   * every future `applyEvent` / `replayFromLog` call.
+   *
+   * The generator runs indefinitely — it never returns. Callers should
+   * break out of the `for await` loop or use an `AbortSignal` to stop.
+   * @example
+   * ```ts
+   * for await (const entry of source.events()) {
+   *   console.log("event applied:", entry);
+   * }
+   * ```
+   */
+  async *events(signal) {
+    const buffer = [];
+    let wake;
+    const unsub = this.emitter.on("state-changed", ({ entry }) => {
+      buffer.push(entry);
+      wake?.();
+    });
+    try {
+      let watermark = 0;
+      while (watermark < this.log.size) {
+        if (signal?.aborted) {
+          return;
+        }
+        for (const entry of this.log.getSince(watermark)) {
+          yield entry;
+        }
+        watermark = this.log.nextSeq;
+      }
+      while (!signal?.aborted) {
+        while (buffer.length > 0) {
+          const nextEntry = buffer.shift();
+          if (nextEntry) {
+            yield nextEntry;
+          }
+        }
+        if (buffer.length === 0) {
+          await new Promise((resolve) => {
+            wake = resolve;
+          });
+        }
+      }
+    } finally {
+      unsub();
+    }
+  }
+  // ── Internal ──────────────────────────────────────────────────────
+  #applyEntry(entry) {
+    const stateBefore = this.#state;
+    try {
+      this.#state = this.#reducer(this.#state, entry);
+    } catch (error) {
+      this.emitter.emit("replay-error", {
+        entry,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+      return;
+    }
+    if (this.#state === stateBefore && !this.#handleUnknown(entry)) {
+      return;
+    }
+    this.emitter.emit("state-changed", { state: this.#state, entry });
+  }
+  #handleUnknown(entry) {
+    const strategy = this.#unknownEventHandling;
+    if (typeof strategy === "function") {
+      return strategy(entry);
+    }
+    switch (strategy) {
+      case "ignore": {
+        return false;
+      }
+      case "fail": {
+        throw new Error(
+          `EventSource: unhandled event type "${entry.type}" (seq ${String(entry.seq)}). Configure \`unknownEventHandling\` to handle this event or change the strategy.`
+        );
+      }
+      default: {
+        console.warn(
+          `[EventSource] unhandled event type "${entry.type}" (seq ${String(entry.seq)}). The event was skipped. Configure \`unknownEventHandling\` if this is expected.`
+        );
+        return false;
+      }
+    }
+  }
+}
+
+export { EventSource };

package/dist/packem_shared/EventsSync-DkVbU0WV.mjs

@@ -0,0 +1,91 @@
+class EventsSync {
+  #options;
+  /** The highest `seq + 1` that has been applied. Starts at `0`. */
+  #watermark = 0;
+  #timer;
+  /** Guards against overlapping poll cycles (e.g. slow fetch). */
+  #running = false;
+  // ── Constructor ─────────────────────────────────────────────────────
+  constructor(options) {
+    this.#options = options;
+  }
+  // ── Public API ──────────────────────────────────────────────────────
+  /**
+   * The current watermark — the next `seq` the sync will fetch from.
+   *
+   * Starts at `0` (fetch everything). Advances to `max(seq) + 1` after
+   * each successful poll cycle.
+   */
+  get watermark() {
+    return this.#watermark;
+  }
+  /**
+   * Start polling for new events on the configured interval.
+   *
+   * Does nothing if polling is already active.
+   * Does **not** perform an initial sync — call {@link sync} once if you
+   * need to catch up immediately.
+   */
+  start() {
+    if (this.#timer !== void 0) {
+      return;
+    }
+    const ms = this.#options.pollInterval ?? 5e3;
+    this.#timer = setInterval(() => {
+      this.#poll().catch(() => void 0);
+    }, ms);
+  }
+  /**
+   * Stop polling for new events.
+   *
+   * Safe to call when not started.
+   */
+  stop() {
+    if (this.#timer !== void 0) {
+      clearInterval(this.#timer);
+      this.#timer = void 0;
+    }
+  }
+  /**
+   * Perform a one-shot sync: fetch events since the current watermark,
+   * apply them through the state machine, and push diffs to the mirror.
+   * @returns The number of events that were fetched and applied.
+   */
+  async sync() {
+    return this.#poll();
+  }
+  // ── Internal ────────────────────────────────────────────────────────
+  /**
+   * One poll cycle: fetch → apply → diff → mirror.
+   */
+  async #poll() {
+    if (this.#running) {
+      return 0;
+    }
+    this.#running = true;
+    try {
+      const events = await this.#options.fetchEventsSince(this.#watermark);
+      if (events.length === 0) {
+        return 0;
+      }
+      this.#options.applyEvents(events);
+      const lastEvent = events[events.length - 1];
+      if (lastEvent) {
+        this.#watermark = lastEvent.seq + 1;
+      }
+      const diffs = this.#options.getTableDiffs();
+      for (const diff of diffs) {
+        this.#options.mirror.applyDiff(diff);
+      }
+      return events.length;
+    } catch (error) {
+      const onError = this.#options.onError ?? console.error;
+      onError(error);
+      return 0;
+    } finally {
+      this.#running = false;
+    }
+  }
+}
+
+export { EventsSync };

package/dist/packem_shared/InMemorySnapshotStore-BHVAD-Bp.mjs

@@ -0,0 +1,24 @@
+class InMemorySnapshotStore {
+  #store = /* @__PURE__ */ new Map();
+  save(key, snapshot) {
+    this.#store.set(key, structuredClone(snapshot));
+    return Promise.resolve();
+  }
+  load(key) {
+    const value = this.#store.get(key);
+    return Promise.resolve(value === void 0 ? null : structuredClone(value));
+  }
+  list() {
+    return Promise.resolve([...this.#store.keys()]);
+  }
+  delete(key) {
+    this.#store.delete(key);
+    return Promise.resolve();
+  }
+  clear() {
+    this.#store.clear();
+    return Promise.resolve();
+  }
+}
+
+export { InMemorySnapshotStore };

package/dist/packem_shared/LocalMirror-GeJ26eNe.mjs

@@ -0,0 +1,188 @@
+import { createSqlJsAdapter } from '../adapters/sqljs.mjs';
+import { applyDiffToDb as applyDiffToDatabase, escapeIdentifier } from './applyDiffToDb-DQ1xZp5J.mjs';
+import { EventLog } from './EventLog-zMy7AYP4.mjs';
+
+const MIRROR_META_TABLE = "__lunora_mirror_meta";
+const ensureMetaTable = (database) => {
+  database.exec(
+    `CREATE TABLE IF NOT EXISTS ${MIRROR_META_TABLE} (
+            key   TEXT PRIMARY KEY NOT NULL,
+            value TEXT NOT NULL
+        )`
+  );
+};
+class LocalMirror {
+  #db;
+  #tables;
+  #eventLog = new EventLog();
+  #changeListeners = /* @__PURE__ */ new Set();
+  /**
+   * Convenience factory that creates a {@link LocalMirror} backed by a
+   * {@link createSqlJsAdapter sql.js adapter} without needing to import
+   * and wire sql.js manually.
+   *
+   * The caller provides an initialised sql.js database — this method wraps
+   * it in an adapter and constructs the mirror.
+   * @example
+   * ```ts
+   * import initSqlJs from "sql.js";
+   *
+   * const SQL = await initSqlJs();
+   * const mirror = LocalMirror.create(new SQL.Database(), {
+   *   tables: { todos: { primaryKey: "id" } },
+   * });
+   * ```
+   */
+  static create(sqlJsDatabase, options) {
+    const adapter = createSqlJsAdapter(sqlJsDatabase);
+    return new LocalMirror({ db: adapter, tables: options?.tables });
+  }
+  constructor(options) {
+    this.#db = options.db;
+    this.#tables = { ...options.tables };
+    ensureMetaTable(this.#db);
+  }
+  /**
+   * Subscribe to data-change notifications. Fires after every {@link applyDiff}.
+   * Returns an unsubscribe function.
+   */
+  onChange(callback) {
+    this.#changeListeners.add(callback);
+    return () => {
+      this.#changeListeners.delete(callback);
+    };
+  }
+  // ── Public API ─────────────────────────────────────────────────────
+  /**
+   * The in-memory event log tracking every diff applied to this mirror.
+   * Use {@link EventLog.getSince} for catch-up replication across tabs
+   * or service-worker instances.
+   */
+  get eventLog() {
+    return this.#eventLog;
+  }
+  /**
+   * The raw SQLite adapter. Advanced consumers (e.g. the React hook)
+   * can use it for ad-hoc queries or bulk operations.
+   */
+  get db() {
+    return this.#db;
+  }
+  /**
+   * Apply a server-side diff to the local SQLite mirror.
+   *
+   * The diff is applied in a transaction and recorded in the event log
+   * so other tabs or the SW can catch up.
+   */
+  applyDiff(diff) {
+    if (diff.changes.length === 0) {
+      return;
+    }
+    const pkColumn = this.#tables[diff.table]?.primaryKey ?? "id";
+    this.#ensureTableSchema(diff);
+    applyDiffToDatabase(this.#db, diff, pkColumn);
+    this.#eventLog.append("table-diff", diff, [diff]);
+    for (const listener of this.#changeListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Run an arbitrary SQL query against the local mirror and return
+   * typed results.
+   * @example
+   * ```ts
+   * const users = mirror.query<{ id: string; name: string }>(
+   *   "SELECT id, name FROM users WHERE active = ?",
+   *   [true],
+   * );
+   * ```
+   */
+  query(sql, params) {
+    return this.#db.query(sql, params);
+  }
+  /**
+   * Delete every row from all known tables (preserves the event log
+   * and schema). Useful when re-syncing from scratch.
+   */
+  clearData() {
+    const tables = this.#db.query(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '__lunora_%' AND name NOT LIKE 'sqlite_%'`
+    );
+    this.#db.transaction(() => {
+      for (const { name } of tables) {
+        this.#db.exec(`DELETE FROM ${escapeIdentifier(name)}`);
+      }
+    });
+  }
+  /**
+   * Dispose the mirror and close the database connection.
+   */
+  close() {
+    this.#db.close();
+    this.#eventLog.clear();
+  }
+  // ── Schema helpers ─────────────────────────────────────────────────
+  /**
+   * Register a table schema so the mirror can create the table on
+   * first use.
+   */
+  registerTable(name, definition) {
+    this.#tables[name] = definition;
+  }
+  /**
+   * Return the list of mirrored table names.
+   */
+  get mirroredTables() {
+    return Object.keys(this.#tables);
+  }
+  // ── Internal ───────────────────────────────────────────────────────
+  /**
+   * Derive the UNION of non-PK column names across every non-delete change.
+   * @param diff The table diff whose changes are scanned.
+   * @param pk The primary-key column to exclude from the result.
+   */
+  static #collectDiffColumns(diff, pk) {
+    const requiredColumns = /* @__PURE__ */ new Set();
+    for (const change of diff.changes) {
+      if (change.type === "delete") {
+        continue;
+      }
+      for (const key of Object.keys(change.data)) {
+        if (key !== pk) {
+          requiredColumns.add(key);
+        }
+      }
+    }
+    return requiredColumns;
+  }
+  /**
+   * Ensure the target table exists with all columns needed by the diff.
+   *
+   * - If the table doesn't exist yet, CREATE it with columns derived from the diff data (PK + every non-delete column).
+   * - If the table already exists, ALTER TABLE ADD COLUMN for any keys in the diff that don't have a corresponding column yet (schema evolution).
+   */
+  #ensureTableSchema(diff) {
+    const pk = this.#tables[diff.table]?.primaryKey ?? "id";
+    const requiredColumns = LocalMirror.#collectDiffColumns(diff, pk);
+    const existing = this.#db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, [diff.table]);
+    if (existing.length === 0) {
+      let columnDefs = `${escapeIdentifier(pk)} TEXT PRIMARY KEY NOT NULL`;
+      for (const key of requiredColumns) {
+        columnDefs += `, ${escapeIdentifier(key)} TEXT`;
+      }
+      this.#db.exec(`CREATE TABLE IF NOT EXISTS ${escapeIdentifier(diff.table)} (${columnDefs})`);
+    } else if (requiredColumns.size > 0) {
+      const existingColumns = new Set(this.#db.query(`PRAGMA table_info(${escapeIdentifier(diff.table)})`).map((row) => row.name));
+      for (const key of requiredColumns) {
+        if (!existingColumns.has(key)) {
+          this.#db.exec(`ALTER TABLE ${escapeIdentifier(diff.table)} ADD COLUMN ${escapeIdentifier(key)} TEXT`);
+        }
+      }
+    }
+  }
+}
+
+export { LocalMirror };

package/dist/packem_shared/MaterializerRuntime-HqNXqJxp.mjs

@@ -0,0 +1,204 @@
+const defineMaterializer = (definition) => {
+  let state = definition.initial();
+  return {
+    def: definition,
+    get state() {
+      return Object.freeze(state);
+    },
+    setState(newState) {
+      state = newState;
+    },
+    apply(entry) {
+      state = definition.handle(state, entry);
+    },
+    reset() {
+      state = definition.initial();
+    }
+  };
+};
+class MaterializerRuntime {
+  #materializers;
+  #snapshotStore;
+  #doClient;
+  #unknownEventHandling;
+  /**
+   * The highest event seq that has been applied to all materializers.
+   * Starts at `0` and advances monotonically.
+   */
+  #appliedSeq = 0;
+  constructor(materializers, options = {}) {
+    this.#materializers = [...materializers];
+    this.#snapshotStore = options.snapshotStore;
+    this.#doClient = options.doClient;
+    this.#unknownEventHandling = options.unknownEventHandling ?? "warn";
+  }
+  // ── Public API ──────────────────────────────────────────────────────
+  /**
+   * The sequence number of the last event applied to all materializers.
+   */
+  get appliedSeq() {
+    return this.#appliedSeq;
+  }
+  /**
+   * Replay a batch of entries through all materializers.
+   *
+   * Entries with `seq < this.appliedSeq` are silently skipped (idempotent).
+   * @returns The number of entries actually applied.
+   */
+  applyEntries(entries) {
+    let count = 0;
+    for (const entry of entries) {
+      if (entry.seq < this.#appliedSeq) {
+        continue;
+      }
+      const statesBefore = this.#materializers.map((m) => m.state);
+      let stateChanged = false;
+      for (const m of this.#materializers) {
+        m.apply(entry);
+      }
+      for (let i = 0; i < this.#materializers.length; i += 1) {
+        if (this.#materializers[i]?.state !== statesBefore[i]) {
+          stateChanged = true;
+          break;
+        }
+      }
+      if (!stateChanged) {
+        this.#handleUnknownEvent(entry);
+      }
+      this.#appliedSeq = entry.seq + 1;
+      count += 1;
+    }
+    return count;
+  }
+  /**
+   * Apply the configured {@link UnknownEventHandling} strategy for an event
+   * that no materializer handled.
+   */
+  #handleUnknownEvent(entry) {
+    const strategy = this.#unknownEventHandling;
+    if (typeof strategy === "function") {
+      strategy(entry);
+      return;
+    }
+    switch (strategy) {
+      case "ignore": {
+        return;
+      }
+      case "fail": {
+        throw new Error(
+          `MaterializerRuntime: unhandled event type "${entry.type}" (seq ${String(entry.seq)}). Configure \`unknownEventHandling\` to handle this event or change the strategy.`
+        );
+      }
+      default: {
+        console.warn(
+          `[MaterializerRuntime] unhandled event type "${entry.type}" (seq ${String(entry.seq)}). The event was skipped. Configure \`unknownEventHandling\` if this is expected.`
+        );
+      }
+    }
+  }
+  /**
+   * Attempt to recover materialized state from a snapshot store.
+   *
+   * When a snapshot is found for a materializer, its state is restored
+   * and the snapshot's watermark (`appliedSeq`) is returned so the caller
+   * can skip replaying entries up to that point.
+   * @returns The highest `appliedSeq` across all recovered snapshots, or `0`.
+   */
+  async recoverFromSnapshots() {
+    if (!this.#snapshotStore) {
+      return 0;
+    }
+    let maxSeq = 0;
+    for (const m of this.#materializers) {
+      const raw = await this.#snapshotStore.load(m.def.name);
+      if (raw !== null && typeof raw === "object") {
+        const snapshot = raw;
+        if (snapshot.state !== void 0) {
+          m.setState(snapshot.state);
+        }
+        if (snapshot.appliedSeq > maxSeq) {
+          maxSeq = snapshot.appliedSeq;
+        }
+      }
+    }
+    if (maxSeq > this.#appliedSeq) {
+      this.#appliedSeq = maxSeq;
+    }
+    return maxSeq;
+  }
+  /**
+   * Persist the current state of all materializers as snapshots.
+   */
+  async persistSnapshots() {
+    if (!this.#snapshotStore) {
+      return;
+    }
+    for (const m of this.#materializers) {
+      await this.#snapshotStore.save(m.def.name, {
+        appliedSeq: this.#appliedSeq,
+        state: m.state
+      });
+    }
+  }
+  // ── DO-backed lifecycle (when a doClient is provided) ──────────────
+  /**
+   * Bootstrap the runtime from the EventLogDO.
+   *
+   * 1. Recover materialized state from snapshots (if a snapshotStore is
+   * configured).
+   * 2. Fetch all entries since the recovered watermark from the DO.
+   * 3. Apply them through the materializers.
+   *
+   * Call this once on startup / after the DO binding is available.
+   * @returns The number of entries applied during catch-up.
+   */
+  async initialize() {
+    if (!this.#doClient) {
+      return 0;
+    }
+    const snapshotSeq = await this.recoverFromSnapshots();
+    const entries = await this.#doClient.getSince(snapshotSeq);
+    if (entries.length === 0) {
+      return 0;
+    }
+    return this.applyEntries(entries);
+  }
+  /**
+   * Append an event to the EventLogDO and apply it through all
+   * materializers.
+   *
+   * This is a convenience over calling `doClient.append(...)` +
+   * `runtime.applyEntries(...)` yourself — it persists the event
+   * **then** applies the returned entry (with its assigned seq).
+   * @returns The persisted entry with its DO-assigned `seq`.
+   */
+  async appendEvent(input) {
+    if (!this.#doClient) {
+      throw new Error("MaterializerRuntime.appendEvent requires a doClient — pass one in the constructor options.");
+    }
+    const persisted = await this.#doClient.append([input]);
+    const entry = persisted[0];
+    if (!entry) {
+      throw new Error("MaterializerRuntime.appendEvent: DO returned empty result");
+    }
+    this.applyEntries([entry]);
+    return entry;
+  }
+  /**
+   * Reset all materializers to their initial state and clear snapshots.
+   */
+  reset() {
+    this.#appliedSeq = 0;
+    for (const m of this.#materializers) {
+      m.reset();
+    }
+  }
+  /**
+   * The list of registered materializers.
+   */
+  get materializers() {
+    return this.#materializers;
+  }
+}
+
+export { MaterializerRuntime, defineMaterializer };