@cratestack/link-batch 0.5.2 → 0.6.3

package/README.md

@@ -33,21 +33,40 @@ const [a, b, c] = await Promise.all([
 
 - **Window**: defaults to `queueMicrotask` — calls fired synchronously in the same tick (e.g.
   inside `Promise.all`) collapse. Pass `windowMs` to widen the window across ticks.
+- **Partitioning** (fixed in [#273](https://github.com/cratestack/cratestack/issues/273); versions
+  before this carried a bug here — see "Known limitations" below): each flush is split into
+  partitions by transport envelope — headers (excluding `Idempotency-Key`, which is carried
+  per-frame, not per-request), `fetch` reference, codec reference, and the resolved batch URL —
+  and every partition is sent as its own `POST /rpc/batch`. Calls that share an envelope, the
+  overwhelmingly common case, still collapse into exactly one request; calls that don't (e.g. two
+  different `Authorization` headers) each keep their own, in a separate request, rather than one
+  silently overwriting the other's.
+- **Aggregate headers**: pass `headers` to `createBatchLink({ headers })` to declare headers that
+  every synthesized `/rpc/batch` request carries, merged **over** each partition's own — a
+  same-named per-call header is overridden by this value, not the other way around. Use this for
+  service-level headers (e.g. an API key) rather than per-tenant auth, which should come from
+  per-call headers that drive partitioning.
+- **`maxBatchSize`** is enforced **per partition**, not globally across the flush — a single
+  oversized partition chunks into several concurrent requests; it never borrows headroom from a
+  different partition.
 - **Dedup**: only calls sharing an explicit `idempotencyKey` are collapsed into one request frame
   by default — that's already the caller's own signal that the call is a safe repeat. Calls with
   no idempotency key are never auto-collapsed, since the server does no dedup of its own and
   silently merging two textually-identical but unmarked mutations would be unsafe. Pass a custom
-  `dedupe` for full value-based collapsing, or `() => null` to disable dedup and only batch.
+  `dedupe` for full value-based collapsing, or `() => null` to disable dedup and only batch. Dedup
+  runs *within* a partition — it never collapses calls across two different envelopes.
 - **Correlation**: results are fanned back out by matching each response frame's `id`, not array
   position — the server's `/rpc/batch` contract already guarantees order (see
   `docs/design/rpc-transport.md` §3.2), but id-based matching is strictly more robust and mirrors
   the repo's own Rust client-side batch debouncer (`examples/rpc-batch-debounce`).
+- **Failure isolation**: a partition that fails (network error, non-OK response) only rejects the
+  callers queued in *that* partition — it never affects a concurrently in-flight partition.
 
 ### Known limitations
 
-- The synthesized `/rpc/batch` request reuses the **first** queued call's `headers`/`fetchFn`/
-  `codec` for the whole flush — per-call custom headers on later calls in the same window are not
-  applied to the aggregate request. Pass shared headers via the runtime's own `headers` option
-  rather than per-call `CratestackRpcCallOptions.headers` when using this link.
 - Aborting an individual call's `AbortSignal` only cancels it if its batch hasn't been sent yet —
   it does not cancel an in-flight `/rpc/batch` request.
+- **(Fixed in #273, kept here for anyone reading an older version's docs)** Before #273, the
+  synthesized `/rpc/batch` request reused the *first* queued call's `headers`/`fetchFn`/`codec` for
+  the whole flush — per-call custom headers on later calls in the same window were silently dropped
+  from the aggregate request instead of applied. This is why partitioning exists now.

package/dist/correlate.d.ts

@@ -0,0 +1,10 @@
+import type { RpcLinkRequest, RpcResponseFrame } from "@cratestack/ts-types";
+import type { Group, QueueEntry } from "./types.js";
+/** Collapses entries that share a non-null dedupe key into one frame.
+ *  Runs *within* a partition — this is frame-level dedup, distinct from
+ *  the request-level split in `./signature`. */
+export declare function groupByDedupeKey(entries: QueueEntry[], dedupe: (request: RpcLinkRequest) => string | null): Group[];
+/** Fans a decoded `/rpc/batch` response back out to each queued caller. */
+export declare function resolveGroups(groups: Group[], frames: RpcResponseFrame[]): void;
+export declare function errorStatus(code: string): number;
+//# sourceMappingURL=correlate.d.ts.map

package/dist/correlate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlate.d.ts","sourceRoot":"","sources":["../src/correlate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpD;;gDAEgD;AAChD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,GACjD,KAAK,EAAE,CAkBT;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAqC/E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBhD"}

package/dist/correlate.js

@@ -0,0 +1,79 @@
+/** Collapses entries that share a non-null dedupe key into one frame.
+ *  Runs *within* a partition — this is frame-level dedup, distinct from
+ *  the request-level split in `./signature`. */
+export function groupByDedupeKey(entries, dedupe) {
+    const groups = [];
+    const indexByKey = new Map();
+    for (const entry of entries) {
+        const key = dedupe(entry.request);
+        if (key === null) {
+            groups.push({ key: null, entries: [entry] });
+            continue;
+        }
+        const existingIndex = indexByKey.get(key);
+        if (existingIndex === undefined) {
+            indexByKey.set(key, groups.length);
+            groups.push({ key, entries: [entry] });
+        }
+        else {
+            groups[existingIndex].entries.push(entry);
+        }
+    }
+    return groups;
+}
+/** Fans a decoded `/rpc/batch` response back out to each queued caller. */
+export function resolveGroups(groups, frames) {
+    // Correlate by `id`, not array position — the server contract
+    // guarantees order (docs/design/rpc-transport.md §3.2), but matching
+    // by id is strictly more robust and is the pattern the repo's own
+    // Rust client-side batch debouncer already establishes
+    // (examples/rpc-batch-debounce/src/lib.rs's `responders` map).
+    const frameById = new Map(frames.map((frame) => [frame.id, frame]));
+    groups.forEach((group, id) => {
+        const frame = frameById.get(id);
+        if (!frame) {
+            const error = new Error(`batch response is missing frame id ${id}`);
+            for (const entry of group.entries) {
+                entry.reject(error);
+            }
+            return;
+        }
+        const hasError = frame.error !== undefined;
+        for (const entry of group.entries) {
+            if (!hasError && frame.output === undefined) {
+                // Mirrors the unary path's `response.status === 204` shortcut
+                // (void-returning calls resolve `undefined`, not a decoded null).
+                entry.resolve({ response: new Response(null, { status: 204 }) });
+                continue;
+            }
+            const body = hasError ? frame.error : frame.output;
+            // Re-encoded with the *caller's own* codec, not the batch's — the
+            // caller's generated runtime decodes this synthetic response with
+            // the codec it was constructed with, which an `options.codec`
+            // override on this link must not change.
+            entry.resolve({
+                response: new Response(entry.request.codec.encode(body), {
+                    status: hasError ? errorStatus(frame.error.code) : 200,
+                }),
+            });
+        }
+    });
+}
+export function errorStatus(code) {
+    switch (code) {
+        case "invalid_argument":
+        case "failed_precondition":
+            return 400;
+        case "unauthenticated":
+            return 401;
+        case "permission_denied":
+            return 403;
+        case "not_found":
+            return 404;
+        case "conflict":
+            return 409;
+        default:
+            return 500;
+    }
+}
+//# sourceMappingURL=correlate.js.map

package/dist/correlate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlate.js","sourceRoot":"","sources":["../src/correlate.ts"],"names":[],"mappings":"AAGA;;gDAEgD;AAChD,MAAM,UAAU,gBAAgB,CAC9B,OAAqB,EACrB,MAAkD;IAElD,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC7C,SAAS;QACX,CAAC;QACD,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,aAAa,CAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,MAAe,EAAE,MAA0B;IACvE,8DAA8D;IAC9D,qEAAqE;IACrE,kEAAkE;IAClE,uDAAuD;IACvD,+DAA+D;IAC/D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,sCAAsC,EAAE,EAAE,CAAC,CAAC;YACpE,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC5C,8DAA8D;gBAC9D,kEAAkE;gBAClE,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBACjE,SAAS;YACX,CAAC;YACD,MAAM,IAAI,GAA2B,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;YAC3E,kEAAkE;YAClE,kEAAkE;YAClE,8DAA8D;YAC9D,yCAAyC;YACzC,KAAK,CAAC,OAAO,CAAC;gBACZ,QAAQ,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;oBACvD,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,KAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG;iBACxD,CAAC;aACH,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,kBAAkB,CAAC;QACxB,KAAK,qBAAqB;YACxB,OAAO,GAAG,CAAC;QACb,KAAK,iBAAiB;YACpB,OAAO,GAAG,CAAC;QACb,KAAK,mBAAmB;YACtB,OAAO,GAAG,CAAC;QACb,KAAK,WAAW;YACd,OAAO,GAAG,CAAC;QACb,KAAK,UAAU;YACb,OAAO,GAAG,CAAC;QACb;YACE,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { RpcLinkRequest } from "@cratestack/ts-types";
+import type { EffectiveConfig, QueueEntry } from "./types.js";
+/** Sends one partition as a single `POST /rpc/batch` and settles every
+ *  caller in it. A partition's entries share `config` by construction
+ *  (see `./signature`), so nothing here is inherited from an arbitrary
+ *  "first" call — the pre-partitioning behavior this replaces. */
+export declare function dispatchPartition(entries: QueueEntry[], config: EffectiveConfig, dedupe: (request: RpcLinkRequest) => string | null): Promise<void>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAgC,MAAM,sBAAsB,CAAC;AAEzF,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE9D;;;kEAGkE;AAClE,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,GACjD,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/dispatch.js

@@ -0,0 +1,46 @@
+import { groupByDedupeKey, resolveGroups } from "./correlate.js";
+/** Sends one partition as a single `POST /rpc/batch` and settles every
+ *  caller in it. A partition's entries share `config` by construction
+ *  (see `./signature`), so nothing here is inherited from an arbitrary
+ *  "first" call — the pre-partitioning behavior this replaces. */
+export async function dispatchPartition(entries, config, dedupe) {
+    const groups = groupByDedupeKey(entries, dedupe);
+    const requests = groups.map((group, id) => {
+        const request = group.entries[0].request;
+        const frame = { id, op: request.opId, input: request.input };
+        if (request.idempotencyKey !== undefined) {
+            frame.idem = request.idempotencyKey;
+        }
+        return frame;
+    });
+    try {
+        const response = await config.fetchFn(config.batchUrl, {
+            method: "POST",
+            headers: config.headers,
+            body: config.codec.encode(requests),
+            signal: null,
+        });
+        if (!response.ok) {
+            const bytes = new Uint8Array(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
+            for (const group of groups) {
+                for (const entry of group.entries) {
+                    entry.resolve({ response: new Response(bytes, { status: response.status }) });
+                }
+            }
+            return;
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const frames = config.codec.decode(bytes);
+        resolveGroups(groups, frames);
+    }
+    catch (error) {
+        // Scoped to this partition only — a failure here never settles a
+        // caller queued under a different transport config.
+        for (const group of groups) {
+            for (const entry of group.entries) {
+                entry.reject(error);
+            }
+        }
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE;;;kEAGkE;AAClE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAqB,EACrB,MAAuB,EACvB,MAAkD;IAElD,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEjD,MAAM,QAAQ,GAAiB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QACtD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC;QAC1C,MAAM,KAAK,GAAe,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACzE,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC;QACtC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;YACnC,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3F,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBAClC,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAuB,CAAC;QAChE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iEAAiE;QACjE,oDAAoD;QACpD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,51 +1,27 @@
-import type { RpcLink, RpcLinkRequest } from "@cratestack/ts-types";
-export interface BatchLinkOptions {
-    /** Scheduling window. Omitted (default) uses `queueMicrotask` — calls
-     *  fired synchronously in the same tick (e.g. inside `Promise.all`)
-     *  collapse into one `/rpc/batch` request. Pass a millisecond value to
-     *  widen the window across ticks (e.g. debounce bursts from unrelated
-     *  components). */
-    windowMs?: number;
-    /** Maximum requests per flushed `/rpc/batch` call. Default: unbounded
-     *  — the server enforces no size limit either (see
-     *  `docs/design/rpc-transport.md` §3.2), but a huge fan-in may still
-     *  be worth capping client-side. */
-    maxBatchSize?: number;
-    /** Returns a dedupe key for a queued call, or `null` to never
-     *  collapse it with anything else. Two calls in the same flush that
-     *  return the same non-null key become ONE `/rpc/batch` frame, and
-     *  every caller resolves from that single result.
-     *
-     *  Default: only collapse calls that share an explicit
-     *  `idempotencyKey` — that's already the caller's own signal that the
-     *  call is safe to treat as a repeat. Calls with no idempotency key
-     *  are never auto-collapsed, since the server does no dedup of its
-     *  own and silently merging two textually-identical but unmarked
-     *  mutations would be unsafe. Pass a custom `dedupe` for full
-     *  value-based batshit-style collapsing (e.g.
-     *  `req => \`${req.opId}:${JSON.stringify(req.input)}\``), or
-     *  `() => null` to disable dedup entirely and only batch.
-     */
-    dedupe?: (request: RpcLinkRequest) => string | null;
-}
+import type { RpcLink } from "@cratestack/ts-types";
+import type { BatchLinkOptions } from "./types.js";
+export { batchSignature, effectiveConfig } from "./signature.js";
+export type { BatchLinkOptions } from "./types.js";
 /** A batshit-style (github.com/yornaath/batshit) automatic batch
  *  scheduler, shipped as an `RpcLink` (issue #182's composition
  *  mechanism) rather than a `fetch` override — so it composes with a
  *  logger, retry, or auth-refresh link instead of clobbering them.
  *
  *  Terminal in practice: for `kind: "unary"` calls it never invokes
- *  `next` — it queues the call and later performs its own single
- *  `POST /rpc/batch`. An explicit `runtime.batch()` call (`kind:
- *  "batch"`) passes straight through via `next`, since it's already
- *  the shape this link would otherwise build.
+ *  `next` — it queues the call and later performs its own
+ *  `POST /rpc/batch` requests. An explicit `runtime.batch()` call
+ *  (`kind: "batch"`) passes straight through via `next`, since it's
+ *  already the shape this link would otherwise build.
  *
- *  Known limitation: the synthesized `/rpc/batch` request reuses the
- *  first queued call's `headers`/`fetchFn`/`codec` for the whole flush
- *  — per-call custom headers on later calls in the same window are not
- *  applied to the aggregate request. Pass shared headers via the
- *  runtime's own `headers` option rather than per-call
- *  `CratestackRpcCallOptions.headers` when using this link. Similarly,
- *  aborting an individual call's `AbortSignal` only cancels it if the
- *  flush hasn't been sent yet — it does not cancel an in-flight batch. */
+ *  Each flush is split into partitions by transport config — headers,
+ *  `fetch`, codec, batch URL (see `batchSignature`) — and every
+ *  partition is sent as its own request, so no call's headers are ever
+ *  dropped in favor of another's (issue #273). Calls sharing a config,
+ *  which is the overwhelmingly common case, still collapse into exactly
+ *  one request.
+ *
+ *  Known limitation: aborting an individual call's `AbortSignal` only
+ *  cancels it if the flush hasn't been sent yet — it does not cancel an
+ *  in-flight batch. */
 export declare function createBatchLink(options?: BatchLinkOptions): RpcLink;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,OAAO,EACP,cAAc,EAIf,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B;;;;uBAImB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;wCAGoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,CAAC;CACrD;AAgBD;;;;;;;;;;;;;;;;;;0EAkB0E;AAC1E,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAyGvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAmC,MAAM,sBAAsB,CAAC;AAGrF,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD;;;;;;;;;;;;;;;;;;;;uBAoBuB;AACvB,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAkEvE"}

package/dist/index.js

@@ -1,3 +1,6 @@
+import { dispatchPartition } from "./dispatch.js";
+import { partition } from "./signature.js";
+export { batchSignature, effectiveConfig } from "./signature.js";
 const defaultDedupe = (request) => request.idempotencyKey !== undefined ? `idem:${request.idempotencyKey}` : null;
 /** A batshit-style (github.com/yornaath/batshit) automatic batch
  *  scheduler, shipped as an `RpcLink` (issue #182's composition
@@ -5,21 +8,23 @@ const defaultDedupe = (request) => request.idempotencyKey !== undefined ? `idem:
  *  logger, retry, or auth-refresh link instead of clobbering them.
  *
  *  Terminal in practice: for `kind: "unary"` calls it never invokes
- *  `next` — it queues the call and later performs its own single
- *  `POST /rpc/batch`. An explicit `runtime.batch()` call (`kind:
- *  "batch"`) passes straight through via `next`, since it's already
- *  the shape this link would otherwise build.
+ *  `next` — it queues the call and later performs its own
+ *  `POST /rpc/batch` requests. An explicit `runtime.batch()` call
+ *  (`kind: "batch"`) passes straight through via `next`, since it's
+ *  already the shape this link would otherwise build.
  *
- *  Known limitation: the synthesized `/rpc/batch` request reuses the
- *  first queued call's `headers`/`fetchFn`/`codec` for the whole flush
- *  — per-call custom headers on later calls in the same window are not
- *  applied to the aggregate request. Pass shared headers via the
- *  runtime's own `headers` option rather than per-call
- *  `CratestackRpcCallOptions.headers` when using this link. Similarly,
- *  aborting an individual call's `AbortSignal` only cancels it if the
- *  flush hasn't been sent yet — it does not cancel an in-flight batch. */
+ *  Each flush is split into partitions by transport config — headers,
+ *  `fetch`, codec, batch URL (see `batchSignature`) — and every
+ *  partition is sent as its own request, so no call's headers are ever
+ *  dropped in favor of another's (issue #273). Calls sharing a config,
+ *  which is the overwhelmingly common case, still collapse into exactly
+ *  one request.
+ *
+ *  Known limitation: aborting an individual call's `AbortSignal` only
+ *  cancels it if the flush hasn't been sent yet — it does not cancel an
+ *  in-flight batch. */
 export function createBatchLink(options = {}) {
-    const maxBatchSize = options.maxBatchSize ?? Number.POSITIVE_INFINITY;
+    const maxBatchSize = Math.max(1, options.maxBatchSize ?? Number.POSITIVE_INFINITY);
     const dedupe = options.dedupe ?? defaultDedupe;
     const windowMs = options.windowMs;
     const queue = [];
@@ -44,49 +49,14 @@ export function createBatchLink(options = {}) {
         if (queue.length === 0) {
             return;
         }
-        const size = Math.max(1, maxBatchSize);
-        const batch = queue.splice(0, size);
-        if (queue.length > 0) {
-            scheduleFlush();
-        }
-        void runBatch(batch);
-    }
-    async function runBatch(entries) {
-        const groups = groupByDedupeKey(entries, dedupe);
-        const leader = entries[0].request;
-        const requests = groups.map((group, id) => {
-            const request = group.entries[0].request;
-            const frame = { id, op: request.opId, input: request.input };
-            if (request.idempotencyKey !== undefined) {
-                frame.idem = request.idempotencyKey;
-            }
-            return frame;
-        });
-        try {
-            const response = await leader.fetchFn(leader.urls.batch(), {
-                method: "POST",
-                headers: leader.headers,
-                body: leader.codec.encode(requests),
-                signal: null,
-            });
-            if (!response.ok) {
-                const bytes = new Uint8Array(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
-                for (const group of groups) {
-                    for (const entry of group.entries) {
-                        entry.resolve({ response: new Response(bytes, { status: response.status }) });
-                    }
-                }
-                return;
-            }
-            const bytes = new Uint8Array(await response.arrayBuffer());
-            const frames = leader.codec.decode(bytes);
-            resolveGroups(groups, frames);
-        }
-        catch (error) {
-            for (const group of groups) {
-                for (const entry of group.entries) {
-                    entry.reject(error);
-                }
+        // Drain the whole queue, then split it. Chunks are dispatched
+        // concurrently rather than rescheduled onto later ticks: the set of
+        // requests issued is identical either way, and firing them together
+        // avoids serializing an oversized fan-in behind its own window.
+        const pending = queue.splice(0, queue.length);
+        for (const part of partition(pending, options)) {
+            for (let i = 0; i < part.entries.length; i += maxBatchSize) {
+                void dispatchPartition(part.entries.slice(i, i + maxBatchSize), part.config, dedupe);
             }
         }
     }
@@ -114,74 +84,4 @@ export function createBatchLink(options = {}) {
         });
     };
 }
-function groupByDedupeKey(entries, dedupe) {
-    const groups = [];
-    const indexByKey = new Map();
-    for (const entry of entries) {
-        const key = dedupe(entry.request);
-        if (key === null) {
-            groups.push({ key: null, entries: [entry] });
-            continue;
-        }
-        const existingIndex = indexByKey.get(key);
-        if (existingIndex === undefined) {
-            indexByKey.set(key, groups.length);
-            groups.push({ key, entries: [entry] });
-        }
-        else {
-            groups[existingIndex].entries.push(entry);
-        }
-    }
-    return groups;
-}
-function resolveGroups(groups, frames) {
-    // Correlate by `id`, not array position — the server contract
-    // guarantees order (docs/design/rpc-transport.md §3.2), but matching
-    // by id is strictly more robust and is the pattern the repo's own
-    // Rust client-side batch debouncer already establishes
-    // (examples/rpc-batch-debounce/src/lib.rs's `responders` map).
-    const frameById = new Map(frames.map((frame) => [frame.id, frame]));
-    groups.forEach((group, id) => {
-        const frame = frameById.get(id);
-        if (!frame) {
-            const error = new Error(`batch response is missing frame id ${id}`);
-            for (const entry of group.entries) {
-                entry.reject(error);
-            }
-            return;
-        }
-        const hasError = frame.error !== undefined;
-        for (const entry of group.entries) {
-            if (!hasError && frame.output === undefined) {
-                // Mirrors the unary path's `response.status === 204` shortcut
-                // (void-returning calls resolve `undefined`, not a decoded null).
-                entry.resolve({ response: new Response(null, { status: 204 }) });
-                continue;
-            }
-            const body = hasError ? frame.error : frame.output;
-            entry.resolve({
-                response: new Response(entry.request.codec.encode(body), {
-                    status: hasError ? errorStatus(frame.error.code) : 200,
-                }),
-            });
-        }
-    });
-}
-function errorStatus(code) {
-    switch (code) {
-        case "invalid_argument":
-        case "failed_precondition":
-            return 400;
-        case "unauthenticated":
-            return 401;
-        case "permission_denied":
-            return 403;
-        case "not_found":
-            return 404;
-        case "conflict":
-            return 409;
-        default:
-            return 500;
-    }
-}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/signature.d.ts

@@ -0,0 +1,25 @@
+import type { RpcLinkRequest } from "@cratestack/ts-types";
+import type { BatchLinkOptions, EffectiveConfig, QueueEntry } from "./types.js";
+/** Resolves the transport config a request would actually be sent with,
+ *  applying any link-level overrides on top of the request's own. */
+export declare function effectiveConfig(request: RpcLinkRequest, options: BatchLinkOptions): EffectiveConfig;
+/** A stable key identifying which queued calls may share one
+ *  `/rpc/batch` request. Two calls batch together only when every part
+ *  of their transport envelope matches: headers, `fetch`, codec, and
+ *  the resolved batch URL.
+ *
+ *  The URL is included because nothing stops one `createBatchLink()`
+ *  instance from being passed to two runtimes pointing at different
+ *  origins; without it, calls to one service would be merged into a
+ *  request sent to the other. */
+export declare function batchSignature(config: EffectiveConfig): string;
+/** Splits a flush into partitions that may each be sent as one
+ *  `/rpc/batch` request. Insertion order is preserved within every
+ *  partition, and partitions are returned in first-seen order, so a
+ *  flush whose calls all share a config behaves exactly as it did
+ *  before partitioning existed. */
+export declare function partition(entries: QueueEntry[], options: BatchLinkOptions): {
+    config: EffectiveConfig;
+    entries: QueueEntry[];
+}[];
+//# sourceMappingURL=signature.d.ts.map

package/dist/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgBhF;qEACqE;AACrE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,gBAAgB,GACxB,eAAe,CAcjB;AAED;;;;;;;;iCAQiC;AACjC,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAO9D;AAoCD;;;;mCAImC;AACnC,wBAAgB,SAAS,CACvB,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,EAAE,gBAAgB,GACxB;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,EAAE,CAiBtD"}

package/dist/signature.js

@@ -0,0 +1,100 @@
+// Carried per *frame* in the `/rpc/batch` payload (`RpcRequest.idem`),
+// not per request — the generated runtime writes the caller's
+// `idempotencyKey` into BOTH the per-call `Idempotency-Key` header and
+// the frame, so including it in the signature would put every distinct
+// key in its own partition and defeat batching entirely for exactly the
+// calls the dedup feature exists to serve. See
+// `rpc-runtime.ts.j2`'s `call()`.
+const FRAME_LEVEL_HEADERS = new Set(["idempotency-key"]);
+// Field separators that cannot appear in a header name or value, so
+// distinct configs cannot collide into one signature string.
+const FIELD = "\u0000";
+const ENTRY = "\u0001";
+/** Resolves the transport config a request would actually be sent with,
+ *  applying any link-level overrides on top of the request's own. */
+export function effectiveConfig(request, options) {
+    const headers = new Headers(request.headers);
+    if (options.headers) {
+        // `options.headers` OVERRIDES same-named request headers, not the
+        // other way around — `.set()` here, applied after seeding `headers`
+        // from the request, is what makes link-level config win.
+        new Headers(options.headers).forEach((value, key) => headers.set(key, value));
+    }
+    return {
+        headers,
+        fetchFn: options.fetchFn ?? request.fetchFn,
+        codec: options.codec ?? request.codec,
+        batchUrl: request.urls.batch(),
+    };
+}
+/** A stable key identifying which queued calls may share one
+ *  `/rpc/batch` request. Two calls batch together only when every part
+ *  of their transport envelope matches: headers, `fetch`, codec, and
+ *  the resolved batch URL.
+ *
+ *  The URL is included because nothing stops one `createBatchLink()`
+ *  instance from being passed to two runtimes pointing at different
+ *  origins; without it, calls to one service would be merged into a
+ *  request sent to the other. */
+export function batchSignature(config) {
+    return [
+        refId(config.fetchFn),
+        refId(config.codec),
+        config.batchUrl,
+        headerSignature(config.headers),
+    ].join(FIELD);
+}
+function headerSignature(headers) {
+    const parts = [];
+    // `.forEach()` rather than `.entries()`/`for...of`: it is the one
+    // iteration style declared consistently across the DOM `Headers` lib
+    // type and the Node/undici one. `key` is already lowercase — the
+    // WHATWG `Headers` spec normalizes names on the way in, so no
+    // `.toLowerCase()` is needed here.
+    headers.forEach((value, key) => {
+        if (!FRAME_LEVEL_HEADERS.has(key)) {
+            parts.push(`${key}:${value}`);
+        }
+    });
+    // `Headers` iteration order is not guaranteed stable across
+    // implementations — sort so two identical header sets always produce
+    // one signature instead of needlessly splitting a batch.
+    parts.sort();
+    return parts.join(ENTRY);
+}
+// Identity (not structural) comparison for `fetch`/codec: two distinct
+// codec objects with equal `contentType` may still encode differently,
+// so only the same reference is safe to batch together.
+const refIds = new WeakMap();
+let nextRefId = 0;
+function refId(ref) {
+    let id = refIds.get(ref);
+    if (id === undefined) {
+        id = nextRefId++;
+        refIds.set(ref, id);
+    }
+    return String(id);
+}
+/** Splits a flush into partitions that may each be sent as one
+ *  `/rpc/batch` request. Insertion order is preserved within every
+ *  partition, and partitions are returned in first-seen order, so a
+ *  flush whose calls all share a config behaves exactly as it did
+ *  before partitioning existed. */
+export function partition(entries, options) {
+    const partitions = [];
+    const indexBySignature = new Map();
+    for (const entry of entries) {
+        const config = effectiveConfig(entry.request, options);
+        const signature = batchSignature(config);
+        const existing = indexBySignature.get(signature);
+        if (existing === undefined) {
+            indexBySignature.set(signature, partitions.length);
+            partitions.push({ config, entries: [entry] });
+        }
+        else {
+            partitions[existing].entries.push(entry);
+        }
+    }
+    return partitions;
+}
+//# sourceMappingURL=signature.js.map

package/dist/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { CratestackRpcCodec, RpcLinkRequest, RpcLinkResponse } from "@cratestack/ts-types";
+export interface BatchLinkOptions {
+    /** Scheduling window. Omitted (default) uses `queueMicrotask` — calls
+     *  fired synchronously in the same tick (e.g. inside `Promise.all`)
+     *  collapse into one `/rpc/batch` request. Pass a millisecond value to
+     *  widen the window across ticks (e.g. debounce bursts from unrelated
+     *  components). */
+    windowMs?: number;
+    /** Maximum requests per flushed `/rpc/batch` call. Applied **per
+     *  partition** (see {@link batchSignature}), not across the whole
+     *  flush — a partition larger than this splits into several
+     *  concurrent requests. Default: unbounded; the server enforces no
+     *  size limit either (see `docs/design/rpc-transport.md` §3.2), but a
+     *  huge fan-in may still be worth capping client-side. */
+    maxBatchSize?: number;
+    /** Returns a dedupe key for a queued call, or `null` to never
+     *  collapse it with anything else. Two calls in the same partition
+     *  that return the same non-null key become ONE `/rpc/batch` frame,
+     *  and every caller resolves from that single result.
+     *
+     *  Default: only collapse calls that share an explicit
+     *  `idempotencyKey` — that's already the caller's own signal that the
+     *  call is safe to treat as a repeat. Calls with no idempotency key
+     *  are never auto-collapsed, since the server does no dedup of its
+     *  own and silently merging two textually-identical but unmarked
+     *  mutations would be unsafe. Pass a custom `dedupe` for full
+     *  value-based collapsing, or `() => null` to disable dedup entirely
+     *  and only batch. */
+    dedupe?: (request: RpcLinkRequest) => string | null;
+    /** Headers merged **over** the shared headers of each partition when
+     *  synthesizing its `/rpc/batch` request. Use this to declare the
+     *  aggregate request's own headers rather than inheriting whatever
+     *  the queued calls happened to carry. */
+    headers?: HeadersInit;
+    /** `fetch` used for synthesized `/rpc/batch` requests, overriding the
+     *  queued calls' own. */
+    fetchFn?: typeof fetch;
+    /** Codec used to encode the `/rpc/batch` body and decode its response
+     *  frames, overriding the queued calls' own. Note each caller's
+     *  individual result is still re-encoded with *its own* codec, so a
+     *  generated runtime always decodes what it expects. */
+    codec?: CratestackRpcCodec;
+}
+/** One queued call awaiting a flush. */
+export interface QueueEntry {
+    readonly request: RpcLinkRequest;
+    readonly resolve: (value: RpcLinkResponse) => void;
+    readonly reject: (reason: unknown) => void;
+}
+/** Calls collapsed into a single `/rpc/batch` frame by `dedupe`. */
+export interface Group {
+    readonly key: string | null;
+    readonly entries: QueueEntry[];
+}
+/** The transport config a synthesized `/rpc/batch` request is issued
+ *  with, after applying any {@link BatchLinkOptions} overrides. Every
+ *  entry within a partition resolves to an equal config by
+ *  construction — that is what the partition *is*. */
+export interface EffectiveConfig {
+    readonly headers: Headers;
+    readonly fetchFn: typeof fetch;
+    readonly codec: CratestackRpcCodec;
+    readonly batchUrl: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEhG,MAAM,WAAW,gBAAgB;IAC/B;;;;uBAImB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;8DAK0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;0BAYsB;IACtB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,CAAC;IACpD;;;8CAG0C;IAC1C,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;6BACyB;IACzB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB;;;4DAGwD;IACxD,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAED,oEAAoE;AACpE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;CAChC;AAED;;;sDAGsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratestack/link-batch",
-  "version": "0.5.2",
+  "version": "0.6.3",
   "description": "A batshit-style automatic batch scheduler for CrateStack's generated TypeScript RPC client, shipped as an RpcLink.",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,7 @@
     "lint": "biome check ."
   },
   "dependencies": {
-    "@cratestack/ts-types": "0.5.2"
+    "@cratestack/ts-types": "0.6.3"
   },
   "devDependencies": {
     "typescript": "^5.7.0",