@procedures/client 0.0.0-stage → 0.2.0

package/src/client/consumption.ts

@@ -0,0 +1,288 @@
+/**
+ * Consumption Types
+ *
+ * Types for configuring how procedure outputs are consumed.
+ * Supports sponge (accumulate), stream (iterate), and handler modes.
+ */
+
+import type { ProcedurePath } from "../procedures/types.js";
+
+// =============================================================================
+// Output Configuration Types
+// =============================================================================
+
+/**
+ * Sponge mode - accumulate all yields into a single value.
+ * For single-yield procedures: returns immediately.
+ * For multi-yield procedures: returns final accumulated value.
+ */
+export interface SpongeOutputConfig {
+  type: "sponge";
+  /**
+   * Accumulator function for multi-yield procedures.
+   * If not provided, returns only the last yielded value.
+   */
+  accumulate?: <T>(accumulated: T[], current: T) => T;
+}
+
+/**
+ * Stream mode - return AsyncIterator of yields.
+ */
+export interface StreamOutputConfig {
+  type: "stream";
+  /**
+   * The number of items to read ahead of the reader. 0 or no value: the procedure runs only
+   * when the reader reads.
+   */
+  bufferSize?: number;
+}
+
+/**
+ * Handler callback type - either a function or a procedure path.
+ * Procedure paths allow declarative handler routing.
+ */
+export type HandlerCallback<T = unknown> =
+  | ((data: T) => void | Promise<void>)
+  | ProcedurePath;
+
+/**
+ * Handler mode - callbacks for progress/complete/error events.
+ * Handlers can be functions or procedure paths for declarative routing.
+ */
+export interface HandlerOutputConfig<TProgress = unknown, TComplete = unknown> {
+  /**
+   * Called for each intermediate yield (streaming procedures).
+   * Can be a callback function or a procedure path.
+   */
+  progress?: HandlerCallback<TProgress>;
+
+  /**
+   * Called when the procedure completes with final value.
+   * Can be a callback function or a procedure path.
+   */
+  complete?: HandlerCallback<TComplete>;
+
+  /**
+   * Called if the procedure throws an error.
+   * Can be a callback function or a procedure path.
+   */
+  error?: HandlerCallback<Error>;
+}
+
+/**
+ * Output consumption configuration.
+ *
+ * @example
+ * ```typescript
+ * // Sponge mode - accumulate to single value
+ * { type: "sponge" }
+ *
+ * // Stream mode - async iterator
+ * { type: "stream" }
+ *
+ * // Handler mode - callbacks
+ * {
+ *   progress: (data) => console.log("Progress:", data),
+ *   complete: (data) => console.log("Done:", data),
+ * }
+ *
+ * // Handler mode - declarative procedure routing
+ * {
+ *   progress: ["ui", "progress-bar", "update"],
+ *   complete: ["files", "save-local"],
+ * }
+ * ```
+ */
+export type OutputConfig<TProgress = unknown, TComplete = unknown> =
+  | SpongeOutputConfig
+  | StreamOutputConfig
+  | HandlerOutputConfig<TProgress, TComplete>;
+
+/**
+ * Default output config when none specified.
+ * Sponge mode for backward compatibility.
+ */
+export const DEFAULT_OUTPUT_CONFIG: SpongeOutputConfig = { type: "sponge" };
+
+// =============================================================================
+// Route Leaf Types
+// =============================================================================
+
+/**
+ * Route leaf with input/output configuration.
+ * Leaves are the terminal nodes in a route tree.
+ *
+ * @example
+ * ```typescript
+ * // Simple input only (sponge by default)
+ * { in: { id: "123" } }
+ *
+ * // With explicit output config
+ * { in: { id: "123" }, out: { type: "stream" } }
+ *
+ * // With handler callbacks
+ * {
+ *   in: { fileId: "abc" },
+ *   out: {
+ *     progress: (p) => updateUI(p),
+ *     complete: (data) => save(data),
+ *   }
+ * }
+ * ```
+ */
+export interface RouteLeafWithConfig<TInput = unknown, TProgress = unknown, TComplete = unknown> {
+  /** Procedure input payload */
+  in: TInput;
+  /** Output consumption configuration (default: sponge) */
+  out?: OutputConfig<TProgress, TComplete>;
+}
+
+/**
+ * Legacy route leaf - plain input object (backward compatible).
+ * Treated as { in: input, out: { type: "sponge" } }
+ */
+export type LegacyRouteLeaf = Record<string, unknown>;
+
+/**
+ * Unified route leaf type.
+ * Supports both new { in, out } format and legacy plain objects.
+ */
+export type RouteLeaf<TInput = unknown> =
+  | RouteLeafWithConfig<TInput>
+  | LegacyRouteLeaf;
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if a route leaf uses the new { in, out } format.
+ */
+export function isRouteLeafWithConfig(leaf: RouteLeaf): leaf is RouteLeafWithConfig {
+  return leaf !== null && typeof leaf === "object" && "in" in leaf;
+}
+
+/**
+ * Check if output config is sponge mode.
+ */
+export function isSpongeConfig(config: OutputConfig | undefined): config is SpongeOutputConfig {
+  return config === undefined || ("type" in config && config.type === "sponge");
+}
+
+/**
+ * Check if output config is stream mode.
+ */
+export function isStreamConfig(config: OutputConfig | undefined): config is StreamOutputConfig {
+  return config !== undefined && "type" in config && config.type === "stream";
+}
+
+/**
+ * Check if output config is handler mode.
+ */
+export function isHandlerConfig(config: OutputConfig | undefined): config is HandlerOutputConfig {
+  return config !== undefined && !("type" in config);
+}
+
+/**
+ * Check if a handler callback is a procedure path.
+ */
+export function isProcedureCallback(callback: HandlerCallback | undefined): callback is ProcedurePath {
+  return Array.isArray(callback);
+}
+
+// =============================================================================
+// Extraction Utilities
+// =============================================================================
+
+/**
+ * Extract input from a route leaf (handles both formats).
+ */
+export function extractInput<TInput>(leaf: RouteLeaf<TInput>): TInput {
+  if (isRouteLeafWithConfig(leaf)) {
+    return leaf.in as TInput;
+  }
+  return leaf as unknown as TInput;
+}
+
+/**
+ * Extract output config from a route leaf.
+ * Returns sponge config for legacy leaves.
+ */
+export function extractOutputConfig(leaf: RouteLeaf): OutputConfig {
+  if (isRouteLeafWithConfig(leaf)) {
+    return leaf.out ?? DEFAULT_OUTPUT_CONFIG;
+  }
+  return DEFAULT_OUTPUT_CONFIG;
+}
+
+// =============================================================================
+// Output Config Defaults
+// =============================================================================
+
+/**
+ * Create a sponge output config.
+ */
+export function sponge(options?: Omit<SpongeOutputConfig, "type">): SpongeOutputConfig {
+  return { type: "sponge", ...options };
+}
+
+/**
+ * Create a stream output config.
+ */
+export function stream(options?: Omit<StreamOutputConfig, "type">): StreamOutputConfig {
+  return { type: "stream", ...options };
+}
+
+/**
+ * Create a handler output config.
+ */
+export function handlers<TProgress = unknown, TComplete = unknown>(
+  config: HandlerOutputConfig<TProgress, TComplete>
+): HandlerOutputConfig<TProgress, TComplete> {
+  return config;
+}
+
+// =============================================================================
+// Type-Refined Consumption Result
+// =============================================================================
+
+/**
+ * Consumption mode - how the caller wants to receive the output.
+ */
+export type ConsumptionMode = 'sponge' | 'stream' | 'handlers';
+
+/**
+ * Infer consumption mode from output config.
+ */
+export type InferConsumptionMode<TConfig extends OutputConfig | undefined> =
+  TConfig extends StreamOutputConfig ? 'stream' :
+  TConfig extends HandlerOutputConfig ? 'handlers' :
+  'sponge';
+
+/**
+ * The result type based on consumption mode.
+ *
+ * - sponge: Returns Promise<T> (accumulated single value)
+ * - stream: Returns AsyncIterable<T> (values as they arrive)
+ * - handlers: Returns void (values delivered via callbacks)
+ */
+export type ConsumptionResult<T, TMode extends ConsumptionMode> =
+  TMode extends 'sponge' ? Promise<T> :
+  TMode extends 'stream' ? AsyncIterable<T> :
+  TMode extends 'handlers' ? void :
+  never;
+
+/**
+ * Infer the result type from output config and value type.
+ */
+export type InferConsumptionResult<T, TConfig extends OutputConfig | undefined> =
+  ConsumptionResult<T, InferConsumptionMode<TConfig>>;
+
+/**
+ * Type-safe consumption mode check.
+ */
+export function getConsumptionMode(config: OutputConfig | undefined): ConsumptionMode {
+  if (isStreamConfig(config)) return 'stream';
+  if (isHandlerConfig(config)) return 'handlers';
+  return 'sponge';
+}

