@lunora/replica 0.0.0 → 1.0.0-alpha.3

package/dist/index.mjs

@@ -0,0 +1,20 @@
+export { createBetterSqlite3Adapter } from './adapters/better-sqlite3.mjs';
+export { createSqliteWasmAdapter } from './adapters/sqlite-wasm.mjs';
+export { createSqlJsAdapter } from './adapters/sqljs.mjs';
+export { applyDiff, applyDiffToSnapshot, applyDiffs } from './packem_shared/applyDiff-BtbIl1D3.mjs';
+export { defineEvents } from './packem_shared/defineEvents-DiBkPTh_.mjs';
+export { MaterializerRuntime, defineMaterializer } from './packem_shared/MaterializerRuntime-HqNXqJxp.mjs';
+export { applyDiffToDb, applyDiffsToDb } from './packem_shared/applyDiffToDb-DQ1xZp5J.mjs';
+export { EventEmitter } from './packem_shared/EventEmitter-CMZfct03.mjs';
+export { EventLog } from './packem_shared/EventLog-zMy7AYP4.mjs';
+export { EventLogDO } from './packem_shared/EventLogDO-CZYUvvSr.mjs';
+export { EventLogDOClient } from './packem_shared/EventLogDOClient-DGiEdi96.mjs';
+export { EventSource } from './packem_shared/EventSource-DfV4VoRD.mjs';
+export { eventsContext } from './packem_shared/eventsContext-Bk_p48hj.mjs';
+export { LocalMirror } from './packem_shared/LocalMirror-GeJ26eNe.mjs';
+export { isClientSeq, isGlobalSeq, isInputEvent } from './packem_shared/isClientSeq-C46BkzqJ.mjs';
+export { InMemorySnapshotStore } from './packem_shared/InMemorySnapshotStore-BHVAD-Bp.mjs';
+export { subscribeToMirror } from './packem_shared/subscribeToMirror-CiaM-nQ7.mjs';
+export { SubscriptionManager } from './packem_shared/SubscriptionManager-C5xbw0pg.mjs';
+export { EventsSync } from './packem_shared/EventsSync-DkVbU0WV.mjs';
+export { classifyChanges, createTableDiff, diffSize, isDiffEmpty, mergeDiffs } from './packem_shared/classifyChanges-aZmkxgVI.mjs';

package/dist/packem_shared/EventEmitter-CMZfct03.mjs

@@ -0,0 +1,92 @@
+class EventEmitter {
+  #listeners = /* @__PURE__ */ new Map();
+  #wildcardListeners = /* @__PURE__ */ new Set();
+  // ── Registration ──────────────────────────────────────────────────
+  /**
+   * Register a handler for a specific event type.
+   * @returns An unsubscribe function (equivalent to calling {@link off}).
+   */
+  on(event, handler) {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      this.off(event, handler);
+    };
+  }
+  /**
+   * Remove a previously registered handler.
+   */
+  off(event, handler) {
+    this.#listeners.get(event)?.delete(handler);
+  }
+  /**
+   * Register a wildcard handler that fires for **every** event type.
+   * @returns An unsubscribe function.
+   */
+  onAny(handler) {
+    this.#wildcardListeners.add(handler);
+    return () => {
+      this.#wildcardListeners.delete(handler);
+    };
+  }
+  /**
+   * Remove a wildcard handler.
+   */
+  offAny(handler) {
+    this.#wildcardListeners.delete(handler);
+  }
+  // ── Emission ──────────────────────────────────────────────────────
+  /**
+   * Emit an event. All registered handlers (typed + wildcard) are invoked
+   * synchronously. Exceptions from handlers are caught and silently
+   * swallowed — they **must not** break the emitter loop.
+   * @returns `true` if at least one handler was called.
+   */
+  emit(event, payload) {
+    let called = false;
+    const typed = this.#listeners.get(event);
+    if (typed) {
+      for (const handler of typed) {
+        try {
+          handler(payload);
+          called = true;
+        } catch {
+        }
+      }
+    }
+    for (const handler of this.#wildcardListeners) {
+      try {
+        handler(event, payload);
+        called = true;
+      } catch {
+      }
+    }
+    return called;
+  }
+  // ── Introspection ─────────────────────────────────────────────────
+  /**
+   * Return `true` when at least one listener is registered for `event`.
+   */
+  hasListeners(event) {
+    return (this.#listeners.get(event)?.size ?? 0) > 0 || this.#wildcardListeners.size > 0;
+  }
+  /**
+   * Return the number of typed listeners for a specific event.
+   */
+  listenerCount(event) {
+    return this.#listeners.get(event)?.size ?? 0;
+  }
+  /**
+   * Remove all listeners.
+   */
+  clear() {
+    this.#listeners.clear();
+    this.#wildcardListeners.clear();
+  }
+}
+
+export { EventEmitter };

