@procedures/client 0.48.0 → 0.48.2

package/src/events/live-view.ts

@@ -0,0 +1,134 @@
+/**
+ * The reader of a live topic (documentation/LIVE-STATE-2026-11.md).
+ *
+ * The view subscribes first and reads the snapshot second. It applies the snapshot, then the events
+ * that came during the read, in their order. So no number is necessary: each set publishes an
+ * event, and the last event of a key decides. After a lost connection and after a loss of events,
+ * the view reads the snapshot again and replaces its values.
+ */
+import { pathToMethod } from "../server/method.js";
+import type { Method } from "../client/types.js";
+import { LIVE_SNAPSHOT_PATH, type LiveEntry, type LiveEvent } from "./live-state.js";
+import type { RemoteEventHandler, SubscribeOptions, Subscription } from "./remote.js";
+
+/** The parts of a client that a view uses. A `Client` has them. */
+export interface LiveClient {
+  /** This method starts a subscription. */
+  subscribe<T = unknown>(topics: string | readonly string[], handler: RemoteEventHandler<T>, options?: SubscribeOptions): Subscription;
+  /** This method calls a procedure. */
+  call<TReq, TRes>(method: Method, payload: TReq): Promise<TRes>;
+}
+
+/** The options of a view. */
+export interface LiveViewOptions<T = unknown> extends SubscribeOptions {
+  /** This function gets the values after each change. */
+  onChange?: ((values: ReadonlyMap<string, LiveEntry<T>>) => void) | undefined;
+  /** This function gets the error of a read of the snapshot. The view keeps its values and its subscription. */
+  onReadError?: ((error: unknown) => void) | undefined;
+}
+
+/** The live values of a topic for one reader. */
+export interface LiveView<T = unknown> {
+  /** The live values by key. */
+  readonly values: ReadonlyMap<string, LiveEntry<T>>;
+  /** This promise resolves after the first snapshot. It rejects when the first subscription or read fails. */
+  readonly ready: Promise<void>;
+  /** This method ends the subscription. A second call does nothing. */
+  close(): void;
+}
+
+/**
+ * This function gives a view of a live topic.
+ *
+ * @example
+ * ```typescript
+ * const view = liveView(client, liveTopic("presence", "board-1"), { onChange: render });
+ * await view.ready;
+ * view.close();
+ * ```
+ */
+export function liveView<T = unknown>(client: LiveClient, topic: string, options: LiveViewOptions<T> = {}): LiveView<T> {
+  const { onChange, onReadError, ...subscribeOptions } = options;
+  const values = new Map<string, LiveEntry<T>>();
+  /** This field holds the events that come during a read of the snapshot. It is undefined when no read runs. */
+  let held: Array<LiveEvent<T>> | undefined;
+  let reads = 0;
+  let closed = false;
+  let settled = false;
+  let resolveReady: () => void = () => undefined;
+  let rejectReady: (error: unknown) => void = () => undefined;
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  // A view that nobody awaits does not give an unhandled rejection
+  ready.catch(() => undefined);
+
+  const apply = (event: LiveEvent<T>): void => {
+    for (const { key } of event.gone) values.delete(key);
+    for (const entry of event.set) values.set(entry.key, entry);
+  };
+  const applyHeld = (): void => {
+    for (const event of held ?? []) apply(event);
+    held = undefined;
+  };
+
+  const read = async (): Promise<void> => {
+    const number = ++reads;
+    held = [];
+    try {
+      const { entries } = await client.call<{ topic: string }, { entries: Array<LiveEntry<T>> }>(pathToMethod([...LIVE_SNAPSHOT_PATH]), { topic });
+      if (closed || number !== reads) return;
+      values.clear();
+      for (const entry of entries) values.set(entry.key, entry);
+      applyHeld();
+      settled = true;
+      resolveReady();
+      onChange?.(values);
+    } catch (error) {
+      if (closed || number !== reads) return;
+      applyHeld();
+      if (!settled) {
+        settled = true;
+        rejectReady(error);
+      }
+      onReadError?.(error);
+    }
+  };
+
+  const unsubscribe = client.subscribe<LiveEvent<T>>(
+    topic,
+    (event, meta) => {
+      if (closed) return;
+      // A loss of events: only a new read gives the keys back
+      if (meta.dropped > 0) void read();
+      if (held) {
+        held.push(event);
+        return;
+      }
+      apply(event);
+      onChange?.(values);
+    },
+    {
+      ...subscribeOptions,
+      onSubscribed: (topics) => {
+        subscribeOptions.onSubscribed?.(topics);
+        if (!closed) void read();
+      },
+    },
+  );
+  unsubscribe.ready.catch((error: unknown) => {
+    if (settled) return;
+    settled = true;
+    rejectReady(error);
+  });
+
+  return {
+    values,
+    ready,
+    close: () => {
+      closed = true;
+      unsubscribe();
+    },
+  };
+}

