@procedures/client 0.0.0-stage → 0.1.0

package/src/client/call-types.ts

@@ -0,0 +1,491 @@
+/**
+ * Nested Call API Types
+ *
+ * Type definitions for the new nested route call structure.
+ * Enables typed per-call middleware config and natural batching.
+ */
+
+import type { ProcedurePath } from "../procedures/types.js";
+import type { RouteLeaf, OutputConfig } from "./consumption.js";
+import { isRouteLeafWithConfig, extractInput, extractOutputConfig } from "./consumption.js";
+
+// Re-export consumption types for convenience
+export type { RouteLeaf, RouteLeafWithConfig, OutputConfig } from "./consumption.js";
+export { isRouteLeafWithConfig, extractInput, extractOutputConfig } from "./consumption.js";
+// =============================================================================
+// Middleware Override Types
+// =============================================================================
+
+/**
+ * Per-call retry configuration override.
+ */
+export interface RetryOverride {
+  /** Maximum number of retry attempts */
+  attempts?: number;
+  /** Delay between retries in milliseconds */
+  delay?: number;
+  /** Exponential backoff multiplier */
+  backoffMultiplier?: number;
+  /** Maximum delay between retries */
+  maxDelay?: number;
+}
+
+/**
+ * Per-call timeout configuration override.
+ */
+export interface TimeoutOverride {
+  /** Overall request timeout in milliseconds */
+  ms?: number;
+  /** Per-attempt timeout for retries */
+  perAttempt?: number;
+}
+
+/**
+ * Per-call cache configuration override.
+ */
+export interface CacheOverride {
+  /** Time-to-live in milliseconds */
+  ttl?: number;
+  /** Skip cache for this request */
+  bypass?: boolean;
+  /** Force cache refresh */
+  refresh?: boolean;
+}
+
+/**
+ * Per-call middleware configuration overrides.
+ * Each middleware can define its own override type.
+ */
+export interface MiddlewareOverrides {
+  retry?: RetryOverride;
+  timeout?: TimeoutOverride;
+  cache?: CacheOverride;
+  /** Extensible for custom middleware overrides */
+  [key: string]: unknown;
+}
+
+/**
+ * This function converts the overrides of a route call to the context keys that the middleware
+ * reads: `retry.attempts` becomes `retry.maxAttempts`, and `timeout.ms` becomes
+ * `timeout.overall`. The other keys pass unchanged. (Before, the documented keys had no
+ * effect: deep dive CORE-14.)
+ *
+ * @param overrides - The `middlewares` of a route call
+ * @returns The context for the metadata of the calls
+ */
+export function toMiddlewareContext(overrides: MiddlewareOverrides | undefined): Record<string, unknown> {
+  const context: Record<string, unknown> = {};
+  if (!overrides) return context;
+  for (const [key, value] of Object.entries(overrides)) {
+    if (FORBIDDEN_ROUTE_KEYS.has(key)) continue;
+    context[key] = value;
+  }
+  if (overrides.retry) {
+    const { attempts, ...rest } = overrides.retry;
+    context["retry"] = attempts === undefined ? rest : { ...rest, maxAttempts: attempts };
+  }
+  if (overrides.timeout) {
+    const { ms, ...rest } = overrides.timeout;
+    context["timeout"] = ms === undefined ? rest : { ...rest, overall: ms };
+  }
+  return context;
+}
+
+// =============================================================================
+// Batch Strategy Types
+// =============================================================================
+
+/**
+ * Batch execution strategy.
+ */
+export type BatchStrategy = "all" | "race" | "stream";
+
+/**
+ * Stream configuration for batch execution.
+ */
+export interface StreamConfig {
+  /** When this many results wait for the reader, no new call starts. 0 or no value: no limit. */
+  bufferSize?: number;
+  /** True (the default): each result as it arrives. False: all results at the end, in route order. */
+  emitPartial?: boolean;
+  /** Maximum concurrent requests */
+  concurrency?: number;
+}
+
+/**
+ * Batch execution configuration.
+ */
+export interface BatchConfig {
+  /** Execution strategy */
+  strategy: BatchStrategy;
+  /** Stream configuration: `concurrency` applies to every strategy but `race` */
+  streamConfig?: StreamConfig;
+  /**
+   * True (the default): every call runs to its end. False: the first failure cancels the other
+   * calls, and each of them gets a `CANCELLED` result.
+   */
+  continueOnError?: boolean;
+}
+
+// =============================================================================
+// Route Types
+// =============================================================================
+
+/**
+ * Recursive route node - can contain nested nodes or leaf payloads.
+ * Leaf nodes are either:
+ * - RouteLeafWithConfig: { in: input, out?: outputConfig }
+ * - LegacyRouteLeaf: plain object (backward compatible)
+ */
+export type RouteNode = {
+  [key: string]: RouteNode | RouteLeaf;
+};
+
+/**
+ * Root route structure for a call.
+ * The structure maps to procedure paths in the registry.
+ */
+export type Route = RouteNode;
+
+// =============================================================================
+// Call Request Types
+// =============================================================================
+
+/**
+ * Nested call request structure.
+ *
+ * @example
+ * ```typescript
+ * const request: CallRequest = {
+ *   middlewares: {
+ *     retry: { attempts: 3 },
+ *     timeout: { ms: 5000 }
+ *   },
+ *   batch: { strategy: 'all' },
+ *   route: {
+ *     collections: {
+ *       users: {
+ *         get: { id: "123" }
+ *       }
+ *     },
+ *     weather: {
+ *       forecast: { city: "NYC", days: 5 }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface CallRequest<TRoute extends Route = Route> {
+  /** Per-call middleware configuration overrides */
+  middlewares?: MiddlewareOverrides;
+
+  /** Batch execution configuration (for multiple routes) */
+  batch?: BatchConfig;
+
+  /** Nested route structure mapping to procedures */
+  route: TRoute;
+
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Simplified call request for single-route calls.
+ * Omits batch config since there's only one route.
+ */
+export interface SingleCallRequest<TRoute extends Route = Route> {
+  middlewares?: MiddlewareOverrides;
+  route: TRoute;
+  signal?: AbortSignal;
+}
+
+// =============================================================================
+// Call Response Types
+// =============================================================================
+
+/**
+ * Result of a single procedure call.
+ */
+export interface ProcedureCallResult<TOutput = unknown> {
+  /** Whether the call succeeded */
+  success: boolean;
+  /** Output data (present if success=true) */
+  data?: TOutput;
+  /** Error info (present if success=false) */
+  error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+    path: ProcedurePath;
+  };
+}
+
+/**
+ * Response type that mirrors the route structure.
+ * Each leaf node becomes a ProcedureCallResult.
+ */
+export type CallResponse<TRoute> = TRoute extends RouteLeaf
+  ? ProcedureCallResult
+  : {
+      [K in keyof TRoute]: TRoute[K] extends RouteNode
+        ? CallResponse<TRoute[K]>
+        : ProcedureCallResult;
+    };
+
+/**
+ * Streaming response for batch calls with stream strategy.
+ */
+export interface StreamingCallResponse<TRoute extends Route = Route> {
+  /** Async iterator yielding results as they arrive */
+  results: AsyncIterable<{
+    /** Path to the result in the route structure */
+    path: ProcedurePath;
+    /** The procedure result */
+    result: ProcedureCallResult;
+  }>;
+
+  /** Promise that resolves to the complete response when all results arrive */
+  complete: Promise<CallResponse<TRoute>>;
+}
+
+// =============================================================================
+// Type Inference Utilities
+// =============================================================================
+
+/**
+ * Extract all paths from a route structure.
+ * Used internally for route validation and resolution.
+ */
+export type ExtractRoutePaths<TRoute, TPrefix extends string[] = []> =
+  TRoute extends RouteLeaf
+    ? TPrefix
+    : TRoute extends RouteNode
+      ? {
+          [K in keyof TRoute]: TRoute[K] extends RouteNode
+            ? ExtractRoutePaths<TRoute[K], [...TPrefix, K & string]>
+            : [...TPrefix, K & string];
+        }[keyof TRoute]
+      : never;
+
+/**
+ * Validate that a route structure only contains valid procedure paths.
+ * This is a compile-time check.
+ */
+export type ValidateRoute<TRoute, TRegisteredPaths extends string[][]> =
+  ExtractRoutePaths<TRoute> extends TRegisteredPaths[number] ? TRoute : never;
+
+// =============================================================================
+// Route Path Utilities
+// =============================================================================
+
+/**
+ * Route keys that name a property of every object. A route key is a path segment, and code
+ * that walks a route with such a key reaches `Object.prototype` (deep dive CORE-6).
+ */
+const FORBIDDEN_ROUTE_KEYS: ReadonlySet<string> = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * This function throws for a route key that would reach `Object.prototype`. `JSON.parse` makes
+ * `"__proto__"` an own key, so a route from JSON can contain it.
+ *
+ * @param key - A route key (a procedure path segment)
+ */
+export function assertRouteKey(key: string): void {
+  if (FORBIDDEN_ROUTE_KEYS.has(key)) {
+    throw new Error(`Invalid route key: ${key}`);
+  }
+}
+
+/**
+ * Flattened route entry with path, input, and output configuration.
+ */
+export interface FlattenedRouteEntry {
+  /** Procedure path */
+  path: ProcedurePath;
+  /** Extracted input payload */
+  input: unknown;
+  /** Output configuration (default: sponge) */
+  outputConfig: OutputConfig;
+  /** Original leaf node (for reference) */
+  leaf: RouteLeaf;
+}
+
+/**
+ * Convert a nested route structure to an array of flattened entries.
+ * Handles both new { in, out } format and legacy plain objects.
+ *
+ * @param route - Nested route object
+ * @returns Array of flattened route entries
+ */
+export function flattenRoute(route: Route): FlattenedRouteEntry[] {
+  const results: FlattenedRouteEntry[] = [];
+
+  function traverse(node: RouteNode | RouteLeaf, path: ProcedurePath): void {
+    path.forEach(assertRouteKey);
+    // Check if this is a new-style leaf: { in: ..., out?: ... }
+    if (isRouteLeafWithConfig(node)) {
+      results.push({
+        path,
+        input: extractInput(node),
+        outputConfig: extractOutputConfig(node),
+        leaf: node,
+      });
+      return;
+    }
+
+    // Check if this is a legacy leaf node (procedure input)
+    // A leaf has no nested RouteNode children - all values are primitives or arrays
+    const isLegacyLeaf = Object.values(node).every(
+      (v) => typeof v !== "object" || v === null || Array.isArray(v)
+    );
+
+    if (isLegacyLeaf) {
+      results.push({
+        path,
+        input: node,
+        outputConfig: { type: "sponge" },
+        leaf: node as RouteLeaf,
+      });
+      return;
+    }
+
+    // Continue traversing nested nodes
+    for (const [key, value] of Object.entries(node)) {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        traverse(value as RouteNode, [...path, key]);
+      }
+    }
+  }
+
+  traverse(route, []);
+  return results;
+}
+
+/**
+ * Legacy flatten function for backward compatibility.
+ * Returns [path, leaf] pairs without output config extraction.
+ *
+ * @deprecated Use flattenRoute() which returns FlattenedRouteEntry[]
+ */
+export function flattenRouteLegacy(route: Route): Array<[ProcedurePath, RouteLeaf]> {
+  return flattenRoute(route).map((entry) => [entry.path, entry.leaf]);
+}
+
+/**
+ * Build a nested response structure from flat results.
+ *
+ * @param results - Array of [path, result] tuples
+ * @returns Nested response object
+ */
+export function buildResponse<TRoute extends Route>(
+  results: Array<[ProcedurePath, ProcedureCallResult]>
+): CallResponse<TRoute> {
+  const response: Record<string, unknown> = {};
+
+  for (const [path, result] of results) {
+    path.forEach(assertRouteKey);
+    let current = response;
+
+    for (let i = 0; i < path.length; i++) {
+      const segment = path[i]!;
+      const isLast = i === path.length - 1;
+
+      if (isLast) {
+        current[segment] = result;
+      } else {
+        // An own key only: `in` also saw inherited names such as "toString"
+        if (!Object.hasOwn(current, segment)) {
+          current[segment] = {};
+        }
+        current = current[segment] as Record<string, unknown>;
+      }
+    }
+  }
+
+  return response as CallResponse<TRoute>;
+}
+
+/**
+ * Check if a route contains multiple procedure calls.
+ * Used to determine if batch execution is needed.
+ *
+ * @param route - Route to check
+ * @returns true if route contains multiple procedures
+ */
+export function isBatchRoute(route: Route): boolean {
+  const paths = flattenRoute(route);
+  return paths.length > 1;
+}
+
+// =============================================================================
+// Type-Safe Route Builders
+// =============================================================================
+
+/**
+ * Helper to create a type-safe route for a single procedure.
+ *
+ * @param path - Procedure path
+ * @param input - Procedure input
+ * @returns Route object
+ *
+ * @example
+ * ```typescript
+ * const route = createRoute(['users', 'get'], { id: '123' });
+ * // { users: { get: { id: '123' } } }
+ * ```
+ */
+export function createRoute<TInput extends RouteLeaf>(
+  path: ProcedurePath,
+  input: TInput
+): Route {
+  path.forEach(assertRouteKey);
+  const route: Record<string, unknown> = {};
+  let current = route;
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i]!;
+    const isLast = i === path.length - 1;
+
+    if (isLast) {
+      current[segment] = input;
+    } else {
+      current[segment] = {};
+      current = current[segment] as Record<string, unknown>;
+    }
+  }
+
+  return route as Route;
+}
+
+/**
+ * Merge multiple routes into a single batched route.
+ *
+ * @param routes - Routes to merge
+ * @returns Merged route
+ */
+export function mergeRoutes(...routes: Route[]): Route {
+  const merged: Record<string, unknown> = {};
+
+  function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+    for (const [key, value] of Object.entries(source)) {
+      assertRouteKey(key);
+      if (
+        Object.hasOwn(target, key) &&
+        typeof target[key] === "object" &&
+        typeof value === "object" &&
+        !Array.isArray(target[key]) &&
+        !Array.isArray(value)
+      ) {
+        deepMerge(target[key] as Record<string, unknown>, value as Record<string, unknown>);
+      } else {
+        target[key] = value;
+      }
+    }
+  }
+
+  for (const route of routes) {
+    deepMerge(merged, route as Record<string, unknown>);
+  }
+
+  return merged as Route;
+}