@lunora/replica 1.0.0-alpha.12 → 1.0.0-alpha.121

package/dist/index.d.mts

@@ -1,9 +1,24 @@
-export { createBetterSqlite3Adapter } from "./adapters/better-sqlite3.mjs";
+export {
+/**
+ * \@lunora/replica — Event sourcing runtime + local SQLite mirror for Lunora
+ *
+ * ## Modules
+ *
+ * - **EventEmitter** — type-safe event emitter with typed + wildcard listeners.
+ * - **EventSource** — event-sourcing runtime that derives state from an
+ * append-only log via a reducer.
+ * - **SubscriptionManager** — manages state and event-type subscriptions.
+ * - **SnapshotStore** — interface + in-memory store for persisting
+ * event-sourced state snapshots.
+ * - **LocalMirror** — local SQLite mirror that applies typed table diffs.
+ * - **EventLog** — append-only log for events and catch-up replication.
+ */
+createBetterSqlite3Adapter } from "./adapters/better-sqlite3.mjs";
 export { createSqliteWasmAdapter } from "./adapters/sqlite-wasm.mjs";
 export { createSqlJsAdapter } from "./adapters/sqljs.mjs";
-import { S as SqliteAdapter } from "./packem_shared/types.d-CkMkSwLJ.mjs";
-import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
-export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
+import { S as SqliteAdapter } from "./packem_shared/types.d-BuLTPLaQ.mjs";
+import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-DzREvGNM.mjs";
+export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-DzREvGNM.mjs";
 /**
  * Apply a single {@link TableDiff} to an in-memory row map and return
  * the updated map.
@@ -39,7 +54,7 @@ declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>
 /**
  * Merge the row-level effect of a {@link TableDiff} into plain JSON
  * state keyed by table name, returning a new snapshot.
- * @param snapshot Current snapshot, e.g. `{ users: Map&lt;id, row>, posts: Map&lt;id, row> }`.
+ * @param snapshot Current snapshot, e.g. `{ users: Map<id, row>, posts: Map<id, row> }`.
  * @param diff Contains the target table name and the row-level changes to merge.
  * @returns A shallow copy of `snapshot` with `diff.table`'s map updated.
  * @experimental
@@ -90,23 +105,12 @@ type EventsDefinition<TDefinition extends Record<string, Record<string, unknown>
   /** Type-level map of event type → payload shape. Useful for generic code. */
   readonly _types: EventTypeMap<TDefinition>;
 };
