@lunora/replica 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/SubscriptionManager-C5xbw0pg.mjs

@@ -0,0 +1,75 @@
+class SubscriptionManager {
+  #subscriptions = /* @__PURE__ */ new Map();
+  #nextId = 0;
+  // ── Registration ──────────────────────────────────────────────────
+  /**
+   * Subscribe to every state change emitted by the event source.
+   * @returns Unsubscribe function.
+   */
+  onStateChange(callback) {
+    const id = String(this.#nextId);
+    this.#nextId += 1;
+    const sub = { kind: "state", id, callback };
+    this.#subscriptions.set(id, sub);
+    return () => {
+      this.#subscriptions.delete(id);
+    };
+  }
+  /**
+   * Subscribe to a specific event type.
+   * @param eventType The event type to listen for (matches `entry.type`).
+   * @param callback Invoked with each matching entry.
+   * @returns Unsubscribe function.
+   */
+  onEvent(eventType, callback) {
+    const id = String(this.#nextId);
+    this.#nextId += 1;
+    const sub = { kind: "event", id, eventType, callback };
+    this.#subscriptions.set(id, sub);
+    return () => {
+      this.#subscriptions.delete(id);
+    };
+  }
+  // ── Notification ──────────────────────────────────────────────────
+  /**
+   * Notify all state-change subscribers with the current state.
+   */
+  notifyState(state) {
+    for (const sub of this.#subscriptions.values()) {
+      if (sub.kind === "state") {
+        try {
+          sub.callback(state);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Notify event-type subscribers whose `eventType` matches.
+   */
+  notifyEvent(entry) {
+    for (const sub of this.#subscriptions.values()) {
+      if (sub.kind === "event" && sub.eventType === entry.type) {
+        try {
+          sub.callback(entry);
+        } catch {
+        }
+      }
+    }
+  }
+  // ── Introspection ─────────────────────────────────────────────────
+  /**
+   * Return the total number of active subscriptions.
+   */
+  get size() {
+    return this.#subscriptions.size;
+  }
+  /**
+   * Remove all subscriptions.
+   */
+  clear() {
+    this.#subscriptions.clear();
+  }
+}
+
+export { SubscriptionManager };

package/dist/packem_shared/applyDiff-BtbIl1D3.mjs

@@ -0,0 +1,40 @@
+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 };

package/dist/packem_shared/applyDiffToDb-DQ1xZp5J.mjs

@@ -0,0 +1,58 @@
+const escapeIdentifier = (id) => `\`${id.replaceAll("`", "``")}\``;
+const setClause = (keys) => keys.map((key) => `${escapeIdentifier(key)} = ?`).join(", ");
+const colList = (keys) => `(${keys.map((key) => escapeIdentifier(key)).join(", ")})`;
+const valueList = (count) => `(${Array.from({ length: count }).fill("?").join(", ")})`;
+const applySingleDiff = (database, diff, pkColumn) => {
+  if (diff.changes.length === 0) {
+    return;
+  }
+  const table = escapeIdentifier(diff.table);
+  const pk = escapeIdentifier(pkColumn);
+  for (const change of diff.changes) {
+    switch (change.type) {
+      case "delete": {
+        database.exec(`DELETE FROM ${table} WHERE ${pk} = ?`, [change.id]);
+        break;
+      }
+      case "insert": {
+        const { data } = change;
+        const keys = Object.keys(data);
+        if (keys.length === 0) {
+          continue;
+        }
+        const sql = `INSERT OR REPLACE INTO ${table} ${colList(keys)} VALUES ${valueList(keys.length)}`;
+        const values = keys.map((k) => data[k]);
+        database.exec(sql, values);
+        break;
+      }
+      case "update": {
+        const { data } = change;
+        const keys = Object.keys(data);
+        if (keys.length === 0) {
+          continue;
+        }
+        const sql = `UPDATE ${table} SET ${setClause(keys)} WHERE ${pk} = ?`;
+        const values = [...keys.map((k) => data[k]), change.id];
+        database.exec(sql, values);
+        break;
+      }
+    }
+  }
+};
+const applyDiffToDatabase = (database, diff, pkColumn) => {
+  database.transaction(() => {
+    applySingleDiff(database, diff, pkColumn ?? "id");
+  });
+};
+const applyDiffsToDatabase = (database, diffs) => {
+  if (diffs.length === 0) {
+    return;
+  }
+  database.transaction(() => {
+    for (const diff of diffs) {
+      applySingleDiff(database, diff, "id");
+    }
+  });
+};
+
+export { applyDiffToDatabase as applyDiffToDb, applyDiffsToDatabase as applyDiffsToDb, escapeIdentifier };

package/dist/packem_shared/classifyChanges-aZmkxgVI.mjs

@@ -0,0 +1,38 @@
+const createTableDiff = (table, changes, timestamp) => {
+  return {
+    table,
+    changes,
+    timestamp: timestamp ?? Date.now()
+  };
+};
+const isDiffEmpty = (diff) => diff.changes.length === 0;
+const diffSize = (diff) => diff.changes.length;
+const classifyChanges = (diff) => {
+  const inserts = [];
+  const updates = [];
+  const deletes = [];
+  for (const change of diff.changes) {
+    if (change.type === "insert") {
+      inserts.push(change);
+    } else if (change.type === "update") {
+      updates.push(change);
+    } else {
+      deletes.push(change);
+    }
+  }
+  return { inserts, updates, deletes };
+};
+const mergeDiffs = (diffs) => {
+  if (diffs.length === 0) {
+    return null;
+  }
+  const first = diffs[0];
+  const last = diffs[diffs.length - 1];
+  return createTableDiff(
+    first.table,
+    diffs.flatMap((d) => d.changes),
+    last.timestamp
+  );
+};
+
+export { classifyChanges, createTableDiff, diffSize, isDiffEmpty, mergeDiffs };

package/dist/packem_shared/defineEvents-DiBkPTh_.mjs

@@ -0,0 +1,28 @@
+const defineEvents = (definition, options) => {
+  const result = {};
+  const typeMap = {};
+  const prefix = options?.version ? `${options.version}.` : "";
+  for (const [namespace, events] of Object.entries(definition)) {
+    const nsObject = {};
+    for (const [name] of Object.entries(events)) {
+      const qualifiedType = `${prefix}${namespace}.${name}`;
+      typeMap[qualifiedType] = void 0;
+      const factory = Object.assign(
+        (payload) => {
+          return {
+            type: qualifiedType,
+            payload,
+            timestamp: Date.now()
+          };
+        },
+        { type: qualifiedType }
+      );
+      nsObject[name] = factory;
+    }
+    result[namespace] = nsObject;
+  }
+  result._types = typeMap;
+  return result;
+};
+
+export { defineEvents };

package/dist/packem_shared/eventsContext-Bk_p48hj.mjs

@@ -0,0 +1,6 @@
+const eventsContext = (client) => {
+  const facade = client;
+  return async ({ ctx: _context, next }) => next({ ctx: { events: facade } });
+};
+
+export { eventsContext };

package/dist/packem_shared/isClientSeq-C46BkzqJ.mjs

@@ -0,0 +1,5 @@
+const isGlobalSeq = (seq) => typeof seq === "number";
+const isClientSeq = (seq) => typeof seq !== "number" && "rebaseGeneration" in seq;
+const isInputEvent = (value) => typeof value === "object" && value !== null && "type" in value && typeof value.type === "string" && "payload" in value && "timestamp" in value;
+
+export { isClientSeq, isGlobalSeq, isInputEvent };

package/dist/packem_shared/local-mirror.d-Bp19ueGy.d.mts

@@ -0,0 +1,412 @@
+import { S as SqliteAdapter } from "./types.d-VfJ76cK4.mjs";
+/**
+* Row-level change kind within a TableDiff.
+*
+* Each change represents one row that was inserted, updated, or deleted on
+* the server since the last sync tick.
+*/
+type RowChange = {
+  data: Record<string, unknown>;
+  type: "insert";
+} | {
+  data: Record<string, unknown>;
+  id: string;
+  type: "update";
+} | {
+  id: string;
+  type: "delete";
+};
+/**
+* A scoped, ordered set of row changes for a single table.
+*
+* `TableDiff` is the unit of replication between the server and the local
+* SQLite mirror. The server pushes diffs over the poke protocol; the
+* client applies them via `applyDiff`.
+*/
+interface TableDiff {
+  /** Ordered row changes — insert/update/delete, earliest first. */
+  readonly changes: ReadonlyArray<RowChange>;
+  /** 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.
+*/
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => TableDiff;
+/**
+* Return `true` when the diff contains no row changes.
+*/
+declare const isDiffEmpty: (diff: TableDiff) => boolean;
+/**
+* Return the number of rows touched by the diff (inserts + updates + deletes).
+*/
+declare const diffSize: (diff: TableDiff) => number;
+/**
+* Partition a {@link TableDiff} into three categories for batch processing.
+*/
+declare const classifyChanges: (diff: TableDiff) => {
+  deletes: RowChange[];
+  inserts: RowChange[];
+  updates: RowChange[];
+};
+/**
+* Merge several diffs for the same table into one (ordering preserved).
+*
+* Returns `null` when the input list is empty.
+*/
+declare const mergeDiffs: (diffs: ReadonlyArray<TableDiff>) => TableDiff | null;
+/**
+* Sequence-number types for the event log.
+*
+* Three namespaces match the vocabulary established by event-sourcing:
+*
+* | Namespace | Shape              | Producer                  | Consumer                     |
+* |-----------|--------------------|---------------------------|------------------------------|
+* | `Global`  | `number`           | `EventLog` / `EventLogDO` | Materializers, subscribers   |
+* | `Input`   | No seq (optimistic) | `defineEvents` factories  | `EventLog.append` / DO client|
+* | `Client`  | `{generation,seq}`  | _(future: rebase engine)_ | _(future: rebase-aware code)_|
+* @module
+*/
+/**
+* A server-authoritative (global) sequence number.
+*
+* Monotonically increasing, assigned by `EventLog` (in-memory) or
+* `EventLogDO` (Durable Object). All confirmed log entries carry a
+* `GlobalSeq`.
+*/
+type GlobalSeq = number;
+/**
+* A client-originated composite sequence number designed to survive rebase.
+*
+* Carries the last-confirmed `global` seq, a monotonically increasing
+* `client` counter, and a `rebaseGeneration` that increments whenever the
+* client's local events are rebased onto a new upstream baseline.
+*/
+interface ClientSeq {
+  /** Client-local monotonically increasing counter. */
+  readonly client: number;
+  /** The last-confirmed global sequence number. 0 for unconfirmed events. */
+  readonly global: number;
+  /** Incremented on every rebase. */
+  readonly rebaseGeneration: number;
+}
+/**
+* Discriminated union of all sequence-number types.
+*/
+type Seq = GlobalSeq | ClientSeq;
+/**
+* Narrow `Seq` to `GlobalSeq`.
+*/
+declare const isGlobalSeq: (seq: Seq) => seq is GlobalSeq;
+/**
+* Narrow `Seq` to `ClientSeq`.
+*/
+declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
+/**
+* An event that has **not** yet been assigned a sequence number.
+*
+* Input events represent optimistic / command payloads before the server
+* confirms them. They carry `type`, `payload`, and `timestamp` but no
+* `seq` — the log assigns one on append.
+*
+* Create input events via `defineEvents` factories:
+*
+* ```ts
+* const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
+* // event: InputEvent&lt;"chat.messageSent", { channelId: string; text: string }>
+* ```
+*/
+interface InputEvent<Type extends string = string, Payload = unknown> {
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: Payload;
+  /** Millisecond timestamp (epoch) when the event was created. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. `"chat.messageSent"`). */
+  readonly type: Type;
+}
+/**
+* Type guard: check whether `value` is an {@link InputEvent}.
+*/
+declare const isInputEvent: (value: unknown) => value is InputEvent;
+/**
+* A single entry in the append-only {@link EventLog}.
+*
+* Entries are immutable once appended; the `seq` field is assigned
+* monotonically by the log and doubles as a watermark for catch-up
+* replication between tabs or service-worker instances.
+*/
+interface EventLogEntry {
+  /**
+  * Globally-unique client identifier that originated this event.
+  * Set by clients that support offline / optimistic writes.
+  * `undefined` when the event was created server-side.
+  */
+  readonly clientId?: string;
+  /**
+  * The sequence number of the causal parent event.
+  *
+  * A {@link GlobalSeq} for events confirmed by the server (pointing
+  * to the previous confirmed event), or a {@link ClientSeq} for
+  * optimistic / offline events pointing to the local predecessor.
+  * `undefined` for the first event in a log.
+  */
+  readonly parentSeqNum?: Seq;
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: unknown;
+  /** Monotonically increasing sequence number (0-based). A {@link GlobalSeq}. */
+  readonly seq: GlobalSeq;
+  /**
+  * Session identifier from the originating client.
+  * Paired with `clientId` to disambiguate concurrent sessions.
+  */
+  readonly sessionId?: string;
+  /**
+  * Optional table diffs that this event produced.
+  * When present, a consumer can re-play the event by applying the diffs
+  * to its local mirror without re-executing the originating mutation.
+  */
+  readonly tableDiffs?: ReadonlyArray<TableDiff>;
+  /** Millisecond timestamp (epoch) when the entry was appended. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. "row-insert", "mutation-apply"). */
+  readonly type: string;
+}
+/**
+* Serialised snapshot of the log — used for persistence and transfer.
+*/
+interface EventLogSnapshot {
+  readonly entries: ReadonlyArray<EventLogEntry>;
+  /** The sequence number of the last entry (head), or `null` for an empty log. */
+  readonly headSeq: GlobalSeq | null;
+  readonly nextSeq: number;
+}
+/**
+* Optional metadata that can accompany an appended event.
+*/
+interface AppendOptions {
+  /** Globally-unique client identifier. */
+  readonly clientId?: string;
+  /**
+  * Causal parent sequence number.
+  * Automatically set to the previous entry's seq when omitted.
+  */
+  readonly parentSeqNum?: Seq;
+  /** Session identifier within the client. */
+  readonly sessionId?: string;
+}
+/**
+* An append-only, in-memory event log for local event sourcing.
+*
+* The log is the single source of truth for "what happened" and drives
+* catch-up replication: a new tab or service worker asks for entries
+* since its known `seq` watermark and re-applies them.
+* @remarks This class is intentionally **not** a full SQLite-backed log.
+* Persistence is the caller's responsibility (write the snapshot
+* to IndexedDB / OPFS via {@link EventLog#snapshot}).
+*/
+declare class EventLog {
+  #private;
+  /**
+  * Append a new entry to the log.
+  *
+  * Accepts either an {@link InputEvent} (e.g. from a `defineEvents` factory)
+  * or the traditional `(type, payload, tableDiffs?)` triple.
+  * @returns The newly created entry (already written to the log).
+  */
+  append(event: InputEvent, options?: AppendOptions): EventLogEntry;
+  append(type: string, payload: unknown, tableDiffs?: ReadonlyArray<TableDiff>, options?: AppendOptions): EventLogEntry;
+  /**
+  * 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: ReadonlyArray<InputEvent | {
+    payload: unknown;
+    type: string;
+  }>): EventLogEntry[];
+  /**
+  * 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: EventLogSnapshot): void;
+  /**
+  * Return **all** entries whose `seq >= sinceSeq`.
+  * Useful for catch-up: "give me everything since my last watermark".
+  */
+  getSince(sinceSeq: number): ReadonlyArray<EventLogEntry>;
+  /**
+  * Paginated read starting at `fromSeq`.
+  * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
+  * entries exist beyond the requested page.
+  */
+  getFrom(fromSeq: number, limit?: number): {
+    entries: ReadonlyArray<EventLogEntry>;
+    hasMore: boolean;
+  };
+  /**
+  * Return all entries as a snapshot suitable for serialisation.
+  */
+  snapshot(): EventLogSnapshot;
+  /** Number of entries currently in the log. */
+  get size(): number;
+  /** The next sequence number that will be assigned. */
+  get nextSeq(): number;
+  /** Return `true` when there are no entries. */
+  get isEmpty(): boolean;
+  /**
+  * 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(): GlobalSeq | null;
+  /** Remove all entries (primarily for testing). */
+  clear(): void;
+  /**
+  * 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}.
+  */
+  events(fromSeq?: number): AsyncGenerator<EventLogEntry>;
+}
+interface MirrorTableDef {
+  /** Primary key column name (defaults to `"id"`). */
+  readonly primaryKey?: string;
+}
+/**
+* Options for constructing a {@link LocalMirror}.
+*/
+interface LocalMirrorOptions {
+  /** Platform-specific SQLite adapter. */
+  readonly db: SqliteAdapter;
+  /**
+  * Table schemas the mirror should manage.
+  *
+  * On first use the mirror creates any missing tables automatically
+  * based on the columns observed in the first diff/row applied.
+  * If you want a fixed schema, pass it here with explicit column
+  * definitions in `columns`.
+  */
+  readonly tables?: Record<string, MirrorTableDef>;
+}
+/**
+* Local SQLite mirror that maintains a client-side replica of server
+* tables by applying {@link TableDiff} deltas.
+*
+* Usage:
+* ```ts
+* import { createSqlJsAdapter } from "@lunora/replica/adapters/sqljs";
+* import initSqlJs from "sql.js";
+*
+* const SQL = await initSqlJs();
+* const db = createSqlJsAdapter(new SQL.Database());
+*
+* const mirror = new LocalMirror({ db });
+*
+* // Apply a server diff:
+* mirror.applyDiff(someDiff);
+*
+* // Query locally:
+* const rows = mirror.query&lt;{ id: string; name: string }>(
+*   "SELECT id, name FROM users WHERE name LIKE ?",
+*   ["alice%"],
+* );
+* ```
+*/
+type ChangeSubscriber = () => void;
+declare class LocalMirror {
+  #private;
+  /**
+  * 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: {
+    close: () => void;
+    exec: (sql: string) => {
+      columns: string[];
+      values: unknown[][];
+    }[];
+    run: (sql: string, params?: unknown[]) => void;
+  }, options?: {
+    tables?: Record<string, MirrorTableDef>;
+  }): LocalMirror;
+  constructor(options: LocalMirrorOptions);
+  /**
+  * Subscribe to data-change notifications. Fires after every {@link applyDiff}.
+  * Returns an unsubscribe function.
+  */
+  onChange(callback: ChangeSubscriber): () => void;
+  /**
+  * 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(): EventLog;
+  /**
+  * The raw SQLite adapter. Advanced consumers (e.g. the React hook)
+  * can use it for ad-hoc queries or bulk operations.
+  */
+  get db(): SqliteAdapter;
+  /**
+  * 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: TableDiff): void;
+  /**
+  * 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<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): T[];
+  /**
+  * Delete every row from all known tables (preserves the event log
+  * and schema). Useful when re-syncing from scratch.
+  */
+  clearData(): void;
+  /**
+  * Dispose the mirror and close the database connection.
+  */
+  close(): void;
+  /**
+  * Register a table schema so the mirror can create the table on
+  * first use.
+  */
+  registerTable(name: string, definition: MirrorTableDef): void;
+  /**
+  * Return the list of mirrored table names.
+  */
+  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 };