@procedures/client 0.8.0 → 0.8.1

package/src/client/client.ts

@@ -30,6 +30,7 @@ import type {
   Method,
   Metadata,
   Message,
+  ResponseItem,
   ClientMiddleware,
   ClientContext,
   ClientRunner,
@@ -56,8 +57,19 @@ import { RouteResolver, type ResolvedRoute, type RouteResolutionResult } from ".
 import { BatchExecutor, type ExecutionContext } from "./batch-executor.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { EventBus } from "../events/types.js";
+import {
+  remoteEvents,
+  subscribeRemote,
+  type EventTransport,
+  type RemoteEvent,
+  type RemoteEventHandler,
+  type RemoteEventsOptions,
+  type SubscribeOptions,
+  type Subscription,
+} from "../events/remote.js";
 import { narrowCapability } from "../procedures/capability.js";
-import { TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { DEADLINE_METADATA_KEY, TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
+import { ms } from "../duration.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -169,6 +181,12 @@ function callerOf(options: ExecOptions): CallerContext {
   return caller;
 }
 
+/**
+ * The timeouts of a subscription: none. The timeout middleware takes 0 as "no timeout", so the
+ * timeouts of the client do not end a subscription, which has no end (roadmap CLI-15).
+ */
+const NO_SUBSCRIPTION_TIMEOUT = Object.freeze({ overall: ms(0), perAttempt: ms(0) });
+
 /**
  * Generate a unique message ID.
  */
@@ -221,6 +239,8 @@ export class Client<TContext = {}> {
   private readonly throwOnError: boolean;
   /** The bus of the local procedures. Undefined: the global bus. */
   private bus: EventBus | undefined;
+  /** The transport of the subscriptions through the middleware, made at the first subscription */
+  private subscriptionTransport: EventTransport | undefined;
   /** The interceptors of the local invocations (roadmap 1.2) */
   private interceptors: readonly Interceptor[] = [];
   /** The capability of the local invocations (CAPABILITIES-2026-10). Undefined: no limits. */
@@ -779,6 +799,68 @@ export class Client<TContext = {}> {
     }
   }
 
+  /**
+   * This method subscribes to topics of the event bus of the server (`documentation/EVENTS.md`).
+   * The call of `events.subscribe` goes through the middleware and the context of this client, as
+   * `stream()` does. Thus a token of the auth middleware goes with it. The subscriber resubscribes
+   * after a failure that a retry can repair, and the subscribers of the same topics share one call.
+   *
+   * A subscription has no deadline: the timeouts of the client (its timeout middleware, the
+   * `timeout` of its context and a `procedure-timeout` of its metadata) do not apply to it. For a
+   * deadline, give it in the metadata of the options, for example
+   * `{ metadata: { timeout: { overall: minutes(5) } } }`.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param handler - The handler of each event. A promise that it gives holds the next event.
+   * @param options - `onSubscribed`, `onError`, a signal, the metadata of the call, the resubscribe rules
+   * @returns The unsubscribe function, with the `ready` promise of the first confirmation
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.subscribe("collections.users", (event) => console.log(event));
+   * await unsubscribe.ready;
+   * unsubscribe();
+   * ```
+   */
+  subscribe<T = unknown>(topics: string | readonly string[], handler: RemoteEventHandler<T>, options: SubscribeOptions = {}): Subscription {
+    return subscribeRemote<T>(this.eventTransport(), topics, handler, options);
+  }
+
+  /**
+   * This method gives the events of topics of the event bus of the server as an async iterator,
+   * through the middleware of this client. A `break` or the signal ends the subscription. As for
+   * `subscribe()`, the timeouts of the client do not apply: the metadata of the options can give one.
+   *
+   * @param topics - One topic, or a list of 1 to 64 topics
+   * @param options - A signal, `onSubscribed`, the metadata of the call, the resubscribe rules
+   */
+  events<T = unknown>(topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
+    return remoteEvents<T>(this.eventTransport(), topics, options);
+  }
+
+  /**
+   * The transport of the subscriptions of this client: each call goes through the middleware, with
+   * the context of the client in its metadata. The subscriptions of one client share it, so they
+   * share their calls. The timeouts and the deadline of the client stay out: only the metadata of
+   * the subscription can give them.
+   */
+  private eventTransport(): EventTransport {
+    if (!this.subscriptionTransport) {
+      const send = <TReq, TRes>(message: Message<TReq>): AsyncIterable<ResponseItem<TRes>> => {
+        const metadata: Metadata = { ...this.defaultMetadata, ...(this.getEffectiveContext() as object) };
+        delete metadata["timeout"];
+        delete metadata[TIMEOUT_METADATA_KEY];
+        delete metadata[DEADLINE_METADATA_KEY];
+        metadata["timeout"] = NO_SUBSCRIPTION_TIMEOUT as unknown as NonNullable<Metadata["timeout"]>;
+        Object.assign(metadata, message.metadata);
+        absorbTimeout(metadata);
+        return this.composeMiddleware<TReq, TRes>()({ message: { ...message, metadata } });
+      };
+      this.subscriptionTransport = { send };
+    }
+    return this.subscriptionTransport;
+  }
+
   /**
    * Compose middleware chain using universal middleware composition.
    *

package/src/events/publisher.ts

@@ -8,11 +8,17 @@
  *
  * - The topic rule (`topics`) is the expose rule of the topics. A topic outside it gives
  *   `TOPIC_NOT_FOUND`.
+ * - `reads` gives the resources that a subscriber of a topic reads. The capability of the call
+ *   must permit them, as for a procedure that reads them (roadmap CLI-15). By default, a topic
+ *   `collections.<name>` reads `collection:<name>`.
  * - `allow` examines each topic with the capability of the call. A refusal gives `FORBIDDEN` with
  *   the reason `topic-not-allowed`.
  * - The procedure declares that it reads the resource `events`, so the capability of the host
  *   applies to it as to each procedure.
  *
+ * - A value with rows (`withRows()`) reaches each subscriber through the output filter of its host
+ *   (`ctx.admit`): each row passes the filter, and the subscriber gets only the admitted rows.
+ *
  * The delivery is at most once. The queue of a subscription holds at most `buffer` events. When
  * it is full, the publisher drops the oldest event, and the next event tells the number of lost
  * events (`dropped`). The bus never waits for a subscriber.
@@ -21,10 +27,13 @@
 import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { InvocationError } from "../procedures/invoke.js";
+import { capabilityRefusal } from "../procedures/capability.js";
+import { collectionTopicReads } from "../procedures/collection/changes.js";
 import type { AnyProcedure, Capability, ProcedureContext } from "../procedures/types.js";
 import type { EventBus, Unsubscribe } from "./types.js";
 import { getGlobalEventBus } from "./bus.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
+import { admittedValue, rowsOf } from "./rows.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -64,6 +73,18 @@ export interface EventPublisherOptions {
    * @default 1024
    */
   buffer?: number | undefined;
+  /**
+   * The resources that a subscriber of a topic reads (roadmap CLI-15). The publisher refuses a
+   * topic whose reads the capability of the call does not permit, as for a procedure that reads
+   * them: `FORBIDDEN` with the reason `effects-exceeded`.
+   * @default `collectionTopicReads`: a topic `collections.<name>` reads `collection:<name>`
+   */
+  reads?: ((topic: string) => readonly string[]) | undefined;
+}
+
+/** A procedure that reads resources, for the admission of a topic under a capability. */
+function topicReader(reads: readonly string[]): AnyProcedure {
+  return { path: [...EVENTS_SUBSCRIBE_PATH], metadata: { effects: { reads: [...reads], writes: [] } } } as unknown as AnyProcedure;
 }
 
 /** This function gives the test of a topic rule. */
@@ -131,7 +152,9 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   private readonly queue: Array<Extract<EventItem, { type: "event" }>> = [];
   private seq = 0;
   private dropped = 0;
-  private waiter: { resolve: (result: IteratorResult<EventItem>) => void; reject: (error: unknown) => void } | undefined;
+  private waiter:
+    | { resolve: (result: IteratorResult<EventItem> | PromiseLike<IteratorResult<EventItem>>) => void; reject: (error: unknown) => void }
+    | undefined;
   private closed = false;
   private failure: unknown;
   private readonly unsubscribes: Unsubscribe[];
@@ -142,6 +165,8 @@ 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,
   ) {
     this.confirmation = { type: "subscribed", topics };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
@@ -166,7 +191,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     const waiter = this.waiter;
     if (waiter && this.queue.length === 0) {
       this.waiter = undefined;
-      waiter.resolve({ value: this.withDropped(event), done: false });
+      waiter.resolve(this.deliver(event));
       return;
     }
     if (this.queue.length >= this.buffer) {
@@ -177,6 +202,16 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     this.queue.push(event);
   }
 
+  /**
+   * The item of an event for the subscriber. The rows of its data pass the output filter of the
+   * host for this subscriber, and the subscriber gets only the admitted rows.
+   */
+  private deliver(event: Extract<EventItem, { type: "event" }>): Promise<IteratorResult<EventItem>> {
+    const item = this.withDropped(event) as Extract<EventItem, { type: "event" }>;
+    if (!this.admit || !rowsOf(item.data)) return Promise.resolve({ value: item, done: false });
+    return admittedValue(item.data, this.admit).then((data): IteratorResult<EventItem> => ({ value: { ...item, data }, done: false }));
+  }
+
   /** The event with the number of events that the publisher dropped before it. */
   private withDropped(event: Extract<EventItem, { type: "event" }>): EventItem {
     if (this.dropped === 0) return event;
@@ -192,7 +227,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
       return Promise.resolve({ value: confirmation, done: false });
     }
     const event = this.queue.shift();
-    if (event) return Promise.resolve({ value: this.withDropped(event), done: false });
+    if (event) return this.deliver(event);
     if (this.failure !== undefined) {
       const failure = this.failure;
       this.failure = undefined;
@@ -268,6 +303,7 @@ export class EventPublisher {
   readonly procedure: AnyProcedure;
   private readonly known: (topic: string) => boolean;
   private readonly allow: EventPublisherOptions["allow"];
+  private readonly reads: (topic: string) => readonly string[];
   private readonly buffer: number;
   private readonly open = new Set<TopicSubscription>();
 
@@ -275,6 +311,7 @@ export class EventPublisher {
     this.bus = options.bus ?? getGlobalEventBus();
     this.known = topicMatcher(options.topics);
     this.allow = options.allow;
+    this.reads = options.reads ?? collectionTopicReads;
     this.buffer = Math.max(1, Math.floor(options.buffer ?? 1024));
     this.procedure = createProcedure()
       .path([...EVENTS_SUBSCRIBE_PATH])
@@ -316,6 +353,13 @@ export class EventPublisher {
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
     }
+    // A subscriber of a topic reads its resources: the capability of the call must permit them
+    for (const topic of unique) {
+      const reads = this.reads(topic);
+      if (reads.length === 0) continue;
+      const refusal = capabilityRefusal(topicReader(reads), ctx.capability);
+      if (refusal) throw new InvocationError("FORBIDDEN", `The topic "${topic}": ${refusal.message}`, ctx.path, refusal.reason);
+    }
     if (this.allow) {
       const call: TopicCall = { capability: ctx.capability, metadata: ctx.metadata };
       for (const topic of unique) {
@@ -324,7 +368,7 @@ export class EventPublisher {
         }
       }
     }
-    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed));
+    const subscription = new TopicSubscription(this.bus, unique, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }

package/src/events/rows.ts

@@ -0,0 +1,48 @@
+/**
+ * The rows of a published value (roadmap CLI-15).
+ *
+ * A value on the bus can hold rows of data: the values of a collection change event, for example.
+ * The publisher of the remote events gives each row to the output filter of the host (`admitItem`)
+ * for each subscriber, and each subscriber gets only the rows that its filter admits. Thus a row
+ * reaches a subscriber only through the same filter as a read.
+ *
+ * The rows are on a symbol key, so they stay in this process: JSON does not take them.
+ */
+
+/** The rows of a published value, and the function that makes the value of the admitted rows. */
+export interface PublishedRows {
+  /** The rows that the output filter examines, one at a time. */
+  readonly rows: readonly unknown[];
+  /** This function gives the value for a subscriber: `admitted[i]` tells if row `i` stays. */
+  keep(admitted: readonly boolean[]): unknown;
+}
+
+/** The key of the rows of a published value. */
+const ROWS: unique symbol = Symbol.for("procedures.publishedRows");
+
+/**
+ * This function gives the value with its rows, for the filter of each subscriber. The rows are not
+ * enumerable: a copy or a comparison of the value does not see them.
+ */
+export function withRows<T extends object>(value: T, rows: PublishedRows): T {
+  return Object.defineProperty(value, ROWS, { value: rows, enumerable: false });
+}
+
+/** The rows of a published value, or undefined for a value without rows. */
+export function rowsOf(value: unknown): PublishedRows | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const rows = (value as { [ROWS]?: unknown })[ROWS];
+  return typeof rows === "object" && rows !== null ? (rows as PublishedRows) : undefined;
+}
+
+/**
+ * The value of a published value for one subscriber: each row passes the filter, and the value
+ * keeps the admitted rows. An error of the filter refuses the row. Without rows or a filter, the
+ * value stays as it is.
+ */
+export async function admittedValue(value: unknown, admit: ((item: unknown) => Promise<boolean>) | undefined): Promise<unknown> {
+  const rows = rowsOf(value);
+  if (!rows || !admit) return value;
+  const admitted = await Promise.all(rows.rows.map((row) => admit(row).catch(() => false)));
+  return rows.keep(admitted);
+}

package/src/index.ts

@@ -27,7 +27,7 @@ export type {
   HttpUrlStrategy,
 } from "./server/index.js";
 export { WebSocketServerTransport } from "./server/index.js";
-export { checkBrowserRequest, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
+export { checkBrowserRequest, hasAmbientCredentials, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
 export type { BrowserGuardOptions, GuardedRequest, GuardResult } from "./server/browser-guard.js";
 export type {
   WebSocketServerTransportOptions,

package/src/node.ts

@@ -9,9 +9,30 @@
  * This entry also exports `writeNdjsonStream`: the writer of an NDJSON stream response of wire
  * protocol v1, for a `ServerResponse` of `node:http`. `HttpServerTransport` uses it, so a server
  * without Express writes the same bytes.
+ *
+ * The procedure faces of Node, without a framework (CLI-3): `procedureHandler(server, options)`
+ * gives a request handler `(req, res) => boolean`, and `upgradeHandler(server, options)` gives an
+ * upgrade handler `(req, socket, head) => boolean`. Each one takes the requests of its path and
+ * gives `false` for the others, so the routes of the application share the listener.
  */
 
 export { WebSocketTransport } from "./adapters/websocket/client/node.js";
 export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/websocket/client/types.js";
 export { writeNdjsonStream } from "./adapters/http/server/ndjson.js";
 export type { WriteNdjsonStreamOptions, NdjsonError } from "./adapters/http/server/ndjson.js";
+export { procedureHandler } from "./adapters/http/server/handler.js";
+export type { ProcedureHandlerOptions, NodeProcedureHandler, NodeUrlStrategy, UrlRequest } from "./adapters/http/server/handler.js";
+export type { CorsOptions } from "./adapters/http/server/cors.js";
+export type { RoutedRequest } from "./adapters/http/server/strategies.js";
+export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "./adapters/http/server/strategies.js";
+export { upgradeHandler } from "./adapters/websocket/server/upgrade.js";
+export type { UpgradeHandlerOptions, NodeUpgradeHandler } from "./adapters/websocket/server/upgrade.js";
+export { WebSocketServerTransport } from "./adapters/websocket/server/transport.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage,
+  TrackedConnection,
+  ConnectionEventHandler,
+} from "./adapters/websocket/server/types.js";

package/src/procedures/capability.ts

@@ -178,6 +178,27 @@ export function narrowCapability<C>(
   return Object.freeze(result) as Capability<C>;
 }
 
+/**
+ * This function joins two requests for a narrower capability into one request that asks for
+ * both: the meet of the clearances, the intersection of the effects and the shorter time. Two
+ * different clearances need an order.
+ */
+export function joinNarrowing<C>(first: CapabilityRequest<C>, second: CapabilityRequest<C>, order?: ClearanceOrder<C>): CapabilityRequest<C> {
+  const result: CapabilityRequest<C> = {};
+  if (first.clearance === undefined || second.clearance === undefined || Object.is(first.clearance, second.clearance)) {
+    const clearance = first.clearance ?? second.clearance;
+    if (clearance !== undefined) result.clearance = clearance;
+  } else {
+    if (!order) throw new Error("Two different clearances need a clearance order: give clearanceOrder to the host (hostPolicy)");
+    result.clearance = order.meet(first.clearance, second.clearance);
+  }
+  const effects = first.effects === undefined ? second.effects : narrowEffects(first.effects, second.effects);
+  if (effects !== undefined) result.effects = effects;
+  const times = [first.timeoutMs, second.timeoutMs].filter((time): time is number => typeof time === "number" && Number.isFinite(time) && time >= 0);
+  if (times.length > 0) result.timeoutMs = Math.min(...times);
+  return result;
+}
+
 // =============================================================================
 // Admission
 // =============================================================================

package/src/procedures/collection/changes.ts

@@ -0,0 +1,245 @@
+/**
+ * The change events of the collection procedures (roadmap CLI-15).
+ *
+ * Each write of a collection procedure publishes one `CollectionChangeEvent` on the bus of its
+ * context (`ctx.bus`), under the topic `collections.<name>`. A peer gets the events with
+ * `events.subscribe` (`documentation/EVENTS.md`). The delivery is at most once, so an event is a
+ * hint of a change, and a subscriber reads the changes when it misses an event.
+ *
+ * - `since` and `version` are versions of `getChangesSince()` of the storage. The events of one
+ *   storage and one topic make a chain: the `since` of an event is the `version` of the event
+ *   before it. A subscriber whose cursor is `since` applies the event without a read.
+ * - The changes of an event come from the change log of the storage, not from the input of the
+ *   write. Thus an event also has the writes that did not go through the procedures.
+ * - By default, an event has only the ids and the versions: a value reaches a caller only through
+ *   a read, with its checks. With the option `values`, an event has the values too, and each row
+ *   `{ id, value }` passes the output filter of the host for each subscriber (`withRows()`).
+ * - A subscriber of the topic must have a capability that reads `collection:<name>`, as for a
+ *   read (`collectionTopicReads()`, the default `reads` of `EventPublisher`).
+ * - An event without `since` only tells that the collection changed: the storage has no change
+ *   log, the chain starts, or the log dropped the version. The subscriber then reads the changes.
+ * - The chain starts at the version of a call of `changes` (a pull of a subscriber). While no one
+ *   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.
+ */
+
+import type { EventBus } from "../../events/types.js";
+import { withRows } from "../../events/rows.js";
+import type { StorageChanges } from "./storage.js";
+
+/**
+ * The change event of the writes of a collection, on the topic `collections.<name>` (roadmap
+ * CLI-15). The data crosses the wire as JSON.
+ */
+export interface CollectionChangeEvent {
+  /**
+   * The version of the storage before the changes. A subscriber whose cursor is this version
+   * applies the changes without a read. Without it, the event is only a hint: read the changes.
+   */
+  readonly since?: string | undefined;
+  /** The version of the storage after the changes, when the storage has a change log. */
+  readonly version?: string | undefined;
+  /** The ids of the items that changed, in the order of the last change of each id. */
+  readonly changed: readonly string[];
+  /** The ids that were deleted. */
+  readonly deleted: readonly string[];
+  /**
+   * With the option `values`: the changed items that the output filter of the subscriber admits.
+   * Without the option, the event has no values: read them with `changes`.
+   */
+  readonly values?: ReadonlyArray<{ readonly id: string; readonly value: unknown }> | undefined;
+  /** With the option `values`: the changed ids whose values the filter refused. Read them with `changes`. */
+  readonly withheld?: readonly string[] | undefined;
+  /** The origin of the writes, when one origin made all the changes of the event. */
+  readonly origin?: string | undefined;
+}
+
+/**
+ * This function gives the topic of the change events of a collection: `collections.<name>`. The
+ * partition of roadmap CLI-17 comes after the name, with the option `topic` of the procedures.
+ */
+export function collectionChangeTopic(collection: string): string {
+  return `collections.${collection}`;
+}
+
+/**
+ * This function gives the resources that a subscriber of a topic reads: `collection:<name>` for
+ * the topic `collections.<name>` and for a topic of a partition, `collections.<name>.<partition>`.
+ * Another topic gives no resource. `EventPublisher` uses it as its default `reads`.
+ */
+export function collectionTopicReads(topic: string): readonly string[] {
+  const match = /^collections\.([^.]+)(?:\.|$)/.exec(topic);
+  return match ? [`collection:${match[1]}`] : [];
+}
+
+/** The part of a storage that the change events read. */
+interface ChangeLog {
+  getChangesSince?(since?: string): Promise<StorageChanges<unknown>>;
+}
+
+/** A write that ended, and that no event told yet. */
+interface EndedWrite {
+  /** The ids of the write, or "*" for a clear. */
+  readonly ids: readonly string[] | "*";
+  readonly origin: string | undefined;
+  /** True when the chain had a version when the write started. */
+  readonly anchored: boolean;
+}
+
+/** The chain of the events of one storage and one topic. */
+interface ChangeChain {
+  /** The `version` of the last event, or of a call of `changes`: the `since` of the next event. */
+  anchor: string | undefined;
+  /** The publishes, one at a time. */
+  tail: Promise<void>;
+  /** The writes that ended since the last publish. */
+  readonly ended: EndedWrite[];
+}
+
+/** The chains of each storage, by topic. A storage that goes away takes its chains with it. */
+const CHAINS = new WeakMap<object, Map<string, ChangeChain>>();
+
+function chainOf(storage: object, topic: string): ChangeChain {
+  let topics = CHAINS.get(storage);
+  if (!topics) {
+    topics = new Map();
+    CHAINS.set(storage, topics);
+  }
+  let chain = topics.get(topic);
+  if (!chain) {
+    chain = { anchor: undefined, tail: Promise.resolve(), ended: [] };
+    topics.set(topic, chain);
+  }
+  return chain;
+}
+
+/** The origin of an event: the one origin of its writes, when the changes are only of these writes. */
+function originOf(writes: readonly EndedWrite[], changes: StorageChanges<unknown> | undefined): string | undefined {
+  const origin = writes[0]?.origin;
+  if (origin === undefined || writes.some((write) => write.origin !== origin)) return undefined;
+  if (!changes || writes.some((write) => write.ids === "*")) return origin;
+  const ids = new Set<string>();
+  for (const write of writes) for (const id of write.ids as readonly string[]) ids.add(id);
+  const own = changes.changed.every(([id]) => ids.has(id)) && changes.deleted.every((id) => ids.has(id));
+  return own ? origin : undefined;
+}
+
+/** A hint: the collection changed, and the subscriber reads the changes. */
+function hint(version: string | undefined, origin: string | undefined): CollectionChangeEvent {
+  return {
+    ...(version !== undefined && { version }),
+    changed: [],
+    deleted: [],
+    ...(origin !== undefined && { origin }),
+  };
+}
+
+/**
+ * The event of a delta with the values of the changed items. Each row `{ id, value }` passes the
+ * output filter of each subscriber, and a refused row goes from `values` to `withheld`.
+ */
+function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ readonly id: string; readonly value: unknown }>): CollectionChangeEvent {
+  return withRows(
+    { ...event, values: entries },
+    {
+      rows: entries,
+      keep: (admitted) => {
+        const withheld = entries.filter((_, index) => !admitted[index]).map(({ id }) => id);
+        return {
+          ...event,
+          values: entries.filter((_, index) => admitted[index]),
+          ...(withheld.length > 0 && { withheld }),
+        };
+      },
+    },
+  );
+}
+
+/** One publish: the event of the writes that ended since the last publish. */
+async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean): Promise<void> {
+  const writes = chain.ended.splice(0);
+  // An earlier publish told these writes
+  if (writes.length === 0) return;
+  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;
+    return;
+  }
+  const since = chain.anchor;
+  if (!storage.getChangesSince || since === undefined) {
+    bus.emit(topic, hint(undefined, originOf(writes, undefined)));
+    return;
+  }
+  let changes: StorageChanges<unknown>;
+  try {
+    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)));
+    return;
+  }
+  chain.anchor = changes.version;
+  // A full result: the log does not know the version of the chain any more
+  if (changes.full || writes.some((write) => !write.anchored)) {
+    bus.emit(topic, hint(changes.version, originOf(writes, undefined)));
+    return;
+  }
+  if (changes.changed.length === 0 && changes.deleted.length === 0) return;
+  const origin = originOf(writes, changes);
+  const event: CollectionChangeEvent = {
+    since,
+    version: changes.version,
+    changed: changes.changed.map(([id]) => id),
+    deleted: changes.deleted,
+    ...(origin !== undefined && { origin }),
+  };
+  bus.emit(topic, values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value }))) : event);
+}
+
+/**
+ * This function runs a write of a collection procedure, and then publishes the change event of
+ * the write on the bus. Without a bus or a topic, it only runs the write. A failed write
+ * publishes too, because a batch can change a part of the storage. The error of the publish
+ * never reaches the caller.
+ *
+ * @param bus - The bus of the context, or undefined
+ * @param storage - The storage of the collection: the chain of the events belongs to it
+ * @param topic - The topic of the events, or undefined for no event
+ * @param ids - The ids of the write, or "*" for a clear
+ * @param origin - The origin of the write
+ * @param write - The write
+ * @param values - True: the events carry the values, for the output filter of each subscriber
+ */
+export async function writeWithChangeEvent<R>(
+  bus: EventBus | undefined,
+  storage: object & ChangeLog,
+  topic: string | undefined,
+  ids: readonly string[] | "*",
+  origin: string | undefined,
+  write: () => Promise<R>,
+  values = false,
+): Promise<R> {
+  if (bus === undefined || topic === undefined) return write();
+  const chain = chainOf(storage, topic);
+  const started: EndedWrite = { ids, origin, anchored: chain.anchor !== undefined };
+  try {
+    return await write();
+  } finally {
+    chain.ended.push(started);
+    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values));
+    chain.tail = run.catch(() => undefined);
+    await chain.tail;
+  }
+}
+
+/**
+ * This function starts the chain of the events of a storage at the version of a call of
+ * `changes`, when the chain has no version. The subscriber that made the call then applies the
+ * next event without a read.
+ */
+export function startChangeChain(bus: EventBus | undefined, storage: object, topic: string | undefined, version: string): void {
+  if (bus === undefined || topic === undefined) return;
+  const chain = chainOf(storage, topic);
+  if (chain.anchor === undefined) chain.anchor = version;
+}