-/**
- * Declare typed event types for event sourcing.
- *
- * Each key under a namespace becomes a factory function that produces
- * an {@link InputEvent} — an optimistic / command event that the event
- * log will assign a sequence number to on append.
- * @param definition A nested object where the outer keys are namespaces
- * and the inner keys are event names mapped to their
- * payload schemas (or simple type-descriptor objects).
- * @returns An object with the same nesting structure, where each leaf is
- * a factory function plus a `.type` property.
- */
+/** Options accepted by {@link defineEvents}. */
 interface DefineEventsOptions {
   /**
    * Optional version prefix for all event types.
    *
-   * When set, every qualified event type is prefixed with `"v&lt;N>."`, enabling
+   * When set, every qualified event type is prefixed with `"v<N>."`, enabling
    * versioned event naming like `"v1.chat.messageSent"` or `"v2.chat.messageSent"`.
    * This allows materializers to evolve their handling logic based on the event
    * version without breaking backward compatibility.
@@ -115,7 +119,19 @@ interface DefineEventsOptions {
   readonly version?: string;
 }
 /**
+ * Declare typed event types for event sourcing.
+ *
+ * Each key under a namespace becomes a factory function that produces
+ * an {@link InputEvent} — an optimistic / command event that the event
+ * log will assign a sequence number to on append.
+ *
  * `defineEvents` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+ * @param definition A nested object where the outer keys are namespaces
+ * and the inner keys are event names mapped to their
+ * payload schemas (or simple type-descriptor objects).
+ * @param options Optional {@link DefineEventsOptions} — currently a `version` prefix.
+ * @returns An object with the same nesting structure, where each leaf is
+ * a factory function plus a `.type` property.
  * @experimental
  */
 declare const defineEvents: <TDefinition extends Record<string, Record<string, unknown>>>(definition: TDefinition, options?: DefineEventsOptions) => EventsDefinition<TDefinition>;
@@ -179,19 +195,28 @@ declare class EventLogDOClient {
     batchId?: string;
   }): Promise<EventLogEntry[]>;
   /**
-   * Fetch all entries with `seq >= sinceSeq`.
+   * Fetch ONE page of entries with `seq >= sinceSeq`.
    *
-   * Pass `sinceSeq = 0` to fetch the entire log.
-   */
-  getSince(sinceSeq: number): Promise<EventLogEntry[]>;
-  /**
-   * Fetch a paginated range of entries.
-   * @returns `{ entries, hasMore }` — `hasMore` is `true` when another
-   * page exists (i.e. the DO returned `limit + 1` rows).
+   * The DO bounds every page (500 entries unless `limit` says otherwise, 1000
+   * max), so `getSince(0)` is the START of the log, never all of it — a
+   * catch-up walks pages until `truncated` is `false`:
+   *
+   * ```ts
+   * let seq = 0;
+   * for (;;) {
+   *   const page = await client.getSince(seq);
+   *   apply(page.entries);
+   *   if (!page.truncated || page.cursor === undefined) break;
+   *   seq = page.cursor;
+   * }
+   * ```
+   * @returns `{ entries, truncated, cursor }` — `cursor` is the `sinceSeq`
+   * for the next page and is present exactly when `truncated` is `true`.
    */
