@procedures/client 0.48.0 → 0.48.1

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/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) {