@procedures/client 0.7.0 → 0.8.0

package/src/events/bus.ts

@@ -11,8 +11,11 @@ import type {
   EventHandler,
   Unsubscribe,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
 } from "./types.js";
+import { realClock, type Clock } from "../clock.js";
+import { toMs, type Duration } from "../duration.js";
 
 /** The error of a wait that its signal ended. */
 function abortedError(channel: string): Error {
@@ -21,6 +24,16 @@ function abortedError(channel: string): Error {
   return error;
 }
 
+/**
+ * The error of a wait that `clear()` ended. Its name is `AbortError`, so code that ignores a
+ * cancelled wait ignores this one too.
+ */
+function clearedError(channel: string): Error {
+  const error = new Error(`The wait on channel "${channel}" ended, because clear() removed the channel`);
+  error.name = "AbortError";
+  return error;
+}
+
 // =============================================================================
 // Event Bus Implementation
 // =============================================================================
@@ -32,8 +45,11 @@ function abortedError(channel: string): Error {
 export class DefaultEventBus implements EventBus {
   private readonly subscribers = new Map<string, Set<EventHandler<unknown>>>();
   private readonly buffer = new Map<string, unknown[]>();
-  /** For each channel, a function per open stream that ends it (for `clear()`). */
-  private readonly streamEnders = new Map<string, Set<() => void>>();
+  /**
+   * For each channel, the functions that `clear()` runs: the `onClear` of each handler of `on()`
+   * that has one. Each open stream has one too, so `clear()` ends it.
+   */
+  private readonly clearHandlers = new Map<string, Set<() => void>>();
   private readonly options: Required<EventBusOptions>;
 
   constructor(options: EventBusOptions = {}) {
@@ -85,9 +101,10 @@ export class DefaultEventBus implements EventBus {
   }
 
   /**
-   * Subscribe to events on a channel.
+   * Subscribe to events on a channel. The `onClear` of the options runs one time when `clear()`
+   * or `clearAll()` removes the handler, not at an unsubscribe.
    */
-  on<T>(channel: string, handler: EventHandler<T>): Unsubscribe {
+  on<T>(channel: string, handler: EventHandler<T>, options: EventListenOptions = {}): Unsubscribe {
     if (this.options.debug) {
       console.log(`[EventBus] subscribe "${channel}"`);
     }
@@ -100,6 +117,30 @@ export class DefaultEventBus implements EventBus {
 
     channelSubs.add(handler as EventHandler<unknown>);
 
+    // The unsubscribe function works once, and removes only the set it added to. (Before, a
+    // repeated call of an old unsubscribe removed the set of a newer subscriber: deep dive CORE-15.)
+    // A clear() also ends the handler: then its unsubscribe does nothing.
+    let subscribed = true;
+    const { onClear } = options;
+    let cleared: (() => void) | undefined;
+    if (onClear) {
+      cleared = () => {
+        if (!subscribed) return;
+        subscribed = false;
+        try {
+          onClear();
+        } catch (error) {
+          this.options.onError(error instanceof Error ? error : new Error(String(error)), channel);
+        }
+      };
+      let handlers = this.clearHandlers.get(channel);
+      if (!handlers) {
+        handlers = new Set();
+        this.clearHandlers.set(channel, handlers);
+      }
+      handlers.add(cleared);
+    }
+
     // Replay buffered events if any
     const buffered = this.buffer.get(channel);
     if (buffered && buffered.length > 0) {
@@ -115,9 +156,6 @@ export class DefaultEventBus implements EventBus {
       }
     }
 
-    // The unsubscribe function works once, and removes only the set it added to. (Before, a
-    // repeated call of an old unsubscribe removed the set of a newer subscriber: deep dive CORE-15.)
-    let subscribed = true;
     return () => {
       if (!subscribed) return;
       subscribed = false;
@@ -130,9 +168,23 @@ export class DefaultEventBus implements EventBus {
       if (channelSubs.size === 0 && this.subscribers.get(channel) === channelSubs) {
         this.subscribers.delete(channel);
       }
+      if (cleared) {
+        const handlers = this.clearHandlers.get(channel);
+        if (handlers?.delete(cleared) && handlers.size === 0) this.clearHandlers.delete(channel);
+      }
     };
   }
 
+  /** This function runs the clear handlers of the channels, after it removed them from the bus. */
+  private runClearHandlers(channels: readonly string[]): void {
+    const handlers: Array<() => void> = [];
+    for (const channel of channels) {
+      handlers.push(...(this.clearHandlers.get(channel) ?? []));
+      this.clearHandlers.delete(channel);
+    }
+    for (const cleared of handlers) cleared();
+  }
+
   /**
    * Subscribe to a single event on a channel. On a buffered channel, the first buffered event
    * resolves the promise. When the signal aborts first, the promise rejects with an `AbortError`.
@@ -153,14 +205,26 @@ export class DefaultEventBus implements EventBus {
         reject(abortedError(channel));
       };
       // on() can replay a buffered event before it returns: the handler must not need
-      // `unsubscribe` yet (before, it threw a ReferenceError, and the promise never settled)
-      unsubscribe = this.on<T>(channel, (data) => {
-        if (settled) return;
-        settled = true;
-        unsubscribe?.();
-        signal?.removeEventListener("abort", onAbort);
-        resolve(data);
-      });
+      // `unsubscribe` yet (before, it threw a ReferenceError, and the promise never settled).
+      // clear() rejects the wait: before, the promise never settled.
+      unsubscribe = this.on<T>(
+        channel,
+        (data) => {
+          if (settled) return;
+          settled = true;
+          unsubscribe?.();
+          signal?.removeEventListener("abort", onAbort);
+          resolve(data);
+        },
+        {
+          onClear: () => {
+            if (settled) return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            reject(clearedError(channel));
+          },
+        },
+      );
       if (settled) {
         unsubscribe();
         return;
@@ -182,23 +246,7 @@ export class DefaultEventBus implements EventBus {
         const queue: T[] = [];
         let resolve: ((value: IteratorResult<T>) => void) | null = null;
         let done = signal?.aborted ?? false;
-
-        // Subscribe to channel
-        const unsubscribe = done
-          ? () => {}
-          : self.on<T>(channel, (data) => {
-              if (done) return;
-
-              if (resolve) {
-                // Someone is waiting, resolve immediately
-                const r = resolve;
-                resolve = null;
-                r({ value: data, done: false });
-              } else {
-                // Queue for later
-                queue.push(data);
-              }
-            });
+        let unsubscribe: Unsubscribe = () => {};
 
         // End the stream: no more events, and a waiting reader gets `done`
         const end = (): void => {
@@ -206,19 +254,31 @@ export class DefaultEventBus implements EventBus {
           done = true;
           unsubscribe();
           signal?.removeEventListener("abort", end);
-          self.streamEnders.get(channel)?.delete(end);
           const r = resolve;
           resolve = null;
           r?.({ value: undefined, done: true });
         };
+
+        // Subscribe to channel. A clear() of the channel ends the stream.
         if (!done) {
+          unsubscribe = self.on<T>(
+            channel,
+            (data) => {
+              if (done) return;
+
+              if (resolve) {
+                // Someone is waiting, resolve immediately
+                const r = resolve;
+                resolve = null;
+                r({ value: data, done: false });
+              } else {
+                // Queue for later
+                queue.push(data);
+              }
+            },
+            { onClear: end },
+          );
           signal?.addEventListener("abort", end, { once: true });
-          let enders = self.streamEnders.get(channel);
-          if (!enders) {
-            enders = new Set();
-            self.streamEnders.set(channel, enders);
-          }
-          enders.add(end);
         }
 
         return {
@@ -276,7 +336,8 @@ export class DefaultEventBus implements EventBus {
   }
 
   /**
-   * Remove all subscribers from a channel.
+   * Remove all subscribers from a channel. The `onClear` of each removed handler runs, and each
+   * stream of the channel ends.
    */
   clear(channel: string): void {
     if (this.options.debug) {
@@ -284,13 +345,14 @@ export class DefaultEventBus implements EventBus {
     }
     this.subscribers.delete(channel);
     this.buffer.delete(channel);
-    // The streams of the channel end: before, their readers waited forever (deep dive CORE-15)
-    for (const end of [...(this.streamEnders.get(channel) ?? [])]) end();
-    this.streamEnders.delete(channel);
+    // The streams of the channel end: before, their readers waited forever (deep dive CORE-15).
+    // The remote subscriptions end with notice too (EVENTS.md).
+    this.runClearHandlers([channel]);
   }
 
   /**
-   * Remove all subscribers from all channels.
+   * Remove all subscribers from all channels. The `onClear` of each removed handler runs, and
+   * each stream ends.
    */
   clearAll(): void {
     if (this.options.debug) {
@@ -298,10 +360,7 @@ export class DefaultEventBus implements EventBus {
     }
     this.subscribers.clear();
     this.buffer.clear();
-    for (const enders of [...this.streamEnders.values()]) {
-      for (const end of [...enders]) end();
-    }
-    this.streamEnders.clear();
+    this.runClearHandlers([...this.clearHandlers.keys()]);
   }
 }
 
@@ -398,7 +457,7 @@ export function withEventBusSignal(bus: EventBus, signal: AbortSignal): EventBus
   const waitOptions = (options?: EventWaitOptions): EventWaitOptions => ({ signal: options?.signal ?? signal });
   return {
     emit: (channel, data) => bus.emit(channel, data),
-    on: (channel, handler) => bus.on(channel, handler),
+    on: (channel, handler, options) => bus.on(channel, handler, options),
     once: (channel, options) => bus.once(channel, waitOptions(options)),
     stream: (channel, options) => bus.stream(channel, waitOptions(options)),
     subscriberCount: (channel) => bus.subscriberCount(channel),
@@ -435,8 +494,8 @@ export function createChannelPrefix(bus: EventBus, prefix: string) {
       bus.emit(prefixed(channel), data);
     },
 
-    on<T>(channel: string, handler: EventHandler<T>): Unsubscribe {
-      return bus.on(prefixed(channel), handler);
+    on<T>(channel: string, handler: EventHandler<T>, options?: EventListenOptions): Unsubscribe {
+      return bus.on(prefixed(channel), handler, options);
     },
 
     once<T>(channel: string, options?: EventWaitOptions): Promise<T> {
@@ -525,68 +584,77 @@ export function mapChannel<TIn, TOut>(
   });
 }
 
+/** Options of `debounceChannel()` and `throttleChannel()`. */
+export interface ChannelTimingOptions {
+  /** The clock of the timers. The default is the clock of the platform. A test gives a fake clock. */
+  clock?: Clock;
+}
+
 /**
- * Debounce events on a channel.
+ * This function sends the last event of `source` to `target` after `delay` without a new event
+ * (a debounce). The delay is a `Duration`, such as `ms(300)`. A plain number throws a `TypeError`.
  *
  * @param bus - Event bus
  * @param source - Source channel
  * @param target - Target channel
- * @param delay - Debounce delay in milliseconds
+ * @param delay - The time without an event before the send
  * @returns Unsubscribe function
  */
 export function debounceChannel<T>(
   bus: EventBus,
   source: string,
   target: string,
-  delay: number
+  delay: Duration,
+  options: ChannelTimingOptions = {},
 ): Unsubscribe {
-  let timer: ReturnType<typeof setTimeout> | null = null;
+  const delayMs = toMs(delay, "debounceChannel delay");
+  const clock = options.clock ?? realClock;
+  let cancel: (() => void) | null = null;
   let lastData: T | undefined;
 
   const unsub = bus.on<T>(source, (data) => {
     lastData = data;
-
-    if (timer) {
-      clearTimeout(timer);
-    }
-
-    timer = setTimeout(() => {
+    cancel?.();
+    cancel = clock.after(delayMs, () => {
+      cancel = null;
       if (lastData !== undefined) {
         bus.emit(target, lastData);
       }
-      timer = null;
-    }, delay);
+    });
   });
 
   return () => {
     unsub();
-    if (timer) {
-      clearTimeout(timer);
-    }
+    cancel?.();
+    cancel = null;
   };
 }
 
 /**
- * Throttle events on a channel.
+ * This function sends an event of `source` to `target` at most one time in each `interval` (a
+ * throttle). It drops the events between. The interval is a `Duration`, such as `seconds(1)`. A
+ * plain number throws a `TypeError`.
  *
  * @param bus - Event bus
  * @param source - Source channel
  * @param target - Target channel
- * @param interval - Throttle interval in milliseconds
+ * @param interval - The shortest time between two sends
  * @returns Unsubscribe function
  */
 export function throttleChannel<T>(
   bus: EventBus,
   source: string,
   target: string,
-  interval: number
+  interval: Duration,
+  options: ChannelTimingOptions = {},
 ): Unsubscribe {
-  let lastEmit = 0;
+  const intervalMs = toMs(interval, "throttleChannel interval");
+  const clock = options.clock ?? realClock;
+  let lastEmit: number | undefined;
 
   return bus.on<T>(source, (data) => {
-    const now = Date.now();
-
-    if (now - lastEmit >= interval) {
+    const now = clock.now();
+    if (lastEmit === undefined || now - lastEmit >= intervalMs) {
       lastEmit = now;
       bus.emit(target, data);
     }

package/src/events/index.ts

@@ -40,6 +40,7 @@ export type {
   ProcedureChannels,
   DefaultChannels,
   EventBusOptions,
+  EventListenOptions,
   EventWaitOptions,
 } from "./types.js";
 
@@ -65,6 +66,7 @@ export type {
   RemoteEvent,
   RemoteEventHandler,
   RemoteEventsOptions,
+  ResubscribeBackoff,
   SubscribeInput,
   SubscribeOptions,
   Subscription,
@@ -81,3 +83,4 @@ export {
   debounceChannel,
   throttleChannel,
 } from "./bus.js";
+export type { ChannelTimingOptions } from "./bus.js";

package/src/events/publisher.ts

@@ -92,6 +92,14 @@ function stoppedError(): Error {
   return Object.assign(new Error("The publisher of the events stops"), { code: "UNAVAILABLE", retryable: true });
 }
 
+/**
+ * The error that ends a subscription when `clear()` or `clearAll()` of the bus removes the
+ * listener of one of its topics. The subscriber does not resubscribe: the host removed the topic.
+ */
+function clearedError(topic: string): Error {
+  return Object.assign(new Error(`The host cleared the topic "${topic}", so the subscription ends`), { code: "TOPIC_CLEARED", retryable: false });
+}
+
 const topicSchema = z.string().min(1).max(MAX_TOPIC_LENGTH);
 
 const subscribeInput = z.object({
@@ -115,7 +123,8 @@ const eventItemSchema = z.discriminatedUnion("type", [
 /**
  * One subscription: the listeners on the bus and the queue of its events. It is the async
  * iterator of the stream of the call. `return()`, the abort of the signal of the call and
- * `fail()` remove the listeners.
+ * `fail()` remove the listeners. When `clear()` of the bus removes a listener, the subscription
+ * gives the events of its queue, and then it ends with `TOPIC_CLEARED`.
  */
 class TopicSubscription implements AsyncIterableIterator<EventItem> {
   private confirmation: EventItem | undefined;
@@ -135,7 +144,10 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     private readonly onClose: (subscription: TopicSubscription) => void,
   ) {
     this.confirmation = { type: "subscribed", topics };
-    this.unsubscribes = topics.map((topic) => bus.on(topic, (data) => this.push(topic, data)));
+    // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
+    this.unsubscribes = topics.map((topic) =>
+      bus.on(topic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
+    );
     signal?.addEventListener("abort", this.onAbort, { once: true });
   }
 
@@ -201,14 +213,19 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     return this;
   }
 
-  /** This function ends the subscription with an error: the reader gets it at its next item. */
-  fail(error: unknown): void {
+  /**
+   * This function ends the subscription with an error: the reader gets it at its next item. With
+   * `keepQueue`, the reader first gets the confirmation and the events of the queue.
+   */
+  fail(error: unknown, options: { keepQueue?: boolean } = {}): void {
     if (this.closed) return;
     const waiter = this.waiter;
     this.waiter = undefined;
     this.release();
-    this.queue.length = 0;
-    this.confirmation = undefined;
+    if (!options.keepQueue) {
+      this.queue.length = 0;
+      this.confirmation = undefined;
+    }
     if (waiter) waiter.reject(error);
     else this.failure = error;
   }