@procedures/client 0.47.2 → 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. */
@@ -226,6 +234,16 @@ function resetHint(): unknown {
  * gives the events of its queue, and then it ends with `TOPIC_CLEARED`.
  */
 class TopicSubscription implements AsyncIterableIterator<EventItem> {
+  private readonly buffer: number;
+  private readonly signal: AbortSignal | undefined;
+  private readonly onClose: (subscription: TopicSubscription) => void;
+  /** The output filter of the host for this subscriber: each row of a value passes it */
+  private readonly admit: ((item: unknown) => Promise<boolean>) | undefined;
+  /** The invocation of the subscription: the rule of the rows of a value gets it (roadmap CLI-41) */
+  private readonly invocation?: Invocation | undefined;
+  /** The row filter of each topic of a collection, by the topic of the subscriber (roadmap CLI-78) */
+  private readonly filters?: ReadonlyMap<string, RowHintFilter> | undefined;
+
   private confirmation: EventItem | undefined;
   private readonly queue: QueuedEvent[] = [];
   private seq = 0;
@@ -245,16 +263,19 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     bus: EventBus,
     /** The topics of the subscriber, each with the topic of the bus that it listens to */
     routes: ReadonlyArray<Route>,
-    private readonly buffer: number,
-    private readonly signal: AbortSignal | undefined,
-    private readonly onClose: (subscription: TopicSubscription) => void,
-    /** The output filter of the host for this subscriber: each row of a value passes it */
-    private readonly admit: ((item: unknown) => Promise<boolean>) | undefined,
-    /** The invocation of the subscription: the rule of the rows of a value gets it (roadmap CLI-41) */
-    private readonly invocation?: Invocation | undefined,
-    /** The row filter of each topic of a collection, by the topic of the subscriber (roadmap CLI-78) */
-    private readonly filters?: ReadonlyMap<string, RowHintFilter> | undefined,
+    buffer: number,
+    signal: AbortSignal | undefined,
+    onClose: (subscription: TopicSubscription) => void,
+    admit: ((item: unknown) => Promise<boolean>) | undefined,
+    invocation?: Invocation | undefined,
+    filters?: ReadonlyMap<string, RowHintFilter> | undefined,
   ) {
+    this.buffer = buffer;
+    this.signal = signal;
+    this.onClose = onClose;
+    this.admit = admit;
+    this.invocation = invocation;
+    this.filters = filters;
     this.confirmation = { type: "subscribed", topics: routes.map(({ topic }) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
     this.unsubscribes = routes.map(({ topic, busTopic }) =>
@@ -455,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[];
@@ -484,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. */
@@ -502,6 +533,7 @@ export class EventPublisher {
    */
   end(): void {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
+    this.live?.close();
   }
 
   /**
@@ -533,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/events/recheck.ts

@@ -109,6 +109,8 @@ type RecheckCheck = (cause: RecheckCause, scope?: RightsScopes) => Promise<void>
  * each new subscription to `watch()`, with the check of its admission.
  */
 export class SubscriptionRechecks {
+  private readonly clock: Clock;
+
   private readonly watches = new Set<Watch>();
   private readonly maxAgeMs: number | undefined;
   private readonly source: SubscriptionRecheck["rightsChanges"];
@@ -117,8 +119,9 @@ export class SubscriptionRechecks {
 
   constructor(
     options: SubscriptionRecheck,
-    private readonly clock: Clock,
+    clock: Clock,
   ) {
+    this.clock = clock;
     const maxAgeMs = options.maxAge === undefined ? undefined : toMs(options.maxAge, "recheck.maxAge");
     if (maxAgeMs !== undefined && !(maxAgeMs > 0)) {
       throw new TypeError(`recheck.maxAge must be more than 0 ms, got ${maxAgeMs} ms`);

package/src/events/remote.ts

@@ -168,18 +168,25 @@ export interface Subscription {
 
 /** The error that ends a subscription. */
 export class SubscriptionError extends Error {
+  /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
+  readonly code: string;
+  /** True when a resubscribe can repair the failure. */
+  readonly retryable: boolean;
+  /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
+  readonly reason?: string | undefined;
+
   override readonly name = "SubscriptionError";
 
   constructor(
-    /** The code: a code of the protocol, for example `TOPIC_NOT_FOUND`. */
-    readonly code: string,
+    code: string,
     message: string,
-    /** True when a resubscribe can repair the failure. */
-    readonly retryable: boolean,
-    /** The reason of a `FORBIDDEN` error, for example `topic-not-allowed`. */
-    readonly reason?: string | undefined,
+    retryable: boolean,
+    reason?: string | undefined,
   ) {
     super(message);
+    this.code = code;
+    this.retryable = retryable;
+    this.reason = reason;
   }
 }
 
@@ -462,6 +469,8 @@ type Entry =
  * last event that the shared subscription got before the subscriber joined.
  */
 class Subscriber {
+  readonly id: string;
+
   /** The `seq` of the wire subscription before the first event of this subscriber. */
   base = 0;
   /** The error that ends this subscriber, after the entries of its queue. */
@@ -473,7 +482,9 @@ class Subscriber {
   private waiter: ((entry: Entry | undefined) => void) | undefined;
   private ended = false;
 
-  constructor(readonly id: string) {}
+  constructor(id: string) {
+    this.id = id;
+  }
 
   /** True when the subscriber waits for an entry. */
   get waiting(): boolean {
@@ -546,6 +557,11 @@ class Subscriber {
  * when its last subscriber leaves, or with the end of the wire subscription for each subscriber.
  */
 class SharedSubscription {
+  private readonly shares: Map<string, SharedSubscription> | undefined;
+  private readonly key: string;
+  private readonly transport: EventTransport;
+  private readonly call: Omit<WireCall, "onSubscribed" | "onRetry">;
+
   private readonly members = new Set<Subscriber>();
   private readonly stop = new AbortController();
   /** The topics of the current confirmation, or undefined before it and during a resubscribe. */
@@ -557,11 +573,16 @@ class SharedSubscription {
   private finished = false;
 
   constructor(
-    private readonly shares: Map<string, SharedSubscription> | undefined,
-    private readonly key: string,
-    private readonly transport: EventTransport,
-    private readonly call: Omit<WireCall, "onSubscribed" | "onRetry">,
-  ) {}
+    shares: Map<string, SharedSubscription> | undefined,
+    key: string,
+    transport: EventTransport,
+    call: Omit<WireCall, "onSubscribed" | "onRetry">,
+  ) {
+    this.shares = shares;
+    this.key = key;
+    this.transport = transport;
+    this.call = call;
+  }
 
   /** True while a new subscriber can join. */
   get open(): boolean {

package/src/events/types.ts

@@ -273,4 +273,38 @@ export interface EventBusOptions {
    * Default: false
    */
   debug?: boolean;
+
+  /**
+   * The bounded fan-out (roadmap CLI-90). Without it, `emit()` calls each handler before it
+   * returns, at each channel size.
+   */
+  fanOut?: EventFanOutOptions;
+}
+
+/**
+ * The options of the bounded fan-out of an event bus (roadmap CLI-90).
+ *
+ * A channel with more handlers than `sliceSize` delivers after `emit()` returns, in slices. The
+ * event loop runs between two slices, so one event does not hold it. A smaller channel stays
+ * synchronous, while no event of the channel waits.
+ *
+ * The limit is a count of handlers, not a time. The work of a stream reader runs in microtasks
+ * after its handler returns, so a clock in the slice does not see this work.
+ */
+export interface EventFanOutOptions {
+  /** The most handlers that one slice calls. A number from 1 up. */
+  sliceSize: number;
+
+  /**
+   * The most events that wait for their slices. The next event then finishes the oldest events
+   * in its `emit()`: the bus loses no event, and its memory stays bounded.
+   * Default: 1024
+   */
+  maxPending?: number;
+
+  /**
+   * The function that runs a slice in a later task of the event loop.
+   * Default: `setImmediate`, or `setTimeout` where `setImmediate` does not exist
+   */
+  schedule?: (slice: () => void) => void;
 }

package/src/middleware/compose.ts

@@ -6,6 +6,7 @@
  * for any chain length - no manual overloads needed!
  */
 
+import { compose as foldLayers, type Layer } from "@mark1russell7/collections/layers";
 import type {
   Middleware,
   MiddlewareRunner,
@@ -47,12 +48,7 @@ export function wrapWithAsyncMiddlewares<
     true
   >
 ): MiddlewareRunner<TBaseContext, TReturn, true> {
-  const combinedRunner = middlewares.reduceRight(
-    (currentRunner, currentMiddleware) => {
-      return currentMiddleware(currentRunner);
-    },
-    fn
-  ) as MiddlewareRunner<TBaseContext, TReturn, true>;
+  const combinedRunner = foldLayers(...(middlewares as readonly Layer[]))(fn) as MiddlewareRunner<TBaseContext, TReturn, true>;
 
   // Wrap in async to ensure synchronous throws become rejected promises
   return async (context) => {
@@ -85,9 +81,7 @@ export function wrapWithSyncMiddlewares<
     false
   >
 ): MiddlewareRunner<TBaseContext, TReturn, false> {
-  return middlewares.reduceRight((currentRunner, currentMiddleware) => {
-    return currentMiddleware(currentRunner);
-  }, fn) as MiddlewareRunner<TBaseContext, TReturn, false>;
+  return foldLayers(...(middlewares as readonly Layer[]))(fn) as MiddlewareRunner<TBaseContext, TReturn, false>;
 }
 
 /**
@@ -115,13 +109,8 @@ export function compose<TAsync extends boolean = false>(
   const fn = args[args.length - 1];
   const middleware = args.slice(0, -1) as Middleware<any, any, any, TAsync>[];
 
-  // Compose middleware from right to left (onion model)
-  const combined = middleware.reduceRight(
-    (next, mw) => mw(next),
-    fn
-  ) as MiddlewareRunner<any, any, TAsync>;
-
-  return combined;
+  // The first middleware is the outermost one (onion model)
+  return foldLayers(...(middleware as readonly Layer[]))(fn) as MiddlewareRunner<any, any, TAsync>;
 }
 
 /**
@@ -150,10 +139,5 @@ export function compose<TAsync extends boolean = false>(
 export function bundle<TAsync extends boolean = false>(
   ...middleware: Middleware<any, any, any, TAsync>[]
 ): Middleware<any, any, any, TAsync> {
-  return (next) =>
-    middleware.reduceRight((acc, mw) => mw(acc), next) as MiddlewareRunner<
-      any,
-      any,
-      TAsync
-    >;
+  return foldLayers(...(middleware as readonly Layer[])) as Middleware<any, any, any, TAsync>;
 }

package/src/procedures/collection/hint-filter.ts

@@ -201,6 +201,13 @@ function ignore(): void {}
  * of the topic to `apply()`, one at a time, in the order of the bus.
  */
 export class RowHintFilter {
+  /** The rules of the collection from the registry of the call. */
+  private readonly lookup: () => CollectionAdmission | null | undefined;
+  /** The invocation of the topic (`collectionInvocation()`): the rules get it. */
+  readonly invocation: Invocation | undefined;
+  /** The partition of the topic: `admitsAll` gets it. */
+  private readonly partition: string | undefined;
+
   /** The rules from the registry: undefined when the registry does not know the collection. */
   private rules: CollectionAdmission | null | undefined;
   /** The result of `admitsAll` for one set of rules. */
@@ -213,13 +220,13 @@ export class RowHintFilter {
   private tail: Promise<unknown> = Promise.resolve();
 
   constructor(
-    /** The rules of the collection from the registry of the call. */
-    private readonly lookup: () => CollectionAdmission | null | undefined,
-    /** The invocation of the topic (`collectionInvocation()`): the rules get it. */
-    readonly invocation: Invocation | undefined,
-    /** The partition of the topic: `admitsAll` gets it. */
-    private readonly partition: string | undefined,
+    lookup: () => CollectionAdmission | null | undefined,
+    invocation: Invocation | undefined,
+    partition: string | undefined,
   ) {
+    this.lookup = lookup;
+    this.invocation = invocation;
+    this.partition = partition;
     this.rules = lookup();
   }
 

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

package/src/server/types.ts

@@ -388,12 +388,17 @@ export class HandlerNotFoundError extends Error {
  * before, the default was the string `"500"`).
  */
 export class ServerError extends Error {
+  public readonly code: string;
+  public readonly retryable: boolean;
+
   constructor(
     message: string,
-    public readonly code: string = "INTERNAL_ERROR",
-    public readonly retryable: boolean = false
+    code: string = "INTERNAL_ERROR",
+    retryable: boolean = false
   ) {
     super(message);
+    this.code = code;
+    this.retryable = retryable;
     this.name = "ServerError";
   }
 }