@lunora/replica 1.0.0-alpha.2 → 1.0.0-alpha.21

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

@@ -0,0 +1,530 @@
+import { S as SqliteAdapter } from "./types.d-CkMkSwLJ.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.
+ * @experimental
+ */
+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`.
+ * @experimental
+ */
+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 and a
+ * fresh stable `id` (unless one is explicitly provided).
+ * @experimental
+ */
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number, id?: string) => TableDiff;
+/**
+ * Return `true` when the diff contains no row changes.
+ * @experimental
+ */
+declare const isDiffEmpty: (diff: TableDiff) => boolean;
+/**
+ * Return the number of rows touched by the diff (inserts + updates + deletes).
+ * @experimental
+ */
+declare const diffSize: (diff: TableDiff) => number;
+/**
+ * Partition a {@link TableDiff} into three categories for batch processing.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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`.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+type Seq = GlobalSeq | ClientSeq;
+/**
+ * Narrow `Seq` to `GlobalSeq`.
+ * @experimental
+ */
+declare const isGlobalSeq: (seq: Seq) => seq is GlobalSeq;
+/**
+ * Narrow `Seq` to `ClientSeq`.
+ * @experimental
+ */
+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 }>
+ * ```
+ * @experimental
+ */
+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}.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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;
+  /**
+   * 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.
+ *
+ * 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}).
+ * @experimental
+ */
+declare class EventLog {
+  #private;
+  constructor(options?: EventLogOptions);
+  /**
+   * 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.
+   *
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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).
+   *
+   * 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>;
+}
+/**
+ * `MirrorTableDef` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+ * @experimental
+ */
+interface MirrorTableDef {
+  /** Primary key column name (defaults to `"id"`). */
+  readonly primaryKey?: string;
+}
+/**
+ * Options for constructing a {@link LocalMirror}.
+ * @experimental
+ */
+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
+   * 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;
+/**
+ * `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+ * @experimental
+ */
+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;
+  /**
+   * 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
+   * 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.
+   *
+   * 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;
+  /**
+   * 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, 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/packem_shared/subscribeToMirror-Dru_AYBu.mjs

@@ -0,0 +1 @@
+const d=e=>`fn_${e.replaceAll(/[/:.]/g,"_")}`,u=e=>Array.isArray(e)?e:e!==null&&typeof e=="object"?[e]:[],g=(e,a,n,f,i)=>{const l=d(n.__lunoraRef);a.registerTable(l,{});let p=new Set;return e.subscribe(n,f,b=>{const y=u(b),o=new Set,t=[];for(const r of y){const c=r,s=c.id;(typeof s=="string"||typeof s=="number")&&o.add(String(s)),t.push({type:"insert",data:c})}for(const r of p)o.has(r)||t.push({type:"delete",id:r});p=o,t.length!==0&&a.applyDiff({table:l,changes:t,timestamp:Date.now()})},{shardKey:i})};export{g as subscribeToMirror};

package/dist/packem_shared/{types.d-VfJ76cK4.d.mts → types.d-CkMkSwLJ.d.mts}

@@ -1,10 +1,11 @@
 /**
-* Abstract SQLite driver interface used by the local mirror.
-*
-* Each runtime (browser via sql.js, React Native via expo-sqlite,
-* Node via better-sqlite3) provides its own adapter implementing this
-* interface so the rest of `@lunora/replica` stays platform-agnostic.
-*/
+ * Abstract SQLite driver interface used by the local mirror.
+ *
+ * Each runtime (browser via sql.js, React Native via expo-sqlite,
+ * Node via better-sqlite3) provides its own adapter implementing this
+ * interface so the rest of `@lunora/replica` stays platform-agnostic.
+ * @experimental
+ */
 interface SqliteAdapter {
   /** Close the database connection. */
   close: () => void;
@@ -13,9 +14,9 @@ interface SqliteAdapter {
   /** Return the id of the last inserted row. */
   lastInsertRowId: () => number;
   /**
-  * Execute a SQL statement and return the result rows.
-  * Columns can be accessed by index or by name.
-  */
+   * Execute a SQL statement and return the result rows.
+   * Columns can be accessed by index or by name.
+   */
   query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
   /** Run all statements in a transaction. */
   transaction: (function_: () => void) => void;

package/dist/packem_shared/{types.d-VfJ76cK4.d.ts → types.d-CkMkSwLJ.d.ts}

@@ -1,10 +1,11 @@
 /**
-* Abstract SQLite driver interface used by the local mirror.
-*
-* Each runtime (browser via sql.js, React Native via expo-sqlite,
-* Node via better-sqlite3) provides its own adapter implementing this
-* interface so the rest of `@lunora/replica` stays platform-agnostic.
-*/
+ * Abstract SQLite driver interface used by the local mirror.
+ *
+ * Each runtime (browser via sql.js, React Native via expo-sqlite,
+ * Node via better-sqlite3) provides its own adapter implementing this
+ * interface so the rest of `@lunora/replica` stays platform-agnostic.
+ * @experimental
+ */
 interface SqliteAdapter {
   /** Close the database connection. */
   close: () => void;
@@ -13,9 +14,9 @@ interface SqliteAdapter {
   /** Return the id of the last inserted row. */
   lastInsertRowId: () => number;
   /**
-  * Execute a SQL statement and return the result rows.
-  * Columns can be accessed by index or by name.
-  */
+   * Execute a SQL statement and return the result rows.
+   * Columns can be accessed by index or by name.
+   */
   query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
   /** Run all statements in a transaction. */
   transaction: (function_: () => void) => void;