@procedures/client 0.2.2 → 0.3.0

package/src/client/client.ts

@@ -56,7 +56,8 @@ 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 { TIMEOUT_METADATA_KEY, narrowCapability } from "../procedures/capability.js";
+import { narrowCapability } from "../procedures/capability.js";
+import { TIMEOUT_METADATA_KEY, absorbTimeout, writeRemainingTime } from "./deadline.js";
 import type { Capability, ClearanceOrder, NestedCallOptions } from "../procedures/types.js";
 import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { validateSchema } from "../procedures/schema.js";
@@ -147,6 +148,11 @@ interface CallerContext {
 
 /** The options of `exec()` and `execStream()`. */
 export interface ExecOptions {
+  /**
+   * The signal of the program: an abort stops the call that runs, and the calls that did not
+   * start do not start (roadmap R14). Each nested call gets it.
+   */
+  signal?: AbortSignal | undefined;
   /**
    * This function gets the hydration events of this program only: the refs that hydration runs,
    * also inside control flow and runners, with the call that gets each result. A trace uses it.
@@ -155,6 +161,14 @@ export interface ExecOptions {
   onRef?: ((event: HydrationEvent) => void) | undefined;
 }
 
+/** The caller context of `exec()` and `execStream()`: the observer and the signal. */
+function callerOf(options: ExecOptions): CallerContext {
+  const caller: CallerContext = {};
+  if (options.onRef) caller.onRef = options.onRef;
+  if (options.signal) caller.signal = options.signal;
+  return caller;
+}
+
 /**
  * Generate a unique message ID.
  */
@@ -357,7 +371,7 @@ export class Client<TContext = {}> {
    * ```typescript
    * // Type accumulation example
    * const client = new Client(transport)
-   *   .use(createTimeoutMiddleware({ overall: 5000 }))  // Client<TimeoutContext>
+   *   .use(createOverallTimeoutMiddleware({ overall: 5000 }))  // Client<TimeoutContext>
    *   .use(createRetryMiddleware())                     // Client<TimeoutContext & RetryContext>
    *   .use(createCacheMiddleware({ methods: ["users.get"] }));                    // Client<... & CacheContext>
    *
@@ -478,7 +492,7 @@ export class Client<TContext = {}> {
     input?: unknown,
     options: ExecOptions = {}
   ): Promise<TOutput> {
-    const caller: CallerContext = options.onRef ? { onRef: options.onRef } : {};
+    const caller: CallerContext = callerOf(options);
     const { path, input: hydratedInput } = await this.prepareRef(refOrPath, input, caller);
     return this.execInternal<TOutput>(path, hydratedInput, caller);
   }
@@ -501,7 +515,7 @@ export class Client<TContext = {}> {
     options: ExecOptions = {}
   ): AsyncIterable<TOutput> {
     const self = this;
-    const caller: CallerContext = options.onRef ? { onRef: options.onRef } : {};
+    const caller: CallerContext = callerOf(options);
     return (async function* () {
       const { path, input: hydratedInput } = await self.prepareRef(refOrPath, input, caller);
       yield* self.execStreamInternal<TOutput>(path, hydratedInput, caller);
@@ -744,6 +758,10 @@ export class Client<TContext = {}> {
       (message.metadata as any).__schema = opts.schema;
     }
 
+    // The remaining time of the caller becomes the deadline of the call: the client sends the
+    // remaining time again for each try (roadmap R10)
+    absorbTimeout(message.metadata);
+
     // Compose middleware chain
     const runner = this.composeMiddleware<TReq, TRes>();
 
@@ -771,6 +789,9 @@ export class Client<TContext = {}> {
     // Innermost function: call transport
     const self = this;
     const transportRunner: ClientRunner<TReq, TRes> = async function* (context: ClientContext<TReq>) {
+      // The remaining time of the deadline goes with each try, so the server stops the handler
+      // when this client stops waiting (roadmap R10)
+      writeRemainingTime(context.message.metadata);
       yield* self.transport.send<TReq, TRes>(context.message);
     };
 
@@ -1163,11 +1184,9 @@ export class Client<TContext = {}> {
         yield* outputItems(await invokeProcedure(procedure, input, options));
         return;
       }
-      const callOptions: CallOptions<TContext> = { context: context.metadata as ClientContextInput<TContext> };
-      if (context.signal) {
-        callOptions.signal = context.signal;
-      }
-      yield* self.stream(self.pathToMethod(path), input, callOptions);
+      // The deadline of the capability goes with the call, as for exec() (roadmap R14: before, a
+      // remote leaf of route() sent the signal, not the deadline)
+      yield* self.stream(self.pathToMethod(path), input, self.remoteCallOptions({ metadata: context.metadata, signal: context.signal }));
     })();
   }
 

package/src/client/deadline.ts

@@ -0,0 +1,64 @@
+/**
+ * One deadline for a call (roadmap R10).
+ *
+ * A call has one absolute deadline in its metadata (`__deadline`, a time of `Date.now()`). The
+ * key starts with `__`, so it stays in this process. Each part of the client can only make it
+ * earlier: the remaining time that the caller sends, the overall timeout and the timeout of each
+ * try. Just before the transport sends a try, the client writes the remaining time into
+ * `procedure-timeout`. The server uses it to make its own deadline earlier, so a handler stops
+ * when its caller stops waiting.
+ *
+ * Before, the overall timeout and the timeout of each try did not reach the server, and a
+ * client could also send `X-Timeout`, which the server ignored.
+ */
+
+import type { Metadata } from "./types.js";
+
+/**
+ * The metadata key of the remaining time of a remote call, in milliseconds. A server uses it
+ * only to make its deadline earlier.
+ */
+export const TIMEOUT_METADATA_KEY = "procedure-timeout";
+
+/** The metadata key of the absolute deadline of a call. It stays in this process. */
+export const DEADLINE_METADATA_KEY = "__deadline";
+
+/** The deadline of a call, or undefined. */
+export function deadlineOf(metadata: Metadata): number | undefined {
+  const deadline = metadata[DEADLINE_METADATA_KEY];
+  return typeof deadline === "number" && Number.isFinite(deadline) ? deadline : undefined;
+}
+
+/**
+ * This function makes the deadline of a call earlier: the earlier of its deadline and `at`. It
+ * gives the deadline from before, to put back with `restoreDeadline`.
+ */
+export function narrowDeadline(metadata: Metadata, at: number): number | undefined {
+  const before = deadlineOf(metadata);
+  metadata[DEADLINE_METADATA_KEY] = before === undefined ? at : Math.min(before, at);
+  return before;
+}
+
+/** This function puts back the deadline from before a `narrowDeadline`. */
+export function restoreDeadline(metadata: Metadata, before: number | undefined): void {
+  if (before === undefined) delete metadata[DEADLINE_METADATA_KEY];
+  else metadata[DEADLINE_METADATA_KEY] = before;
+}
+
+/**
+ * The remaining time that the caller gives in `procedure-timeout` becomes the deadline of the
+ * call, when the call starts. The client then writes the remaining time again for each try.
+ */
+export function absorbTimeout(metadata: Metadata, now: number = Date.now()): void {
+  const timeoutMs = metadata[TIMEOUT_METADATA_KEY];
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) return;
+  delete metadata[TIMEOUT_METADATA_KEY];
+  narrowDeadline(metadata, now + timeoutMs);
+}
+
+/** This function writes the remaining time of the deadline into `procedure-timeout`, for one try. */
+export function writeRemainingTime(metadata: Metadata, now: number = Date.now()): void {
+  const deadline = deadlineOf(metadata);
+  if (deadline === undefined) return;
+  metadata[TIMEOUT_METADATA_KEY] = Math.max(0, Math.floor(deadline - now));
+}

package/src/client/errors/factory.ts

@@ -94,8 +94,10 @@ export type ErrorPattern = {
 const ERROR_PATTERNS : ErrorPattern[] = [
   {
     code: ErrorCode.ABORTED,
+    // The reason of AbortSignal.timeout() is a TimeoutError with the message "The operation was
+    // aborted due to timeout": it is a timeout (roadmap R30: before, it was ABORTED)
     detect: (name: string, message: string) =>
-      name === "aborterror" || message.includes("abort"),
+      name === "aborterror" || (name !== "timeouterror" && message.includes("abort")),
   },
   {
     code: ErrorCode.TIMEOUT,
@@ -124,13 +126,8 @@ const ERROR_PATTERNS : ErrorPattern[] = [
       message.includes("network") ||
       message.includes("connection"),
   },
-  {
-    code: ErrorCode.PARSE_ERROR,
-    detect: (_name: string, message: string) =>
-      message.includes("parse") ||
-      message.includes("json") ||
-      message.includes("unexpected token"),
-  },
+  // Before the parse errors: "Converting circular structure to JSON" names JSON too (roadmap R30:
+  // before, it was PARSE_ERROR)
   {
     code: ErrorCode.SERIALIZE_ERROR,
     detect: (_name: string, message: string) =>
@@ -138,6 +135,13 @@ const ERROR_PATTERNS : ErrorPattern[] = [
       message.includes("stringify") ||
       message.includes("circular"),
   },
+  {
+    code: ErrorCode.PARSE_ERROR,
+    detect: (_name: string, message: string) =>
+      message.includes("parse") ||
+      message.includes("json") ||
+      message.includes("unexpected token"),
+  },
 ] as const satisfies ErrorPattern[];
 
 /**

package/src/client/index.ts

@@ -29,7 +29,7 @@ export { LocalTransport } from "../adapters/local/client/index.js";
 export type { LocalTransportOptions, Handler } from "../adapters/local/client/index.js";
 
 export { WebSocketTransport } from "../adapters/websocket/client/index.js";
-export type { WebSocketTransportOptions } from "../adapters/websocket/client/index.js";
+export type { WebSocketTransportOptions, WebSocketClass } from "../adapters/websocket/client/index.js";
 // WebSocketState is a runtime enum — export as a value (not type-only) so consumers can compare
 // transport.getState() === WebSocketState.CONNECTED. See documentation/BUGS-2026-07.md (L1).
 export { WebSocketState } from "../adapters/websocket/client/index.js";
@@ -43,10 +43,13 @@ export type {
 } from "../adapters/mock/client//index.js";
 
 // Middleware
-export { createRetryMiddleware } from "./middleware/retry.js";``
+export { createRetryMiddleware } from "./middleware/retry.js";
+// The delivery of a failed try: it did not leave, or its outcome is indeterminate (roadmap R1)
+export { DELIVERY_METADATA_KEY, deliveryOf, isNotSentError } from "./middleware/items.js";
+export type { Delivery } from "./middleware/items.js";
 export type { RetryOptions } from "./middleware/retry.js";
 
-export { createCacheMiddleware } from "./middleware/cache.js";
+export { createCacheMiddleware, invalidateCache } from "./middleware/cache.js";
 export type { CacheOptions, CacheStats } from "./middleware/cache.js";
 
 export {
@@ -55,6 +58,21 @@ export {
   createCombinedTimeoutMiddleware,
 } from "./middleware/timeout.js";
 export type { TimeoutOptions } from "./middleware/timeout.js";
+// Typed durations (roadmap R11)
+export { ms, seconds, minutes, hours, toMs, isDuration } from "../duration.js";
+export type { Duration } from "../duration.js";
+// The resilience preset and the deadline of a call (roadmap R10)
+export { resilience } from "./middleware/resilience.js";
+export type { ResilienceOptions, ResilienceContext } from "./middleware/resilience.js";
+export {
+  TIMEOUT_METADATA_KEY,
+  DEADLINE_METADATA_KEY,
+  deadlineOf,
+  narrowDeadline,
+  restoreDeadline,
+  absorbTimeout,
+  writeRemainingTime,
+} from "./deadline.js";
 
 export { createPaginationMiddleware, paginateAll } from "./middleware/pagination.js";
 export type { PaginationOptions } from "./middleware/pagination.js";

package/src/client/middleware/cache.ts

@@ -8,6 +8,9 @@
 import type { ClientRunner, ClientContext, ResponseItem, Metadata, Method, TypedClientMiddleware } from "../types.js";
 import type { CacheContext } from "./contexts.js";
 import { LruMap } from "./lru.js";
+import { isDuration, optionalMs, type Duration } from "../../duration.js";
+import type { Effects } from "../../procedures/types.js";
+import { TIMER_DEFAULTS } from "../../timers.js";
 
 /**
  * Cache middleware options.
@@ -21,10 +24,10 @@ export interface CacheOptions {
   methods: readonly string[] | ((method: Method) => boolean);
 
   /**
-   * Time-to-live for cache entries in milliseconds. A call can give its own: `cache: { ttl }`.
+   * Time-to-live for cache entries, for example `minutes(1)`. A call can give its own: `cache: { ttl }`.
    * @default 60000 (1 minute)
    */
-  ttl?: number;
+  ttl?: Duration;
 
   /**
    * Maximum number of cache entries (LRU eviction when exceeded).
@@ -39,11 +42,11 @@ export interface CacheOptions {
   onStats?: (stats: CacheStats) => void;
 
   /**
-   * Interval in milliseconds for emitting cache statistics.
+   * Interval for emitting cache statistics.
    * Only used if onStats is provided.
    * @default 60000 (1 minute)
    */
-  statsInterval?: number;
+  statsInterval?: Duration;
 
   /**
    * Custom cache key generator.
@@ -64,6 +67,14 @@ export interface CacheOptions {
    * @returns true if response should be cached
    */
   shouldCache?: (item: ResponseItem<unknown>) => boolean;
+
+  /**
+   * The effects of each method (roadmap R13), for example `effectsIn(registry)`. A call that
+   * writes resources deletes the cached entries of the methods that read one of them, when it
+   * succeeds. An entry of a method with unknown reads goes too. Without this option, a write
+   * deletes nothing, and the entries live until their time to live ends.
+   */
+  effects?: (method: Method) => Effects | undefined;
 }
 
 /**
@@ -110,10 +121,21 @@ export function stableStringify(value: unknown): string {
 }
 
 /**
- * The metadata keys that do not change a response: middleware state and tracing. The other
- * keys (auth, pagination, custom fields) are part of the cache key.
+ * The metadata keys that do not change a response: middleware state, tracing, and the keys of
+ * one call (its idempotency key and the remaining time of its deadline). The other keys (auth,
+ * pagination, custom fields) are part of the cache key.
  */
-const VOLATILE_METADATA = new Set(["retry", "timeout", "tracing", "cache", "circuitBreaker", "rateLimit"]);
+const VOLATILE_METADATA = new Set([
+  "retry",
+  "timeout",
+  "tracing",
+  "cache",
+  "circuitBreaker",
+  "rateLimit",
+  "idempotency-key",
+  "procedure-timeout",
+  "traceparent",
+]);
 
 /** The part of the metadata that can change a response. */
 function keyMetadata(metadata: Metadata): Record<string, unknown> {
@@ -153,6 +175,21 @@ function copyItem<T>(item: ResponseItem<T>): ResponseItem<T> | undefined {
 interface CacheEntry {
   items: ResponseItem<unknown>[];
   expiresAt: number;
+  /** The resources that the method of the entry reads, when the `effects` option knows them */
+  reads: readonly string[] | undefined;
+  /** The method of the entry, for the invalidation by method */
+  method: Method;
+}
+
+/** The deleters of each cache middleware, for `invalidateCache` */
+const invalidators = new WeakMap<object, (matches?: (method: Method) => boolean) => number>();
+
+/**
+ * This function deletes the entries of a cache middleware: all of them, or the entries of the
+ * methods that `matches` selects. It gives the number of deleted entries.
+ */
+export function invalidateCache(middleware: object, matches?: (method: Method) => boolean): number {
+  return invalidators.get(middleware)?.(matches) ?? 0;
 }
 
 /** The overrides of one call: `cache: { ttl, bypass, refresh }` in its context. */
@@ -160,7 +197,7 @@ function cacheOverrides(value: unknown): { ttl?: number; bypass?: boolean; refre
   if (typeof value !== "object" || value === null) return {};
   const { ttl, bypass, refresh } = value as Record<string, unknown>;
   return {
-    ...(typeof ttl === "number" && ttl >= 0 ? { ttl } : {}),
+    ...(isDuration(ttl) && ttl.value >= 0 ? { ttl: optionalMs(ttl, "cache.ttl")! } : {}),
     ...(bypass === true ? { bypass: true } : {}),
     ...(refresh === true ? { refresh: true } : {}),
   };
@@ -199,18 +236,18 @@ function defaultShouldCache(item: ResponseItem<unknown>): boolean {
  * client.use(createCacheMiddleware({
  *   methods: ["users.get", "users.list"], // only these calls are cached
  *   capacity: 100,
- *   ttl: 60000, // 1 minute
+ *   ttl: minutes(1),
  *   onStats: (stats) => console.log(`Hit rate: ${stats.hitRate}%`)
  * }));
  * ```
  */
 export function createCacheMiddleware(options: CacheOptions): TypedClientMiddleware<CacheContext, {}> {
+  const ttl = optionalMs(options.ttl, "ttl") ?? TIMER_DEFAULTS.cache.ttlMs;
+  const statsInterval = optionalMs(options.statsInterval, "statsInterval") ?? TIMER_DEFAULTS.cache.statsIntervalMs;
   const {
     methods,
-    ttl = 60000,
     capacity = 100,
     onStats,
-    statsInterval = 60000,
     keyGenerator = defaultKeyGenerator,
     shouldCache = defaultShouldCache,
   } = options;
@@ -253,11 +290,30 @@ export function createCacheMiddleware(options: CacheOptions): TypedClientMiddlew
       : ((names: ReadonlySet<string>) => (method: Method): boolean => names.has(`${method.service}.${method.operation}`))(
           new Set(methods),
         );
+  const effectsOf = options.effects;
+
+  /**
+   * The calls in flight, by key: a second call with the same key waits for the first one and
+   * gets a copy of its response (roadmap R13). Before, each one made its own request.
+   */
+  const inFlight = new Map<string, Promise<CacheEntry | undefined>>();
 
-  return <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
+  /** A write that succeeded deletes the entries that read one of its resources (R13). */
+  const invalidateAfterWrite = (method: Method): void => {
+    const writes = effectsOf?.(method)?.writes;
+    if (!writes || writes.length === 0) return;
+    cache.deleteWhere((entry) => entry.reads === undefined || entry.reads.some((resource) => writes.includes(resource)));
+  };
+
+  const middleware = <TReq, TRes>(next: ClientRunner<TReq, TRes>): ClientRunner<TReq, TRes> => {
     return async function* (context: ClientContext<TReq>) {
       if (!cacheable(context.message.method)) {
-        yield* next(context);
+        let failed = false;
+        for await (const item of next(context)) {
+          if (item.status.type === "error") failed = true;
+          yield item;
+        }
+        if (!failed && effectsOf) invalidateAfterWrite(context.message.method);
         return;
       }
 
@@ -294,23 +350,64 @@ export function createCacheMiddleware(options: CacheOptions): TypedClientMiddlew
         cache.delete(cacheKey);
       }
 
+      // The same call is in flight: wait for it and give a copy of its response (R13)
+      const pending = overrides.refresh ? undefined : inFlight.get(cacheKey);
+      if (pending) {
+        const shared = await pending;
+        if (shared) {
+          stats.hits++;
+          setState(true);
+          for (const item of shared.items) yield (copyItem(item) ?? item) as ResponseItem<TRes>;
+          return;
+        }
+        // The first call gave a stream or an error: this call makes its own request
+      }
+
       // Cache miss - fetch and store. Only a response of one item is cached: a stream is never
       // collected or cached (before, the middleware kept every item of a stream in memory).
       stats.misses++;
       let first: ResponseItem<TRes> | undefined;
       let count = 0;
+      let settle: (entry: CacheEntry | undefined) => void = () => undefined;
+      const mine = new Promise<CacheEntry | undefined>((resolve) => (settle = resolve));
+      if (!overrides.refresh) inFlight.set(cacheKey, mine);
+      let entry: CacheEntry | undefined;
+      try {
+        for await (const item of next(context)) {
+          count++;
+          if (count === 1) first = item;
+          yield item;
+        }
+        setState(false);
 
-      for await (const item of next(context)) {
-        count++;
-        if (count === 1) first = item;
-        yield item;
-      }
-      setState(false);
-
-      if (count === 1 && first && shouldCache(first)) {
-        const copy = copyItem(first);
-        if (copy) cache.set(cacheKey, { items: [copy as ResponseItem<unknown>], expiresAt: Date.now() + (overrides.ttl ?? ttl) });
+        // An inner layer that changed the key metadata during the call (an auth middleware
+        // inside the cache) makes the key wrong: such a response is not stored (R13)
+        const keyAfter = keyGenerator(context.message.method, context.message.payload, metadata);
+        if (count === 1 && first && shouldCache(first) && keyAfter === cacheKey) {
+          const copy = copyItem(first);
+          if (copy) {
+            entry = {
+              items: [copy as ResponseItem<unknown>],
+              expiresAt: Date.now() + (overrides.ttl ?? ttl),
+              reads: effectsOf?.(context.message.method)?.reads,
+              method: context.message.method,
+            };
+            cache.set(cacheKey, entry);
+          }
+        }
+      } finally {
+        if (inFlight.get(cacheKey) === mine) inFlight.delete(cacheKey);
+        settle(entry);
       }
     };
   };
+  invalidators.set(middleware, (matches) => {
+    if (!matches) {
+      const size = cache.size;
+      cache.clear();
+      return size;
+    }
+    return cache.deleteWhere((entry) => matches(entry.method));
+  });
+  return middleware;
 }