package/src/client/context.ts

@@ -0,0 +1,228 @@
+/**
+ * Client Context System
+ *
+ * Provides hierarchical context passing for middleware configuration.
+ * Context can be set at client-level, inherited by child clients, and
+ * overridden per-call.
+ *
+ * @example
+ * ```typescript
+ * // Client-level context
+ * const authedClient = client.withContext({
+ *   auth: { token: "user-token" },
+ *   timeout: { overall: 5000 }
+ * });
+ *
+ * // Per-call override
+ * await authedClient.call(method, payload, {
+ *   context: { retry: { maxAttempts: 10 } }
+ * });
+ * ```
+ */
+
+import type { Metadata } from "./types.js";
+import type {
+  RetryContext,
+  CacheContext,
+  TimeoutContext,
+  AuthContext,
+  TracingContext,
+  CircuitBreakerContext,
+  RateLimitContext,
+  PaginationContext,
+} from "./middleware/contexts.js";
+
+// =============================================================================
+// Context Input Types
+// =============================================================================
+
+/**
+ * All possible middleware context fields that can be passed by the user.
+ * This is the union of all middleware context types, made partial for input.
+ */
+export type MiddlewareContextFields = Partial<
+  RetryContext &
+    CacheContext &
+    TimeoutContext &
+    AuthContext &
+    TracingContext &
+    CircuitBreakerContext &
+    RateLimitContext &
+    PaginationContext
+>;
+
+/**
+ * Context input type for client.withContext() and per-call context.
+ *
+ * When TContext is the accumulated context type from middleware,
+ * this allows passing any subset of that context plus any middleware fields.
+ */
+export type ClientContextInput<TContext = {}> = TContext extends object
+  ? Partial<TContext> & MiddlewareContextFields
+  : MiddlewareContextFields;
+
+// =============================================================================
+// Call Options
+// =============================================================================
+
+/**
+ * Schema definition for per-call validation override.
+ * Only available when Zod middleware is installed.
+ */
+export interface SchemaOverride {
+  /** Input/request payload schema */
+  input?: unknown; // z.ZodType when zod is installed
+  /** Output/response payload schema */
+  output?: unknown; // z.ZodType when zod is installed
+}
+
+/**
+ * Options for client.call() and client.stream() methods.
+ *
+ * Provides fine-grained control over individual requests including
+ * context overrides, raw metadata, cancellation, and validation.
+ *
+ * @example
+ * ```typescript
+ * // Full options example
+ * await client.call(method, payload, {
+ *   context: { auth: { token: "override-token" } },
+ *   metadata: { "x-custom-header": "value" },
+ *   signal: abortController.signal,
+ *   schema: { input: MyInputSchema, output: MyOutputSchema }
+ * });
+ * ```
+ */
+export interface CallOptions<TContext = {}> {
+  /**
+   * Per-call context override.
+   * Merged with client context, with per-call values taking priority.
+   */
+  context?: ClientContextInput<TContext>;
+
+  /**
+   * Additional raw metadata to include in the request.
+   * Applied after context merge, so takes highest priority.
+   */
+  metadata?: Metadata;
+
+  /**
+   * Abort signal for request cancellation.
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Per-call schema override for validation.
+   * Requires Zod middleware to be installed.
+   */
+  schema?: SchemaOverride;
+}
+
+// =============================================================================
+// Context Merging
+// =============================================================================
+
+/**
+ * Deep merge context objects with later values taking priority.
+ *
+ * Merges nested objects recursively, while replacing primitives and arrays.
+ * Undefined values are skipped (don't override existing values).
+ *
+ * @example
+ * ```typescript
+ * const base = { auth: { token: "a", userId: "1" }, timeout: { overall: 5000 } };
+ * const override = { auth: { token: "b" }, retry: { maxAttempts: 3 } };
+ *
+ * mergeContext(base, override);
+ * // Result: {
+ * //   auth: { token: "b", userId: "1" },
+ * //   timeout: { overall: 5000 },
+ * //   retry: { maxAttempts: 3 }
+ * // }
+ * ```
+ */
+export function mergeContext<T extends object>(
+  base: T | undefined,
+  ...overrides: (Partial<T> | undefined)[]
+): T {
+  const result = { ...(base ?? {}) } as T;
+
+  for (const override of overrides) {
+    if (!override) continue;
+
+    for (const [key, value] of Object.entries(override)) {
+      if (value === undefined) continue;
+      // A context from JSON can have an own "__proto__" key: never copy it (deep dive CORE-6)
+      if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+
+      if (isPlainObject(value) && isPlainObject((result as Record<string, unknown>)[key])) {
+        // Deep merge objects
+        (result as Record<string, unknown>)[key] = mergeContext(
+          (result as Record<string, unknown>)[key] as object,
+          value,
+        );
+      } else {
+        // Replace primitives, arrays, and other values
+        (result as Record<string, unknown>)[key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a value is a plain object (not array, null, Date, etc.).
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+// =============================================================================
+// Type Helpers
+// =============================================================================
+
+/**
+ * Known keys that distinguish CallOptions from legacy Metadata.
+ * If any of these keys are present, the object is CallOptions.
+ */
+const CALL_OPTIONS_KEYS = ["context", "metadata", "signal", "schema"] as const;
+
+/**
+ * Check if options object is CallOptions or legacy Metadata.
+ *
+ * CallOptions has at least one of the known CallOptions keys.
+ * Metadata is a plain object without these specific keys.
+ */
+export function isCallOptions<TContext>(
+  options: CallOptions<TContext> | Metadata | undefined,
+): options is CallOptions<TContext> {
+  if (!options || typeof options !== "object") {
+    return false;
+  }
+
+  return CALL_OPTIONS_KEYS.some((key) => key in options);
+}
+
+/**
+ * Normalize call options to always be CallOptions format.
+ * Handles backward compatibility with legacy Metadata parameter.
+ */
+export function normalizeCallOptions<TContext>(
+  options: CallOptions<TContext> | Metadata | undefined,
+): CallOptions<TContext> {
+  if (!options) {
+    return {};
+  }
+
+  if (isCallOptions<TContext>(options)) {
+    return options;
+  }
+
+  // Legacy: raw Metadata object
+  return { metadata: options };
+}