package/src/events/publisher.ts

@@ -42,6 +42,7 @@ import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/t
 import type { Principal } from "../server/types.js";
 import type { EventBus, Unsubscribe } from "./types.js";
 import { getGlobalEventBus } from "./bus.js";
+import { LiveState, type LiveStateOptions } from "./live-state.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
 import { admittedValue, rowsOf } from "./rows.js";
 import { realClock, type Clock } from "../clock.js";
@@ -117,6 +118,13 @@ export interface EventPublisherOptions {
    * @default no check after the start, other than at a call of `rightsChanged()`
    */
   recheck?: SubscriptionRecheck | undefined;
+  /**
+   * The live state of the host (LIVE-STATE-2026-11.md): keyed values in memory on the topics
+   * `live.<name>` and `live.<name>.<partition>`. The topic rule must name these topics. A server
+   * registers `live.set` and `live.snapshot`, and its expose rule applies to them.
+   * @default no live state
+   */
+  live?: LiveStateOptions | undefined;
 }
 
 /** A procedure that reads resources, for the admission of a topic under a capability. */
@@ -468,6 +476,8 @@ export class EventPublisher {
   readonly bus: EventBus;
   /** The procedure `events.subscribe` of this publisher. A host pins it, outside its registry. */
   readonly procedure: AnyProcedure;
+  /** The live state, from the option `live`, or undefined. */
+  readonly live: LiveState | undefined;
   private readonly known: (topic: string) => boolean;
   private readonly allow: EventPublisherOptions["allow"];
   private readonly reads: (topic: string) => readonly string[];
@@ -497,6 +507,14 @@ export class EventPublisher {
       })
       .handler((async (input: SubscribeInput, ctx: ProcedureContext) => this.subscribe(input.topics, ctx)) as never)
       .build();
+    this.live = options.live
+      ? new LiveState(options.live, {
+          bus: this.bus,
+          clock: options.clock,
+          topicSchema,
+          admit: (topic, ctx) => this.admitTopic(topic, ctx),
+        })
+      : undefined;
   }
 
   /** This function publishes an event on the bus: each subscription of the topic gets it. */