package/dist/packem_shared/EventLog-zMy7AYP4.mjs

@@ -0,0 +1,162 @@
+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/EventLogDO-CZYUvvSr.mjs

@@ -0,0 +1,235 @@
+const toArray = (cursor) => {
+  if (typeof cursor.toArray === "function") {
+    return cursor.toArray();
+  }
+  if (typeof cursor[Symbol.iterator] === "function") {
+    return [...cursor];
+  }
+  return [];
+};
+const rowsToEntries = (cursor) => {
+  const rows = toArray(cursor);
+  return rows.map((row) => {
+    return {
+      seq: row.seq,
+      type: row.type,
+      payload: JSON.parse(row.payload),
+      timestamp: row.timestamp,
+      clientId: row.client_id ?? void 0,
+      sessionId: row.session_id ?? void 0,
+      parentSeqNum: row.parent_seq ?? void 0
+    };
+  });
+};
+class EventLogDO {
+  state;
+  env;
+  /** Whether the `events` table has been created. */
+  #initialized = false;
+  constructor(state, env) {
+    this.state = state;
+    this.env = env;
+  }
+  // ── Fetch (RPC dispatch) ──────────────────────────────────────────
+  async fetch(request) {
+    this.#ensureTable();
+    const url = new URL(request.url);
+    try {
+      if (request.method === "POST" && url.pathname === "/append") {
+        return await this.#handleAppend(request);
+      }
+      if (request.method === "GET" && url.pathname === "/since") {
+        return this.#handleSince(url);
+      }
+      if (request.method === "GET" && url.pathname === "/range") {
+        return this.#handleRange(url);
+      }
+      if (request.method === "GET" && url.pathname === "/size") {
+        return this.#handleSize();
+      }
+      if (request.method === "GET" && url.pathname === "/state") {
+        return this.#handleState();
+      }
+    } catch (error) {
+      console.error("[event-log-do] request failed:", error);
+      return Response.json(
+        {
+          error: {
+            code: "INTERNAL_ERROR",
+            message: "internal error"
+          }
+        },
+        { status: 500, headers: { "content-type": "application/json" } }
+      );
+    }
+    return Response.json(
+      { error: { code: "NOT_FOUND", message: "unknown route" } },
+      {
+        status: 404,
+        headers: { "content-type": "application/json" }
+      }
+    );
+  }
+  // ── Handlers ──────────────────────────────────────────────────────
+  /** POST /append — insert events, return entries with assigned seqs. */
+  async #handleAppend(request) {
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return Response.json(
+        { error: { code: "BAD_REQUEST", message: "invalid JSON body" } },
+        {
+          status: 400,
+          headers: { "content-type": "application/json" }
+        }
+      );
+    }
+    if (!Array.isArray(body.events) || body.events.length === 0 || body.events.some((eventRecord) => typeof eventRecord.type !== "string" || eventRecord.type.length === 0)) {
+      return Response.json(
+        { error: { code: "BAD_REQUEST", message: "events[] with a non-empty string `type` required" } },
+        {
+          status: 400,
+          headers: { "content-type": "application/json" }
+        }
+      );
+    }
+    const entries = [];
+    const { sql } = this.state.storage;
+    const now = Date.now();
+    for (const eventRecord of body.events) {
+      const seq = EventLogDO.#nextSeq(sql);
+      const entry = {
+        seq,
+        type: eventRecord.type,
+        payload: eventRecord.payload,
+        timestamp: eventRecord.timestamp ?? now
+      };
+      EventLogDO.#insertEvent(sql, entry);
+      entries.push(entry);
+    }
+    const response = { entries };
+    return Response.json(response, {
+      status: 200,
+      headers: { "content-type": "application/json" }
+    });
+  }
+  /** GET /since?seq=N — return entries with seq >= N. */
+  #handleSince(url) {
+    const seqParameter = url.searchParams.get("seq");
+    const sinceSeq = seqParameter === null ? 0 : Number(seqParameter);
+    if (!Number.isFinite(sinceSeq) || sinceSeq < 0) {
+      return Response.json(
+        { error: { code: "BAD_REQUEST", message: "invalid seq" } },
+        {
+          status: 400,
+          headers: { "content-type": "application/json" }
+        }
+      );
+    }
+    const { sql } = this.state.storage;
+    const cursor = sql.exec(
+      "SELECT seq, type, payload, timestamp, client_id, session_id, parent_seq FROM events WHERE seq >= ? ORDER BY seq ASC",
+      sinceSeq
+    );
+    const entries = rowsToEntries(cursor);
+    return Response.json(
+      { entries },
+      {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      }
+    );
+  }
+  /** GET /range?from=N&amp;limit=M — paginated read (default limit 50). */
+  #handleRange(url) {
+    const fromParameter = url.searchParams.get("from");
+    const fromSeq = fromParameter === null ? 0 : Number(fromParameter);
+    const limitParameter = url.searchParams.get("limit");
+    const limit = limitParameter === null ? 50 : Number(limitParameter);
+    if (!Number.isFinite(fromSeq) || fromSeq < 0 || !Number.isFinite(limit) || limit < 1 || limit > 1e3) {
+      return Response.json(
+        { error: { code: "BAD_REQUEST", message: "invalid from/limit" } },
+        {
+          status: 400,
+          headers: { "content-type": "application/json" }
+        }
+      );
+    }
+    const { sql } = this.state.storage;
+    const cursor = sql.exec(
+      "SELECT seq, type, payload, timestamp, client_id, session_id, parent_seq FROM events WHERE seq >= ? ORDER BY seq ASC LIMIT ?",
+      fromSeq,
+      limit + 1
+      // Fetch one extra to detect hasMore
+    );
+    const allRows = rowsToEntries(cursor);
+    const hasMore = allRows.length > limit;
+    const entries = hasMore ? allRows.slice(0, limit) : allRows;
+    const response = { entries, hasMore };
+    return Response.json(response, {
+      status: 200,
+      headers: { "content-type": "application/json" }
+    });
+  }
+  /** GET /size — return the number of stored events. */
+  #handleSize() {
+    const { sql } = this.state.storage;
+    const cursor = sql.exec("SELECT COUNT(*) AS count FROM events");
+    const rows = toArray(cursor);
+    const count = rows[0]?.count ?? 0;
+    return Response.json(
+      { count },
+      {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      }
+    );
+  }
+  /** GET /state — return the full event log state. */
+  #handleState() {
+    const { sql } = this.state.storage;
+    const cursor = sql.exec("SELECT seq, type, payload, timestamp, client_id, session_id, parent_seq FROM events ORDER BY seq ASC");
+    const entries = rowsToEntries(cursor);
+    const nextSeq = (entries.at(-1)?.seq ?? -1) + 1;
+    return Response.json({ entries, nextSeq }, { status: 200, headers: { "content-type": "application/json" } });
+  }
+  // ── Internal ──────────────────────────────────────────────────────
+  #ensureTable() {
+    if (this.#initialized) {
+      return;
+    }
+    const { sql } = this.state.storage;
+    sql.exec(
+      "CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL, payload TEXT NOT NULL, timestamp INTEGER NOT NULL, client_id TEXT, session_id TEXT, parent_seq INTEGER)"
+    );
+    this.#initialized = true;
+  }
+  /** Get the next available sequence number. */
+  static #nextSeq(sql) {
+    const cursor = sql.exec("SELECT COALESCE(MAX(seq), -1) + 1 AS next_seq FROM events");
+    const rows = toArray(cursor);
+    return rows[0]?.next_seq ?? 0;
+  }
+  /** Insert a single event entry. */
+  /* eslint-disable unicorn/no-null -- SQLite bindings use `null` for missing optional columns */
+  static #insertEvent(sql, entry) {
+    let parentSeq = null;
+    if (typeof entry.parentSeqNum === "number") {
+      parentSeq = entry.parentSeqNum;
+    }
+    sql.exec(
+      "INSERT INTO events (seq, type, payload, timestamp, client_id, session_id, parent_seq) VALUES (?, ?, ?, ?, ?, ?, ?)",
+      entry.seq,
+      entry.type,
+      JSON.stringify(entry.payload),
+      entry.timestamp,
+      entry.clientId ?? null,
+      entry.sessionId ?? null,
+      parentSeq
+    );
+  }
+  /* eslint-enable unicorn/no-null */
+}
+
+export { EventLogDO };

