@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/batch-executor.js

@@ -0,0 +1,397 @@
+/**
+ * Batch Executor
+ *
+ * Executes multiple procedure calls with configurable strategies:
+ * - all: Wait for all results
+ * - race: Return first result, and abort the other calls
+ * - stream: Yield results as they arrive
+ *
+ * Each call gets its own abort signal, linked to the signal of the batch. The executor aborts a
+ * call that can no longer change the result: a loser of a race, a call that still runs when the
+ * reader of a stream stops, or (with `continueOnError: false`) every call after the first failure.
+ */
+import { buildResponse } from "./call-types.js";
+/** An abort controller whose signal also aborts when the parent signal aborts. */
+function linkedController(parent) {
+    const controller = new AbortController();
+    if (parent) {
+        if (parent.aborted) {
+            controller.abort(parent.reason);
+        }
+        else {
+            parent.addEventListener("abort", () => controller.abort(parent.reason), { once: true });
+        }
+    }
+    return controller;
+}
+function cancelledResult(path, message) {
+    return { success: false, error: { code: "CANCELLED", message, retryable: false, path } };
+}
+// =============================================================================
+// Batch Executor Class
+// =============================================================================
+/**
+ * Executes batched procedure calls with configurable strategies.
+ *
+ * @example
+ * ```typescript
+ * const executor = new BatchExecutor(execute);
+ *
+ * // Execute all routes in parallel
+ * const result = await executor.executeAll(resolved, context);
+ *
+ * // Stream results as they arrive
+ * for await (const { path, result } of executor.executeStream(resolved, context)) {
+ *   console.log(`${path.join('.')}: ${result.success}`);
+ * }
+ * ```
+ */
+export class BatchExecutor {
+    execute;
+    constructor(execute) {
+        this.execute = execute;
+    }
+    /**
+     * Execute resolved routes with the specified strategy.
+     *
+     * @param resolved - Resolved routes to execute
+     * @param context - Execution context
+     * @param config - Batch configuration
+     * @returns Batch execution result
+     */
+    async executeBatch(resolved, context, config = { strategy: "all" }) {
+        switch (config.strategy) {
+            case "race":
+                return this.executeRace(resolved, context);
+            case "stream":
+                // For non-streaming API, collect all stream results
+                return this.collectStream(resolved, context, config);
+            case "all":
+            default:
+                return this.executeAll(resolved, context, config);
+        }
+    }
+    /**
+     * Execute all routes in parallel and wait for all results. The results are in route order.
+     *
+     * With `continueOnError: false`, the first failure cancels the other calls: each gets a
+     * `CANCELLED` result. By default, every call runs to its end.
+     */
+    async executeAll(resolved, context, config) {
+        // The stream with emitPartial: false holds every result, then gives them in route order
+        return this.collect(this.executeStream(resolved, context, {
+            strategy: "all",
+            ...config,
+            streamConfig: { ...config?.streamConfig, emitPartial: false },
+        }));
+    }
+    /**
+     * Execute routes and return when the first one completes. The executor aborts the other calls.
+     */
+    async executeRace(resolved, context) {
+        const startTime = Date.now();
+        const controllers = resolved.map(() => linkedController(context.signal));
+        const calls = resolved.map((route, index) => this.runOne(route, { ...context, signal: controllers[index].signal }).then((item) => ({ item, index })));
+        const winner = await Promise.race(calls);
+        controllers.forEach((controller, index) => {
+            if (index !== winner.index)
+                controller.abort();
+        });
+        return {
+            response: buildResponse([[winner.item.path, winner.item.result]]),
+            success: winner.item.result.success,
+            duration: Date.now() - startTime,
+            results: [winner.item],
+        };
+    }
+    /**
+     * Execute routes and stream results as they arrive.
+     *
+     * Each completed call goes into a queue, so every result reaches the reader, also when several
+     * calls complete in one tick. (Before, the executor gave only the winner of each
+     * `Promise.race`: the other calls of that tick were lost: deep dive CORE-2.)
+     *
+     * - `streamConfig.concurrency`: the maximum number of calls that run at one time.
+     * - `streamConfig.bufferSize`: when this many results wait for the reader, the executor starts
+     *   no new call. 0 or no value: no limit.
+     * - `streamConfig.emitPartial`: false holds every result, then yields them in route order.
+     * - `continueOnError: false`: the first failure cancels the calls that wait or run.
+     *
+     * When the reader stops early, the executor aborts the calls that still run.
+     */
+    async *executeStream(resolved, context, config) {
+        const concurrency = Math.max(1, config?.streamConfig?.concurrency ?? resolved.length);
+        const emitPartial = config?.streamConfig?.emitPartial ?? true;
+        // A buffer limit with emitPartial: false would stop the batch: the results are never read early
+        const bufferSize = emitPartial ? config?.streamConfig?.bufferSize ?? 0 : 0;
+        const failFast = config?.continueOnError === false;
+        const pending = resolved.map((route, index) => ({ route, index }));
+        const running = new Map();
+        const done = [];
+        let stopped = false;
+        let wake;
+        const notify = () => {
+            const resolve = wake;
+            wake = undefined;
+            resolve?.();
+        };
+        const cancelRest = () => {
+            stopped = true;
+            const message = "Cancelled after another route failed";
+            for (const { route, index } of pending.splice(0)) {
+                done.push({ path: route.path, result: cancelledResult(route.path, message), duration: 0, index });
+            }
+            for (const [index, call] of running) {
+                call.controller.abort();
+                done.push({ path: call.path, result: cancelledResult(call.path, message), duration: 0, index });
+            }
+            running.clear();
+        };
+        const fill = () => {
+            while (!stopped &&
+                pending.length > 0 &&
+                running.size < concurrency &&
+                (bufferSize <= 0 || done.length < bufferSize)) {
+                const { route, index } = pending.shift();
+                const controller = linkedController(context.signal);
+                running.set(index, { path: route.path, controller });
+                void this.runOne(route, { ...context, signal: controller.signal }).then((item) => {
+                    // A cancelled call has its result already
+                    if (!running.delete(index))
+                        return;
+                    done.push({ ...item, index });
+                    if (failFast && !item.result.success)
+                        cancelRest();
+                    fill();
+                    notify();
+                });
+            }
+        };
+        const strip = ({ path, result, duration }) => ({ path, result, duration });
+        try {
+            fill();
+            for (;;) {
+                if (emitPartial && done.length > 0) {
+                    yield strip(done.shift());
+                    fill();
+                    continue;
+                }
+                if (running.size === 0 && (pending.length === 0 || stopped))
+                    break;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+            if (!emitPartial) {
+                done.sort((a, b) => a.index - b.index);
+                for (const item of done.splice(0))
+                    yield strip(item);
+            }
+        }
+        finally {
+            // The reader stopped early, or the batch ended: abort the calls that still run
+            stopped = true;
+            for (const call of running.values())
+                call.controller.abort();
+            running.clear();
+        }
+    }
+    /**
+     * Get a streaming response with both iterator and completion promise.
+     */
+    getStreamingResponse(resolved, context, config) {
+        const results = [];
+        const stream = this.executeStream(resolved, context, config);
+        // One pump consumes the stream. The results iterator reads the items from a buffer, so
+        // every item reaches both the iterator and the final response. (BUGS-2026-07 H12: the
+        // iterator and the completion promise each iterated the same generator, so they split
+        // the items between them.)
+        const buffered = [];
+        let finished = false;
+        let failure;
+        let wake;
+        const notify = () => {
+            const resolve = wake;
+            wake = undefined;
+            resolve?.();
+        };
+        const complete = (async () => {
+            try {
+                for await (const item of stream) {
+                    results.push([item.path, item.result]);
+                    buffered.push(item);
+                    notify();
+                }
+            }
+            catch (error) {
+                failure = { error };
+                throw error;
+            }
+            finally {
+                finished = true;
+                notify();
+            }
+            return buildResponse(results);
+        })();
+        // A caller that only uses the iterator still sees the failure there
+        complete.catch(() => { });
+        const iterate = async function* () {
+            let index = 0;
+            for (;;) {
+                if (index < buffered.length) {
+                    yield buffered[index++];
+                    continue;
+                }
+                if (finished) {
+                    if (failure)
+                        throw failure.error;
+                    return;
+                }
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+        };
+        return {
+            results: iterate(),
+            complete,
+        };
+    }
+    /**
+     * Collect stream results into a batch result.
+     */
+    async collectStream(resolved, context, config) {
+        return this.collect(this.executeStream(resolved, context, config));
+    }
+    async collect(items) {
+        const startTime = Date.now();
+        const results = [];
+        for await (const item of items) {
+            results.push(item);
+        }
+        return {
+            response: buildResponse(results.map(({ path, result }) => [path, result])),
+            success: results.every((r) => r.result.success),
+            duration: Date.now() - startTime,
+            results,
+        };
+    }
+    /** Run one call. The result is never a rejection: an exception becomes an error result. */
+    async runOne(route, context) {
+        const callStart = Date.now();
+        try {
+            const result = await this.execute(route, context);
+            return { path: route.path, result, duration: Date.now() - callStart };
+        }
+        catch (error) {
+            return { path: route.path, result: this.createErrorResult(route.path, error), duration: Date.now() - callStart };
+        }
+    }
+    /**
+     * Create an error result from an exception.
+     */
+    createErrorResult(path, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof Error && "code" in error
+            ? String(error.code)
+            : "EXECUTION_ERROR";
+        return {
+            success: false,
+            error: {
+                code,
+                message,
+                retryable: false,
+                path,
+            },
+        };
+    }
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a batch executor with a procedure executor function.
+ *
+ * @param execute - Function that executes a single procedure
+ * @returns Batch executor instance
+ */
+export function createBatchExecutor(execute) {
+    return new BatchExecutor(execute);
+}
+/**
+ * Determine the optimal batch strategy based on route count and config.
+ *
+ * @param routeCount - Number of routes to execute
+ * @param config - User-provided batch config
+ * @returns Effective batch strategy
+ */
+export function determineStrategy(routeCount, config) {
+    if (config?.strategy) {
+        return config.strategy;
+    }
+    // Default: single route doesn't need batching
+    if (routeCount === 1) {
+        return "all";
+    }
+    // Default for multiple routes
+    return "all";
+}
+// =============================================================================
+// Concurrency Control
+// =============================================================================
+/**
+ * Semaphore for limiting concurrent executions.
+ */
+export class Semaphore {
+    permits;
+    waiting = [];
+    constructor(permits) {
+        this.permits = permits;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        return new Promise((resolve) => {
+            this.waiting.push(resolve);
+        });
+    }
+    release() {
+        if (this.waiting.length > 0) {
+            const next = this.waiting.shift();
+            next();
+        }
+        else {
+            this.permits++;
+        }
+    }
+    async withPermit(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+/**
+ * Execute procedures with concurrency limit.
+ *
+ * @param resolved - Routes to execute
+ * @param execute - Executor function
+ * @param context - Execution context
+ * @param concurrency - Maximum concurrent executions
+ * @returns Array of results
+ */
+export async function executeWithConcurrency(resolved, execute, context, concurrency) {
+    const semaphore = new Semaphore(concurrency);
+    const results = [];
+    await Promise.all(resolved.map(async (route) => {
+        const result = await semaphore.withPermit(() => execute(route, context));
+        results.push({ path: route.path, result });
+    }));
+    return results;
+}
+//# sourceMappingURL=batch-executor.js.map

package/dist/client/batch-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-executor.js","sourceRoot":"","sources":["../../src/client/batch-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgDhD,kFAAkF;AAClF,SAAS,gBAAgB,CAAC,MAA+B;IACvD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,eAAe,CAAC,IAAmB,EAAE,OAAe;IAC3D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;AAC3F,CAAC;AAED,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAa;IACK,OAAO;IAApC,YAA6B,OAA0B;uBAA1B,OAAO;IAAsB,CAAC;IAE3D;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,QAAyB,EACzB,OAAyB,EACzB,MAAM,GAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAEzC,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxB,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,WAAW,CAAS,QAAQ,EAAE,OAAO,CAAC,CAAC;YACrD,KAAK,QAAQ;gBACX,oDAAoD;gBACpD,OAAO,IAAI,CAAC,aAAa,CAAS,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC/D,KAAK,KAAK,CAAC;YACX;gBACE,OAAO,IAAI,CAAC,UAAU,CAAS,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CACd,QAAyB,EACzB,OAAyB,EACzB,MAAoB;QAEpB,wFAAwF;QACxF,OAAO,IAAI,CAAC,OAAO,CACjB,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE;YACpC,QAAQ,EAAE,KAAK;YACf,GAAG,MAAM;YACT,YAAY,EAAE,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE;SAC9D,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAyB,EACzB,OAAyB;QAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACzE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAC1C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,CAAE,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CACzG,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE;YACxC,IAAI,KAAK,KAAK,MAAM,CAAC,KAAK;gBAAE,UAAU,CAAC,KAAK,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,QAAQ,EAAE,aAAa,CAAS,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACzE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;YACnC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAChC,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;SACvB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,aAAa,CAClB,QAAyB,EACzB,OAAyB,EACzB,MAAoB;QAEpB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtF,MAAM,WAAW,GAAG,MAAM,EAAE,YAAY,EAAE,WAAW,IAAI,IAAI,CAAC;QAC9D,gGAAgG;QAChG,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,MAAM,EAAE,eAAe,KAAK,KAAK,CAAC;QAEnD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgE,CAAC;QACxF,MAAM,IAAI,GAAyC,EAAE,CAAC;QACtD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,IAA8B,CAAC;QACnC,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC;YACrB,IAAI,GAAG,SAAS,CAAC;YACjB,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,UAAU,GAAG,GAAS,EAAE;YAC5B,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,OAAO,GAAG,sCAAsC,CAAC;YACvD,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YACpG,CAAC;YACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;gBACpC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBACxB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAClG,CAAC;YACD,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC,CAAC;QAEF,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,OACE,CAAC,OAAO;gBACR,OAAO,CAAC,MAAM,GAAG,CAAC;gBAClB,OAAO,CAAC,IAAI,GAAG,WAAW;gBAC1B,CAAC,UAAU,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,EAC7C,CAAC;gBACD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAG,CAAC;gBAC1C,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpD,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;gBACrD,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;oBAC/E,0CAA0C;oBAC1C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;wBAAE,OAAO;oBACnC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBAC9B,IAAI,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;wBAAE,UAAU,EAAE,CAAC;oBACnD,IAAI,EAAE,CAAC;oBACP,MAAM,EAAE,CAAC;gBACX,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAiC,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAErH,IAAI,CAAC;YACH,IAAI,EAAE,CAAC;YACP,SAAS,CAAC;gBACR,IAAI,WAAW,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACnC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAG,CAAC,CAAC;oBAC3B,IAAI,EAAE,CAAC;oBACP,SAAS;gBACX,CAAC;gBACD,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC;oBAAE,MAAM;gBACnE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;oBAClC,IAAI,GAAG,OAAO,CAAC;gBACjB,CAAC,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;gBACvC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;oBAAE,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,+EAA+E;YAC/E,OAAO,GAAG,IAAI,CAAC;YACf,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YAC7D,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,oBAAoB,CAClB,QAAyB,EACzB,OAAyB,EACzB,MAAoB;QAEpB,MAAM,OAAO,GAAgD,EAAE,CAAC;QAChE,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE7D,uFAAuF;QACvF,sFAAsF;QACtF,sFAAsF;QACtF,2BAA2B;QAC3B,MAAM,QAAQ,GAAgB,EAAE,CAAC;QACjC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAuC,CAAC;QAC5C,IAAI,IAA8B,CAAC;QACnC,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC;YACrB,IAAI,GAAG,SAAS,CAAC;YACjB,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC3B,IAAI,CAAC;gBACH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;oBAChC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;oBACvC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,MAAM,EAAE,CAAC;gBACX,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,QAAQ,GAAG,IAAI,CAAC;gBAChB,MAAM,EAAE,CAAC;YACX,CAAC;YACD,OAAO,aAAa,CAAS,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,EAAE,CAAC;QACL,oEAAoE;QACpE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEzB,MAAM,OAAO,GAAG,KAAK,SAAS,CAAC;YAC7B,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,SAAS,CAAC;gBACR,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;oBAC5B,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAE,CAAC;oBACzB,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,EAAE,CAAC;oBACb,IAAI,OAAO;wBAAE,MAAM,OAAO,CAAC,KAAK,CAAC;oBACjC,OAAO;gBACT,CAAC;gBACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;oBAClC,IAAI,GAAG,OAAO,CAAC;gBACjB,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,OAAO,EAAE;YAClB,QAAQ;SACT,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,aAAa,CACzB,QAAyB,EACzB,OAAyB,EACzB,MAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAS,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7E,CAAC;IAEO,KAAK,CAAC,OAAO,CAAuB,KAA+B;QACzE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,aAAa,CAAS,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YAClF,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YAC/C,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAChC,OAAO;SACR,CAAC;IACJ,CAAC;IAED,2FAA2F;IACnF,KAAK,CAAC,MAAM,CAAC,KAAoB,EAAE,OAAyB;QAClE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAClD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;QACxE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;QACnH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,IAAmB,EAAE,KAAc;QAC3D,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK;YACpD,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YACpB,CAAC,CAAC,iBAAiB,CAAC;QAEtB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI;gBACJ,OAAO;gBACP,SAAS,EAAE,KAAK;gBAChB,IAAI;aACL;SACF,CAAC;IACJ,CAAC;CACF;AAED,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,MAAoB;IAEpB,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;QACrB,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,8CAA8C;IAC9C,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8BAA8B;IAC9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,SAAS;IACZ,OAAO,CAAS;IAChB,OAAO,GAAsB,EAAE,CAAC;IAExC,YAAY,OAAe;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAG,CAAC;YACnC,IAAI,EAAE,CAAC;QACT,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,EAAoB;QACtC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAyB,EACzB,OAA0B,EAC1B,OAAyB,EACzB,WAAmB;IAEnB,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAgE,EAAE,CAAC;IAEhF,MAAM,OAAO,CAAC,GAAG,CACf,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/client/call-types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 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";
+export type { RouteLeaf, RouteLeafWithConfig, OutputConfig } from "./consumption.js";
+export { isRouteLeafWithConfig, extractInput, extractOutputConfig } from "./consumption.js";
+/**
+ * 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 declare function toMiddlewareContext(overrides: MiddlewareOverrides | undefined): Record<string, unknown>;
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+}
+/**
+ * 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>>;
+}
+/**
+ * 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;
+/**
+ * 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 declare function assertRouteKey(key: string): void;
+/**
+ * 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 declare function flattenRoute(route: Route): FlattenedRouteEntry[];
+/**
+ * Legacy flatten function for backward compatibility.
+ * Returns [path, leaf] pairs without output config extraction.
+ *
+ * @deprecated Use flattenRoute() which returns FlattenedRouteEntry[]
+ */
+export declare function flattenRouteLegacy(route: Route): Array<[ProcedurePath, RouteLeaf]>;
+/**
+ * Build a nested response structure from flat results.
+ *
+ * @param results - Array of [path, result] tuples
+ * @returns Nested response object
+ */
+export declare function buildResponse<TRoute extends Route>(results: Array<[ProcedurePath, ProcedureCallResult]>): 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 declare function isBatchRoute(route: Route): boolean;
+/**
+ * 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 declare function createRoute<TInput extends RouteLeaf>(path: ProcedurePath, input: TInput): Route;
+/**
+ * Merge multiple routes into a single batched route.
+ *
+ * @param routes - Routes to merge
+ * @returns Merged route
+ */
+export declare function mergeRoutes(...routes: Route[]): Route;
+//# sourceMappingURL=call-types.d.ts.map