@@ -515,6 +533,7 @@ export class EventPublisher {
    */
   end(): void {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
+    this.live?.close();
   }
 
   /**
@@ -546,11 +565,22 @@ export class EventPublisher {
    */
   private async route(topic: string, ctx: ProcedureContext): Promise<Route> {
     const target = collectionTopicTarget(topic, ctx.repository);
-    if (!target) return { topic, busTopic: topic };
+    if (!target) return { topic, busTopic: (await this.live?.route(topic, ctx)) ?? topic };
     const partition = await partitionOfCall(ctx, target.collection, target.partition);
     return { topic, busTopic: collectionChangeTopic(target.collection, partition), collection: target.collection, partition, requested: target.partition };
   }
 
+  /**
+   * This method runs the checks of a subscription on one topic: the topic rule, the reads, `allow`
+   * and the partition. A live set and a snapshot pass the same checks as a subscriber.
+   *
+   * @returns The topic of the bus
+   */
+  async admitTopic(topic: string, ctx: ProcedureContext): Promise<string> {
+    this.admitTopics([topic], ctx);
+    return (await this.route(topic, ctx)).busTopic;
+  }
+
   /**
    * The resources that a subscriber of a topic reads. The default (`collectionTopicReads`) reads
    * the collection of the topic with the rule of the listener (`collectionTopicTarget`) and the

package/src/procedures/collection/admission.ts

@@ -265,9 +265,10 @@ export function admittedStorage<T>(storage: CollectionStorage<T>, admission: Col
   /** The full answer of `changes`: each admitted row, at a version that the rows include. */
   const fullAnswer = async (): Promise<StorageChanges<T>> => {
     const all = await storage.getChangesSince!(undefined);
-    if (all.full) return { version: all.version, full: true, changed: await admitted(all.changed), deleted: [] };
+    const held = all.held ? { held: true } : {};
+    if (all.full) return { version: all.version, full: true, changed: await admitted(all.changed), deleted: [], ...held };
     // A log that does not give all rows: the rows, read after the version, include that version
-    return { version: all.version, full: true, changed: await entries(), deleted: [] };
+    return { version: all.version, full: true, changed: await entries(), deleted: [], ...held };
   };
 
   const view: CollectionStorage<T> = {

package/src/procedures/collection/changes.ts

@@ -22,6 +22,16 @@
  *   listens to the topic, the procedures publish nothing, and the chain stops.
  * - The publishes of one storage and one topic run one at a time, in the order of the writes. A
  *   write resolves after its event is on the bus. A failed publish never fails the write.
+ * - The writes that end while a publish runs share the next publish, so one read of the change
+ *   log replies to all of them. At most one publish runs, and at most one publish waits.
+ * - A version can stop below a write in flight (`StorageChanges.held`, roadmap CLI-102). The chain
+ *   then reads the log again, after a wait that starts at 100 ms and doubles up to 5 s. It stops when
+ *   no write holds the version or no one listens. Thus a write that a write in flight holds back
+ *   reaches the subscribers with no later write. The event of such a read has no origin. It has
+ *   no rows before the changes, so a row filter makes a hint without ids.
+ * - The log can give a write two times (`StorageChanges`), so a subscriber applies a change by its id.
+ * - A read with no change sends no event, and the chain keeps its version. The version of a log can
+ *   move with no change, when another process writes a row again at a later number.
  * - With the rule `admission.admit`, the publisher filters the ids of each event for each
  *   subscriber (roadmap CLI-78, `hint-filter.ts`). The event carries the rows after the changes,
  *   from the change log. While a subscriber has a filter, each write first reads the rows before
@@ -103,6 +113,11 @@ interface ChangeLog {
   getBatch?(ids: string[]): Promise<Map<string, unknown>>;
 }
 
+/** The first wait before a read again of a log that a write in flight holds back. */
+const HELD_FIRST_MS = 100;
+/** The longest wait before a read again. */
+const HELD_MOST_MS = 5000;
+
 /** A write that ended, and that no event told yet. */
 interface EndedWrite {
   /** The ids of the write, or "*" for a clear. */
@@ -120,8 +135,30 @@ interface ChangeChain {
   anchor: string | undefined;
   /** The publishes, one at a time. */
   tail: Promise<void>;
+  /** The publish that did not start. A write that ends joins it, because it reads the writes that ended before its start. */
+  next: Promise<void> | undefined;
   /** The writes that ended since the last publish. */
   readonly ended: EndedWrite[];
+  /** True when the next publish reads the log with no write that ended. */
+  owed: boolean;
+  /** The last wait before a read again, or 0 when no write in flight holds the log back. */
+  heldWaitMs: number;
+  /** The timer of the next read again. */
+  heldTimer: ReturnType<typeof setTimeout> | undefined;
+}
+
+/** This function gives the publish that did not start, and it makes one when none waits. A failed publish rejects nothing here. */
+function nextPublish(chain: ChangeChain, start: () => Promise<void>): Promise<void> {
+  if (chain.next) return chain.next;
+  const next = chain.tail
+    .then(() => {
+      chain.next = undefined;
+      return start();
+    })
+    .catch(() => undefined);
+  chain.next = next;
+  chain.tail = next;
+  return next;
 }
 
 /** The chains of each storage, by topic. A storage that goes away takes its chains with it. */
@@ -135,7 +172,7 @@ function chainOf(storage: object, topic: string): ChangeChain {
   }
   let chain = topics.get(topic);
   if (!chain) {
-    chain = { anchor: undefined, tail: Promise.resolve(), ended: [] };
+    chain = { anchor: undefined, tail: Promise.resolve(), next: undefined, ended: [], owed: false, heldWaitMs: 0, heldTimer: undefined };
     topics.set(topic, chain);
   }
   return chain;
@@ -187,20 +224,41 @@ function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ reado
   );
 }
 
-/** One publish: the event of the writes that ended since the last publish. */
+/** This function starts the timer of the next read again while a write holds the log back, and it stops the timer otherwise. */
+function whileHeld(chain: ChangeChain, held: boolean, read: () => void): void {
+  if (!held) {
+    chain.heldWaitMs = 0;
+    if (chain.heldTimer !== undefined) clearTimeout(chain.heldTimer);
+    chain.heldTimer = undefined;
+    return;
+  }
+  if (chain.heldTimer !== undefined) return;
+  chain.heldWaitMs = Math.min(HELD_MOST_MS, chain.heldWaitMs * 2 || HELD_FIRST_MS);
+  chain.heldTimer = setTimeout(() => {
+    chain.heldTimer = undefined;
+    read();
+  }, chain.heldWaitMs);
+  chain.heldTimer.unref?.();
+}
+
+/** One publish: the event of the writes that ended since the last publish, and of a read again. */
 async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admission: CollectionAdmission | undefined): Promise<void> {
   const admit = admission?.admit;
   const writes = chain.ended.splice(0);
+  const owed = chain.owed;
+  chain.owed = false;
   // An earlier publish told these writes
-  if (writes.length === 0) return;
+  if (writes.length === 0 && !owed) return;
+  const readAgain = (): void => rereadChain(chain, storage, bus, topic, values, admission);
   if (!bus.hasSubscribers(topic)) {
     // No one listens: the procedures do not read the log. The next call of `changes` starts the chain again.
     chain.anchor = undefined;
+    whileHeld(chain, false, readAgain);
     return;
   }
   const since = chain.anchor;
   if (!storage.getChangesSince || since === undefined) {
-    bus.emit(topic, hint(undefined, originOf(writes, undefined)));
+    if (writes.length > 0) bus.emit(topic, hint(undefined, originOf(writes, undefined)));
     return;
   }
   let changes: StorageChanges<unknown>;
@@ -208,16 +266,21 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
     changes = await storage.getChangesSince(since);
   } catch {
     // The subscribers read the changes themselves. The chain keeps its version.
-    bus.emit(topic, hint(undefined, originOf(writes, undefined)));
+    if (writes.length > 0) bus.emit(topic, hint(undefined, originOf(writes, undefined)));
+    // A read again that failed told no subscriber, so it stays owed
+    else whileHeld(chain, true, readAgain);
     return;
   }