-  getRange(fromSeq: number, limit?: number): Promise<{
+  getSince(sinceSeq: number, limit?: number): Promise<{
+    cursor?: number;
     entries: EventLogEntry[];
-    hasMore: boolean;
+    truncated: boolean;
   }>;
   /**
    * Return the total number of entries currently in the log.
@@ -199,6 +224,12 @@ declare class EventLogDOClient {
   getSize(): Promise<number>;
   /**
    * Return the full log state — all entries plus the next seq number.
+   *
+   * Only for a log small enough to answer as one body: the DO refuses with a
+   * 413 past its page ceiling, since serialising an unbounded log into one
+   * response is what {@link EventLogDOClient.getSince} was bounded to avoid.
+   * A catch-up walks `getSince` instead.
+   * @throws Error when the log is too large to return in one body
    */
   getState(): Promise<{
     entries: EventLogEntry[];
@@ -272,8 +303,8 @@ type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry)
  * Events emitted by the {@link EventSource} runtime.
  *
  * A `type` (not `interface`) so it satisfies `EventEmitter`'s
- * `Record&lt;string, unknown>` constraint — interfaces have no implicit index
- * signature and aren't assignable to `Record&lt;string, unknown>`.
+ * `Record<string, unknown>` constraint — interfaces have no implicit index
+ * signature and aren't assignable to `Record<string, unknown>`.
  * @experimental
  */
 type EventSourceEvents = {
@@ -409,8 +440,10 @@ declare class EventSource<S extends Record<string, unknown> = Record<string, unk
    * 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.
+   * The generator runs indefinitely unless given a `signal` — callers
+   * should break out of the `for await` loop or pass an `AbortSignal` to
+   * stop it (an abort settles the generator, `done: true`, on its next
+   * iteration step; it does not throw).
    * @example
    * ```ts
    * for await (const entry of source.events()) {
@@ -461,9 +494,16 @@ declare class InMemorySnapshotStore implements SnapshotStore {
  *
  * Pure functions are strongly encouraged: given the same event and state,
  * they must produce the same next state for deterministic replay.
+ *
+ * Return {@link UNHANDLED} for an event `type` the reducer does not recognise —
+ * that, and only that, is what {@link MaterializerRuntimeOptions.unknownEventHandling}
+ * reacts to. Returning the current `state` is a legitimate, idempotent no-op for
+ * a type the reducer DOES handle; reference equality cannot tell the two apart
+ * (REPLICA-07), and reading it as "unhandled" warned about — or, under `"fail"`,
+ * threw on — an event type the reducer explicitly recognised.
  * @experimental
  */
-type MaterializerReducer<S> = (state: S, entry: EventLogEntry) => S;
+type MaterializerReducer<S> = (state: S, entry: EventLogEntry) => S | typeof UNHANDLED;
 /**
  * Options for defining a single materializer.
  * @experimental
@@ -472,7 +512,8 @@ interface MaterializerDef<S> {
   /**
    * Reducer invoked for every event in the log.
    *
-   * Return the current state unchanged to skip the event.
+   * Return the current state unchanged for a recognised event with nothing to
+   * do; return {@link UNHANDLED} for a `type` this reducer does not process.
    */
   handle: MaterializerReducer<S>;
   /** Factory for the initial (empty) state. */
@@ -485,8 +526,12 @@ interface MaterializerDef<S> {
  * @experimental
  */
 interface Materializer<S> {
-  /** Apply a single event entry through the reducer. */
-  apply: (entry: EventLogEntry) => void;
+  /**
+   * Apply a single event entry through the reducer.
+   * @returns `false` when the reducer returned {@link UNHANDLED} (state left
+   * untouched), `true` otherwise.
+   */
+  apply: (entry: EventLogEntry) => boolean;
   readonly def: MaterializerDef<S>;
   /** Reset to the initial state. */
   reset: () => void;
@@ -507,9 +552,9 @@ declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materia
  * A materializer of any state shape. The {@link MaterializerRuntime} holds a
  * heterogeneous collection and only ever calls `apply(entry)` / `setState(...)`
  * (with cast values) / reads `def.name` — it never needs the concrete state
- * type. `Materializer&lt;unknown>` won't do: `setState(state: S)` makes
- * `Materializer&lt;S>` invariant in `S`, so `Materializer&lt;number>` isn't assignable
- * to `Materializer&lt;unknown>`. Erasing the type param is the idiomatic fix.
+ * type. `Materializer<unknown>` won't do: `setState(state: S)` makes
+ * `Materializer<S>` invariant in `S`, so `Materializer<number>` isn't assignable
+ * to `Materializer<unknown>`. Erasing the type param is the idiomatic fix.
  */
 type AnyMaterializer = Materializer<any>;
 /**
@@ -528,7 +573,21 @@ interface MaterializerRuntimeOptions {
   /** Optional snapshot store for persisting/recovering materialized state. */
   snapshotStore?: SnapshotStore;
   /**
-   * How to handle events whose type no materializer handles.
+   * How to handle an event that every materializer explicitly DECLINED — one
+   * for which each reducer returned {@link UNHANDLED}.
+   *
+   * A reducer that instead falls through to `return state` for a type it does
+   * not recognise has, as far as the runtime can tell, handled the event: it
+   * changed nothing, but it did not decline. `"fail"` and `"warn"` are inert
+   * for such a reducer, and no option here can make them otherwise — write the
+   * reducer's default branch as `return UNHANDLED` if you want to hear about
+   * unknown types.
+   *
+   * A materializer whose own watermark is already past the entry does not run
+   * for it, and does not count as declining it: an entry that was already
+   * applied has already been classified, so a catch-up replaying it for a
+   * LAGGING materializer alone never re-reports it. Without that, `"fail"`
+   * aborted a catch-up on events a snapshot-recovered sibling had processed.
    * @default "warn"
    */
   unknownEventHandling?: UnknownEventHandling;
@@ -586,12 +645,24 @@ declare class MaterializerRuntime {
    *
    * 1. Recover materialized state from snapshots (if a snapshotStore is
    * configured).
-   * 2. Fetch all entries since the MINIMUM per-materializer watermark from
+   * 2. Fetch entries since the MINIMUM per-materializer watermark from
    * the DO — not the maximum — so a materializer with no snapshot (or a
    * lower one) still receives every event it hasn't seen (REPLICA-04).
    * 3. Apply them through the materializers; `applyEntries` skips each
    * entry for any materializer already past it, so nothing is double-applied.
    *
+   * The DO answers one BOUNDED page per request, so step 2/3 walk pages until
+   * the log is exhausted — applying each page as it arrives, rather than
+   * holding the whole backlog in memory. Taking only the first page (and
+   * dropping `truncated`) would silently leave every materializer short of
+   * the log's head whenever the backlog exceeds a page.
+   *
+   * The walk is bounded by {@link MAX_CATCHUP_PAGES}: against a log written
+   * faster than it is read, "until the log is exhausted" never arrives and
+   * startup would never finish. Hitting the budget returns what was applied
+   * with every materializer's watermark advanced, so a later `initialize()`
+   * (or the ordinary append path) picks up exactly where this left off.
+   *
    * Call this once on startup / after the DO binding is available.
    * @returns The number of entries applied during catch-up.
    */
@@ -603,7 +674,8 @@ declare class MaterializerRuntime {
    * 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`.
+   * @returns The persisted entry with its DO-assigned `seq` — always, whether
+   * or not the entry could be applied to the materializers (see below).
    */
   appendEvent(input: AppendEventInput): Promise<EventLogEntry>;
   /**
@@ -697,20 +769,15 @@ interface EventsFacade {
     type: string;
   }[]) => Promise<EventLogEntry[]>;
   /**
-   * Fetch a paginated range of entries.
-   * @returns `{ entries, hasMore }` — `hasMore` is `true` when another
-   * page exists.
+   * Fetch ONE bounded page of entries with `seq >= sinceSeq`.
+   * @returns `{ entries, truncated, cursor }` — pass `cursor` back as
+   * `sinceSeq` while `truncated` is `true` to walk the whole log.
    */
-  getRange: (fromSeq: number, limit?: number) => Promise<{
+  getSince: (sinceSeq: number, limit?: number) => Promise<{
+    cursor?: number;
     entries: EventLogEntry[];
-    hasMore: boolean;
+    truncated: boolean;
   }>;
-  /**
-   * Fetch all entries with `seq >= sinceSeq`.
-   *
-   * Pass `sinceSeq = 0` to fetch the entire log.
-   */
-  getSince: (sinceSeq: number) => Promise<EventLogEntry[]>;
   /** Return the total number of entries currently in the log. */
   getSize: () => Promise<number>;
   /** Return the full log state — all entries plus the next seq number. */
@@ -731,7 +798,7 @@ interface EventsContextOutput {
  * Create a middleware that attaches a typed `ctx.events` facade backed by
  * the given {@link EventLogDOClient}.
  *
- * The facade surfaces `append`, `getSince`, `getRange`, `getSize`, and
+ * The facade surfaces `append`, `getSince`, `getSize`, and
  * `getState` — every method the DO client exposes — so handlers can read
  * and write the event log without reaching for the DO stub directly.
  *
@@ -773,18 +840,33 @@ interface SubscriptionClient {
  * is applied to the local SQLite store.
  *
  * Each frame from a Lunora live query is the FULL current result set, so the
- * callback treats it as a snapshot: it upserts every row present and emits a
- * `delete` for any id that was mirrored on a previous frame but is absent now —
- * otherwise rows that drop out of the server result would linger stale in the
- * local mirror. Rows are keyed by their `id` field (the mirror's default primary
- * key); a row without an `id` can't be reconciled on removal, and — because the
- * mirror table's `id` column is `NOT NULL` — will fail the insert.
+ * callback diffs it against the previous frame: a row that is new or whose
+ * content changed is upserted, a row that dropped out is deleted, and an
+ * unchanged row produces nothing. A frame identical to the last one therefore
+ * applies no diff — no event-log entry, no `version` bump, no re-query for the
+ * hooks subscribed to the mirror.
+ *
+ * Rows are keyed by the table's primary key (`id` unless the table was
+ * registered with another `primaryKey`). A row without one still lands — the
+ * apply path derives a key from the ROW's own content — but it cannot be
+ * diffed: it is re-emitted on every frame, and it is never reconciled on
+ * removal because only keyed rows are recorded for the delete pass. Repeating an
+ * identical frame is therefore a no-op upsert, but each distinct content the
+ * un-keyed row ever holds leaves a row behind for the life of the mirror.
+ * **Mirror a query that selects the primary key.** An un-keyed shape (an
+ * aggregate, or a projection that drops `id`) is supported only so that one such
+ * row cannot take the rest of the frame down with it.
  *
  * The mirror table name is derived from the function ref alone (not `args`), so
  * do NOT mirror two subscriptions to the same function with different `args`
  * into the same mirror: they'd share one table and the snapshot-delete pass of
  * one could remove rows still live in the other.
  *
+ * `mirror.clearData()` resets the remembered frame. Without that reset the next
+ * identical frame diffed clean against a mirror that no longer held the rows —
+ * no changes, no `applyDiff` — and the table stayed empty until some row's
+ * content happened to change or the page reloaded.
+ *
  * Call the returned unsubscribe function to tear down both the client
  * subscription and future mirror writes.
  * @example
@@ -878,15 +960,28 @@ interface EventsSyncOptions {
    * consumer should feed these events into their state machine
    * (e.g. an {@link import("@lunora/replica").EventSource | EventSource})
    * so that the machine's state reflects the latest log position.
+   *
+   * **Must be atomic across the batch: apply every event, or none.** There is
+   * no rollback here and none is possible — the state machine is the
+   * consumer's. A call that mutates derived state and then throws partway is
+   * re-delivered WHOLE on the next poll (the watermark only advances past a
+   * batch that fully succeeded, and a replay that threw is not recorded), so a
+   * non-atomic implementation applies the events before the throw twice. A
+   * call that RETURNS is never re-delivered: {@link EventsSync} tracks the
+   * highest applied `seq` separately from the watermark, so a batch whose
+   * replay succeeded and whose mirror fan-out then failed is not replayed.
    */
   applyEvents: (events: ReadonlyArray<EventLogEntry>) => void;
   /**
-   * Fetch all events whose `seq >= sinceSeq`.
+   * Fetch the next batch of events whose `seq >= sinceSeq`.
    *
-   * In a server-side context, this typically wraps
-   * {@link import("@lunora/replica").EventLogDOClient.getSince |
-   * EventLogDOClient.getSince()}.
-   * In a client context it could call a Lunora action that proxies to the
+   * It does NOT have to return the whole backlog: a bounded batch is
+   * preferred and is what the DO-backed transport gives you
+   * ({@link import("@lunora/replica").EventLogDOClient.getSince |
+   * EventLogDOClient.getSince()} answers one page). {@link EventsSync} keeps
+   * calling with the advanced watermark until a call returns nothing, so the
+   * whole log is applied either way — one bounded atom at a time.
+   * In a client context this could call a Lunora action that proxies to the
    * event log, or read from an IndexedDB cache.
    *
    * Return an empty array when there are no new events.
@@ -896,8 +991,17 @@ interface EventsSyncOptions {
    * Produce {@link TableDiff | TableDiffs} from the current derived state.
    *
    * Called after every batch of events has been applied. The consumer
-   * compares the state _before_ and _after_ the batch and returns the
-   * diffs needed to bring the LocalMirror up to date.
+   * **recomputes a full diff from the current mirror-vs-source state** and
+   * returns the diffs needed to bring the LocalMirror up to date.
+   *
+   * **MUST be idempotent** — it must NOT advance a one-shot cursor as a side
+   * effect. A batch that fails partway (a `mirror.applyDiff` throws) is
+   * retried on the next poll from the same watermark; if this call consumed a
+   * cursor on the first attempt it would return `[]` on the retry and the
+   * un-mirrored diffs would be lost forever. Recompute-from-current-state has
+   * no such hazard: calling it again with no new events returns the same
+   * diffs, and calling it after a partial mirror write returns exactly the
+   * diffs still missing from the mirror.
    *
    * Return an empty array when there are no changes to push to the mirror.
    */