@procedures/client 0.47.2 → 0.48.0

package/src/events/publisher.ts

@@ -226,6 +226,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 +255,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 }) =>

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/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";
   }
 }