-  chain.anchor = changes.version;
+  whileHeld(chain, changes.held === true, readAgain);
   // A full result: the log does not know the version of the chain any more
   if (changes.full || writes.some((write) => !write.anchored)) {
+    chain.anchor = changes.version;
     bus.emit(topic, hint(changes.version, originOf(writes, undefined)));
     return;
   }
+  // No event tells this version, so the chain stays at the version of the last event. The next read from it gets each change.
   if (changes.changed.length === 0 && changes.deleted.length === 0) return;
+  chain.anchor = changes.version;
   const origin = originOf(writes, changes);
   const event: CollectionChangeEvent = {
     since,
@@ -231,6 +294,12 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
   bus.emit(topic, admit ? withHintImages(out, { after: afterOf(changes), before: beforeOf(writes), admission: admission! }) : out);
 }
 
+/** This function reads the log of a chain again. A publish that did not start does this read. */
+function rereadChain(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admission: CollectionAdmission | undefined): void {
+  chain.owed = true;
+  void nextPublish(chain, () => publish(chain, storage, bus, topic, values, admission));
+}
+
 /** The rows after the changes, from the change log: a changed id has its item, a deleted id has none. */
 function afterOf(changes: StorageChanges<unknown>): Map<string, HintRowState> {
   const after = new Map<string, HintRowState>();
@@ -295,9 +364,7 @@ export async function writeWithChangeEvent<R>(
     return await write();
   } finally {
     chain.ended.push(started);
-    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admission));
-    chain.tail = run.catch(() => undefined);
-    await chain.tail;
+    await nextPublish(chain, () => publish(chain, storage, bus, topic, values, admission));
   }
 }
 