package/dist/packem_shared/EventLogDOClient-DGiEdi96.mjs

@@ -0,0 +1,86 @@
+class EventLogDOClient {
+  #fetch;
+  constructor(options) {
+    this.#fetch = options.fetch;
+  }
+  // ── Append ─────────────────────────────────────────────────────────
+  /**
+   * Append one or more events to the log.
+   * @returns The persisted entries with their assigned `seq` numbers.
+   */
+  async append(events) {
+    const body = JSON.stringify({ events });
+    const response = await this.#fetch(
+      new Request("https://do/append", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body
+      })
+    );
+    if (!response.ok) {
+      throw await EventLogDOClient.#toError(response, "append");
+    }
+    const data = await response.json();
+    return data.entries;
+  }
+  // ── Read / replay ───────────────────────────────────────────────────
+  /**
+   * Fetch all entries with `seq >= sinceSeq`.
+   *
+   * Pass `sinceSeq = 0` to fetch the entire log.
+   */
+  async getSince(sinceSeq) {
+    const response = await this.#fetch(new Request(`https://do/since?seq=${String(sinceSeq)}`));
+    if (!response.ok) {
+      throw await EventLogDOClient.#toError(response, "getSince");
+    }
+    const data = await response.json();
+    return data.entries;
+  }
+  /**
+   * Fetch a paginated range of entries.
+   * @returns `{ entries, hasMore }` — `hasMore` is `true` when another
+   * page exists (i.e. the DO returned `limit + 1` rows).
+   */
+  async getRange(fromSeq, limit = 50) {
+    const response = await this.#fetch(new Request(`https://do/range?from=${String(fromSeq)}&limit=${String(limit)}`));
+    if (!response.ok) {
+      throw await EventLogDOClient.#toError(response, "getRange");
+    }
+    return await response.json();
+  }
+  /**
+   * Return the total number of entries currently in the log.
+   */
+  async getSize() {
+    const response = await this.#fetch(new Request("https://do/size"));
+    if (!response.ok) {
+      throw await EventLogDOClient.#toError(response, "getSize");
+    }
+    const data = await response.json();
+    return data.count;
+  }
+  /**
+   * Return the full log state — all entries plus the next seq number.
+   */
+  async getState() {
+    const response = await this.#fetch(new Request("https://do/state"));
+    if (!response.ok) {
+      throw await EventLogDOClient.#toError(response, "getState");
+    }
+    return await response.json();
+  }
+  // ── Internal ────────────────────────────────────────────────────────
+  /** Parse an error response body and return a descriptive `Error`. */
+  static async #toError(response, method) {
+    try {
+      const body = await response.json();
+      const message = body.error?.message ?? response.statusText;
+      return new Error(`EventLogDO.${method} failed (${String(response.status)}): ${message}`);
+    } catch {
+      return new Error(`EventLogDO.${method} failed (${String(response.status)}): ${response.statusText}`);
+    }
+  }
+}
+
+export { EventLogDOClient };