@@ -311,3 +378,14 @@ export function startChangeChain(bus: EventBus | undefined, storage: object, top
   const chain = chainOf(storage, topic);
   if (chain.anchor === undefined) chain.anchor = version;
 }
+
+/**
+ * This function makes the chain read the log again when a call of `changes` gets a version that a
+ * write in flight holds back. A write outside the procedures then reaches the subscribers too.
+ * With no bus, no topic or no subscriber, it does nothing.
+ */
+export function rereadWhileHeld(bus: EventBus | undefined, storage: object & ChangeLog, topic: string | undefined, values = false, admission?: CollectionAdmission): void {
+  if (bus === undefined || topic === undefined || !bus.hasSubscribers(topic)) return;
+  const chain = chainOf(storage, topic);
+  whileHeld(chain, true, () => rereadChain(chain, storage, bus, topic, values, admission));
+}

package/src/procedures/collection/procedures.ts

@@ -58,7 +58,7 @@ import {
 } from "./schemas.js";
 import { DEFAULT_FIND_LIMIT, queryEntries, type StorageQueryOptions, type StorageQueryPolicy } from "./query.js";
 import type { CollectionStorage, StorageBatchWriteOptions, StorageItemWriteOptions, StorageWriteOptions } from "./storage.js";
-import { collectionChangeTopic, startChangeChain, writeWithChangeEvent } from "./changes.js";
+import { collectionChangeTopic, rereadWhileHeld, startChangeChain, writeWithChangeEvent } from "./changes.js";
 import { partitionOfCall, storageOfCall, withPartition, type PartitionInput } from "./partition.js";
 import { admitsRow, admittedStorage, checkAdmission, type CollectionAdmission } from "./admission.js";
 import { patchItem } from "./patch-in-parts.js";
@@ -339,7 +339,12 @@ export function createCollectionProcedures(collectionName: string, options: Coll
           const changes = await view.getChangesSince(input.since);
           // The chain of the change events starts at this version: the caller then applies the
           // next event without a read (roadmap CLI-15)
-          if (topicRule) startChangeChain(ctx.bus, storage, topicOf(ctx, partition), changes.version);
+          if (topicRule) {
+            const topic = topicOf(ctx, partition);
+            startChangeChain(ctx.bus, storage, topic, changes.version);
+            // A write in flight holds this read back, so the chain reads again until the write ends (roadmap CLI-102)
+            if (changes.held) rereadWhileHeld(ctx.bus, storage, topic, withValues, admission);
+          }
           return {
             version: changes.version,
             full: changes.full,

package/src/procedures/collection/storage.ts

@@ -185,6 +185,11 @@ export type StorageObserver<T> = (changes: StorageChangeBatch<T>) => void;
  *   has the ids that were deleted after it.
  * - The order of a full result is the order of the entries. The order of a delta is the order of
  *   the last change of each id.
+ * - A result gives each write at least one time. A write can come again in two cases, with the same
+ *   value or a later value. A full result takes its version before it lists the items, so it can
+ *   hold a write above that version, and the next delta gives the write again. A write that ends
+ *   after its lease can come again in a later delta, with a new version. A consumer applies a change
+ *   by its id, and does not count changes.
  */
 export interface StorageChanges<T> {
   /** The version of the storage that includes these changes. */
@@ -195,6 +200,11 @@ export interface StorageChanges<T> {
   changed: Array<[string, T]>;
   /** The ids that were deleted. Empty when `full` is true. */
   deleted: string[];
+  /**
+   * True when this version stops below a write in flight. A later read can give more changes, with no
+   * new write.
+   */
+  held?: boolean;
 }
 
 /** The metadata that a storage gives about itself. */

package/src/server/procedure-server.ts

@@ -516,6 +516,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     const events = options.events;
     this.publisher = events instanceof EventPublisher ? events : events ? new EventPublisher({ ...events, clock: events.clock ?? this.clock }) : undefined;
     if (this.publisher) this.registerProcedure(this.publisher.procedure, { alwaysOn: true });
+    // The live state is a choice of the host, so its expose rule applies to these procedures
+    for (const procedure of this.publisher?.live?.procedures ?? []) this.registerProcedure(procedure);
 
     // Configure collections
     if (options.collections) {