@boy-offi9-inc/reqkit 0.8.0 → 0.9.0

package/README.md

@@ -76,6 +76,7 @@ Requires Node 18+. TypeScript types are included.
 | Slow down *before* the server says 429 (obey `X-RateLimit-*`) | [`createRateLimiter`](#createratelimiteropts) |
 | Stop hammering a service that keeps failing | [`createCircuitBreaker`](#createcircuitbreakeropts) |
 | Cache GETs (TTL, stale-while-revalidate, stale-if-error, ETag/304) | [`createFetch` → `cache`](#caching) |
+| Cut tail latency with backup requests | [`withHedge`](#withhedgefn-opts) / [`createFetch` → `hedge`](#hedged-requests) |
 | Log or measure every request, retry and cache hit | [`createFetch` → `onEvent`](#events-and-logging) |
 | Attach a token and refresh it on 401 — once, even with many requests in flight | [`createFetch` → `auth`](#auth-token-refresh) |
 | Walk a paginated API (cursor, offset, `Link` headers) | [`paginate` / `paginateLinks`](#pagination-paginate-paginatepages-paginatelinks) |
@@ -201,6 +202,30 @@ Pass your own `signal` to cancel from the outside too — it's linked into the o
 await withTimeout(signal => fetch(url, { signal }), 5000, { signal: userController.signal });
 ```
 
+### `withHedge(fn, opts)`
+
+Insurance against the occasional slow request. It starts `fn`; if that hasn't answered after `delayMs`, it starts a backup (a *hedge*) and takes whichever succeeds first. The others are aborted, so connections are freed.
+
+```js
+import { withHedge } from "@boy-offi9-inc/reqkit";
+
+const res = await withHedge((signal) => fetch(url, { signal }), { delayMs: 150 });
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `delayMs` | — (required) | wait before launching backup *n*: a number, or `(n) => ms` |
+| `maxHedges` | `1` | how many backups at most |
+| `isFailure` | `status >= 500` | results that count as failed — the next backup launches immediately |
+| `hedgeOnError` | `true` | when an attempt *throws*, launch the next backup immediately |
+| `onHedge` | — | `({ index, afterMs }) => void` — a backup was launched |
+| `onWinner` | — | `(index) => void` — which attempt won (`0` = the original) |
+| `signal` | — | cancels every attempt and rejects with the signal's reason |
+
+`fn(signal, index)` receives an `AbortSignal` (pass it to `fetch`) and the attempt number (`0` = the original). If every attempt fails, the last failed *result* is returned (a 503 `Response` isn't thrown); if none produced a result, the last error is thrown. The bodies of responses that lose are cancelled.
+
+Hedging sends extra requests, so only use it for calls that are safe to run twice (GETs and other idempotent calls).
+
 ### `normalizeError(err)`
 
 One consistent error shape regardless of source (fetch, axios, node http, generic):
@@ -511,6 +536,7 @@ const admin = api.extend({ headers: { "x-role": "admin" } }); // merges over the
 | `circuitBreaker` | — | `true` / options → one breaker **per origin**; or pass a shared [`createCircuitBreaker`](#createcircuitbreakeropts), or `(url) => breaker`. An open circuit stops retries immediately. |
 | `trustedOrigins` | — | extra origins that may receive the default credentials — see [Security](#security) |
 | `auth` | — | attach a token and refresh it on 401 — see [Auth token refresh](#auth-token-refresh) |
+| `hedge` | — | send a backup request when an attempt is slow — see [Hedged requests](#hedged-requests). `true` = hedge at your own recent p95 |
 | `cache` | — | in-memory GET cache — see [Caching](#caching). `true` = 60s TTL. Per request: `cache: false` bypasses, `"reload"` refreshes |
 | `dedupe` | `false` | merge identical concurrent `GET`/`HEAD` calls; every caller gets its own readable clone. Requests with their own `signal` are never merged. |
 | `throwHttpErrors` | `true` | throw `HTTPError` for non-2xx (`err.status`, `err.response`, `err.url`, `err.method`) |
@@ -541,6 +567,21 @@ await Promise.all(urls.map((u) => api.json(u))); // 20 requests, all 401 → one
 - **Options:** `header` (default `"authorization"`), `scheme` (default `"Bearer"`, `""` for a bare token such as an `X-API-Key`), `shouldRefresh(response)` (default: status 401). `refresh({ token, response })` may return the new token or just update your store. If `refresh` throws, every waiting request rejects with that error — and the next request tries again.
 - `extend()` children that share the same `auth` object share one refresh; the cache keys entries per token.
 
+#### Hedged requests
+
+```js
+const api = createFetch({ baseUrl: "https://api.example.com", hedge: true });          // hedge at your own recent p95
+const api2 = createFetch({ baseUrl: "https://api.example.com", hedge: { delayMs: 200 } }); // or a fixed delay
+```
+
+If an attempt hasn't answered after the delay, a backup request goes out and the first good response wins; the slower request is cancelled.
+
+- **Idempotent only.** GET, HEAD, OPTIONS, PUT and DELETE are hedged; a POST isn't unless it carries an `Idempotency-Key` (or you list the method in `methods`). Stream bodies are never hedged.
+- **`delayMs: "auto"`** (the default for `hedge: true`) waits for your own recent `percentile` latency (default 0.95) per origin, never less than `minDelayMs` (20), and uses `fallbackDelayMs` (300) until `minSamples` (10) responses have been seen. At p95 that's roughly 5% extra requests for a much shorter tail.
+- **Failures don't wait.** A 5xx response or a thrown error launches the backup immediately.
+- **Backups are real requests:** each one goes through the rate limiter. Hedging is applied per attempt, inside retries, and turns off request de-duplication for the hedged call.
+- Override per call with `hedge: false` or `hedge: { delayMs: 100 }`. `maxHedges` (default 1) allows more backups.
+
 #### Events and logging
 
 One callback receives everything that happens, so you can plug reqkit into your logger or metrics without wrapping anything.
@@ -561,8 +602,9 @@ const api = createFetch({
 | `request` | a call starts | `url`, `method` |
 | `attempt` | a network attempt starts | `url`, `method`, `attempt` (1-based) |
 | `retry` | an attempt failed and another will follow | `url`, `method`, `attempt`, `delayMs`, `reason` (`"error"` \| `"status"`), `status?`, `error?` |
-| `response` | the final response arrives (including non-2xx, before `HTTPError` is thrown) | `url`, `method`, `status`, `ok`, `durationMs`, `attempts`, `cache?` (`"hit"` \| `"stale"` \| `"revalidated"` \| `"miss"` \| `"stale-if-error"`) |
+| `response` | the final response arrives (including non-2xx, before `HTTPError` is thrown) | `url`, `method`, `status`, `ok`, `durationMs`, `attempts`, `hedges`, `hedgeWon`, `cache?` (`"hit"` \| `"stale"` \| `"revalidated"` \| `"miss"` \| `"stale-if-error"`) |
 | `error` | the call fails without a response — network error, timeout, abort, open circuit | `url?`, `method?`, `error`, `durationMs`, `attempts` |
+| `hedge` | a backup request was sent | `url`, `method`, `index`, `afterMs` |
 | `cache` | cache activity | `url`, `method`, `event` (`hit`, `stale`, `revalidated`, `miss`, `store`, `stale-if-error`) |
 | `ratelimit` | a call waited on the rate limiter | `url`, `method`, `waitedMs` |
 | `circuit` | a circuit breaker changed state (breakers created from options — one per origin) | `origin`, `state`, `previous` |

package/dist/reqkit.mjs

@@ -1,4 +1,4 @@
-/*! @boy-offi9-inc/reqkit v0.8.0 — ESM bundle (generated by scripts/build-esm.js, do not edit) */
+/*! @boy-offi9-inc/reqkit v0.9.0 — ESM bundle (generated by scripts/build-esm.js, do not edit) */
 const __defs = {
 "errors/HTTPError": function (module, exports, require) {
 class HTTPError extends Error {
@@ -297,6 +297,8 @@ module.exports = { createMemoryCache };
 const { withRetry, RetryAbortedError } = require("../resilience/retry");
 const { withTimeout } = require("../resilience/timeout");
 const { withDedupe } = require("../resilience/dedupe");
+const { withHedge } = require("../resilience/hedge");
+const { createLatencyTracker } = require("./latency");
 const { buildQuery } = require("./buildQuery");
 const { parseJsonSafe } = require("./parseJsonSafe");
 const { normalizeError } = require("../errors/normalizeError");
@@ -395,6 +397,8 @@ function mergeDefaults(base, extra) {
  *  - `onEvent`: one callback for everything that happens (request, attempt,
  *    retry, response, error, cache, rate-limit waits, circuit changes, token
  *    refreshes) — plug it into your logger or metrics
+ *  - `hedge`: if a request is slow, send a backup and take whichever answers
+ *    first (idempotent requests only) — trims tail latency
  *  - concurrent GET de-duplication (withDedupe)
  *  - `auth`: attach a token, and on a 401 refresh it ONCE (shared by all
  *    concurrent requests) and replay the request
@@ -427,6 +431,11 @@ function mergeDefaults(base, extra) {
  * @param {string[]} [defaults.trustedOrigins] - extra origins ("https://cdn.example.com") that may
  *   receive the default credentials, besides `baseUrl`'s. With neither `baseUrl` nor
  *   `trustedOrigins` set there is nothing to compare against and credentials go everywhere.
+ * @param {boolean | object} [defaults.hedge] - `{ delayMs, maxHedges, methods }` (or `true`). If an attempt
+ *   hasn't answered after `delayMs`, a backup request is sent and the first good answer wins. `delayMs`
+ *   is a number, or "auto" (default) to hedge at your own recent p95 latency per origin (tuned with
+ *   `percentile` = 0.95, `minDelayMs` = 20, `fallbackDelayMs` = 300 until 10 samples exist). Applies to
+ *   idempotent methods (or requests with an `Idempotency-Key`) only. Disables `dedupe` for hedged requests.
  * @param {boolean} [defaults.dedupe=false] - merge identical concurrent GET/HEAD calls
  * @param {boolean} [defaults.throwHttpErrors=true]
  * @param {typeof fetch} [defaults.fetch=globalThis.fetch]
@@ -448,6 +457,7 @@ function createFetch(defaults = {}) {
     cache,
     auth,
     trustedOrigins,
+    hedge,
     dedupe = false,
     throwHttpErrors: defaultThrow = true,
     fetch: customFetch,
@@ -533,6 +543,12 @@ function createFetch(defaults = {}) {
     emitEvent({ type: "cache", url, method: "GET", event: type });
   };
 
+  const hedgeDefaults = !hedge
+    ? null
+    : { delayMs: "auto", maxHedges: 1, ...(hedge === true ? {} : hedge) };
+  if (hedgeDefaults && !hedgeDefaults.tracker) hedgeDefaults.tracker = createLatencyTracker();
+  const fallbackTracker = hedgeDefaults ? null : createLatencyTracker(); // for per-request `hedge` on an instance with no defaults
+
   // Shared in-flight GETs. Every caller gets its own clone of the response so
   // body reads don't fight each other.
   const sharedFetch = withDedupe((key, url, init) => doFetch(url, init), { keyFn: (key) => key });
@@ -597,6 +613,7 @@ function createFetch(defaults = {}) {
       signal,
       headers: initHeaders,
       cache: cacheMode,
+      hedge: hedgeOpt,
       ...fetchInit
     } = init;
 
@@ -649,6 +666,26 @@ function createFetch(defaults = {}) {
       (methods.map((m) => m.toUpperCase()).includes(finalMethod) || hasIdempotencyKey);
     const { statusCodes, methods: _methods, retries = 2, shouldRetry: customShouldRetry, ...retryRest } = retryCfg || {};
 
+    // --- hedging policy ----------------------------------------------------
+    const hedgeCfg =
+      hedgeOpt === false || (!hedgeDefaults && !hedgeOpt)
+        ? null
+        : { delayMs: "auto", maxHedges: 1, ...(hedgeDefaults || {}), ...(hedgeOpt && hedgeOpt !== true ? hedgeOpt : {}) };
+    const hedgeMethods = ((hedgeCfg && hedgeCfg.methods) || DEFAULT_RETRY_METHODS).map((m) => m.toUpperCase());
+    const canHedge =
+      hedgeCfg !== null &&
+      hedgeCfg.maxHedges >= 1 &&
+      !isStreamBody(ctx.init.body) &&
+      (hedgeMethods.includes(finalMethod) || hasIdempotencyKey);
+    const tracker = canHedge ? (hedgeDefaults ? hedgeDefaults.tracker : fallbackTracker) : null;
+    const trackerKey = originOf(ctx.url);
+    const hedgeDelay = () => {
+      if (typeof hedgeCfg.delayMs === "number") return hedgeCfg.delayMs;
+      const { percentile = 0.95, minDelayMs = 20, fallbackDelayMs = 300, minSamples = 10 } = hedgeCfg;
+      if (tracker.count(trackerKey) < minSamples) return fallbackDelayMs;
+      return Math.max(minDelayMs, tracker.percentile(trackerKey, percentile));
+    };
+
     // One trip to the network: rate limit → circuit breaker → per-attempt
     // timeout → fetch, retried per the policy above. `netHeaders` and
     // `netSignal` are parameters so background revalidation can reuse this.
@@ -656,16 +693,21 @@ function createFetch(defaults = {}) {
       const attemptOnce = () => {
         state.attempts++;
         emitEvent({ type: "attempt", url: ctx.url, method: finalMethod, attempt: state.attempts });
-        const attempt = async () => {
+        // A single request: rate limit → per-attempt timeout → fetch. `sig` is what cancels it —
+        // the caller's signal normally, or the hedge's own signal when it can lose a race.
+        const runOnce = async (sig) => {
           if (limiter) {
-            const waitedMs = await limiter.acquire({ signal: netSignal });
-            if (waitedMs > 0) emitEvent({ type: "ratelimit", url: ctx.url, method: finalMethod, waitedMs });
+            const waitStart = Date.now();
+            await limiter.acquire({ signal: sig });
+            const waitedMs = Date.now() - waitStart;
+            // Only report waits that mean something; scheduling jitter on an immediate acquire is not a wait.
+            if (waitedMs >= 5) emitEvent({ type: "ratelimit", url: ctx.url, method: finalMethod, waitedMs });
           }
+          const startedOne = Date.now();
           const res = await withTimeout(
             (attemptSignal) => {
               const attemptInit = { ...ctx.init, method: finalMethod, headers: netHeaders, signal: attemptSignal };
-              const useDedupe =
-                dedupe && !netSignal && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
+              const useDedupe = dedupe && !sig && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
               if (!useDedupe) return doFetch(ctx.url, attemptInit);
               // No per-attempt signal on a shared request: aborting one caller
               // must never cancel everyone else's. It still gets its own
@@ -678,11 +720,27 @@ function createFetch(defaults = {}) {
               return sharedFetch(key, ctx.url, sharedInit).then((res) => res.clone());
             },
             timeout === false ? Infinity : timeout,
-            { signal: netSignal }
+            { signal: sig }
           );
           if (limiter) limiter.update(res);
+          if (tracker && res.status < 500) tracker.record(trackerKey, Date.now() - startedOne);
           return res;
         };
+        const attempt = canHedge
+          ? () =>
+              withHedge((hedgeSignal) => runOnce(hedgeSignal), {
+                delayMs: hedgeDelay,
+                maxHedges: hedgeCfg.maxHedges,
+                signal: netSignal,
+                onHedge: ({ index, afterMs }) => {
+                  state.hedges++;
+                  emitEvent({ type: "hedge", url: ctx.url, method: finalMethod, index, afterMs });
+                },
+                onWinner: (index) => {
+                  state.hedgeWon = index > 0;
+                },
+              })
+          : () => runOnce(netSignal);
         const breaker = breakerFor && breakerFor(ctx.url);
         return breaker ? breaker.run(attempt) : attempt();
       };
@@ -746,6 +804,8 @@ function createFetch(defaults = {}) {
         durationMs: Date.now() - state.startedAt,
         attempts: state.attempts,
         cache: state.cache,
+        hedges: state.hedges,
+        hedgeWon: state.hedgeWon,
       });
       if (onResponse) await onResponse({ url: ctx.url, init: ctx.init, response });
       if (throwHttpErrors && !response.ok) {
@@ -857,13 +917,21 @@ function createFetch(defaults = {}) {
   }
 
   async function request(input, init = {}) {
-    const state = { startedAt: Date.now(), attempts: 0, responded: false, cache: undefined, url: undefined, method: undefined };
+    const state = { startedAt: Date.now(), attempts: 0, hedges: 0, hedgeWon: false, responded: false, cache: undefined, url: undefined, method: undefined };
     try {
       return await execute(input, init, state);
     } catch (error) {
       // A non-2xx HTTPError was already reported as a "response" event.
       if (!state.responded) {
-        emitEvent({ type: "error", url: state.url, method: state.method, error, durationMs: Date.now() - state.startedAt, attempts: state.attempts });
+        emitEvent({
+          type: "error",
+          url: state.url,
+          method: state.method,
+          error,
+          durationMs: Date.now() - state.startedAt,
+          attempts: state.attempts,
+          hedges: state.hedges,
+        });
       }
       throw error;
     }
@@ -890,6 +958,7 @@ function createFetch(defaults = {}) {
           rateLimit: limiter || undefined,
           circuitBreaker: breakerFor || undefined,
           cache: cacheCfg || undefined,
+          hedge: hedgeDefaults || undefined,
         },
         overrides
       )
@@ -900,6 +969,50 @@ function createFetch(defaults = {}) {
 
 module.exports = { createFetch, HTTPError };
 
+},
+"http/latency": function (module, exports, require) {
+/**
+ * Remembers recent response times per key (an origin) so `createFetch` can
+ * hedge at "my usual slow" instead of a hand-tuned constant.
+ */
+function createLatencyTracker({ maxSamples = 100, maxKeys = 200 } = {}) {
+  const byKey = new Map();
+
+  return {
+    record(key, ms) {
+      if (!Number.isFinite(ms) || ms < 0) return;
+      let samples = byKey.get(key);
+      if (!samples) {
+        samples = [];
+        byKey.set(key, samples);
+        if (byKey.size > maxKeys) byKey.delete(byKey.keys().next().value); // forget the oldest origin
+      }
+      samples.push(ms);
+      if (samples.length > maxSamples) samples.shift();
+    },
+
+    count(key) {
+      const samples = byKey.get(key);
+      return samples ? samples.length : 0;
+    },
+
+    /** The p-th percentile (0–1) of the recent samples for `key`, or null when there are none. */
+    percentile(key, p) {
+      const samples = byKey.get(key);
+      if (!samples || samples.length === 0) return null;
+      const sorted = [...samples].sort((a, b) => a - b);
+      const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+      return sorted[index];
+    },
+
+    clear() {
+      byKey.clear();
+    },
+  };
+}
+
+module.exports = { createLatencyTracker };
+
 },
 "http/parseJsonSafe": function (module, exports, require) {
 /**
@@ -933,6 +1046,7 @@ module.exports = { parseJsonSafe };
 "index": function (module, exports, require) {
 const { withRetry, RetryAbortedError, StopRetry } = require("./resilience/retry");
 const { withTimeout, TimeoutError } = require("./resilience/timeout");
+const { withHedge } = require("./resilience/hedge");
 const { normalizeError } = require("./errors/normalizeError");
 const { parseJsonSafe } = require("./http/parseJsonSafe");
 const { buildQuery } = require("./http/buildQuery");
@@ -955,6 +1069,7 @@ module.exports = {
   RetryAbortedError,
   StopRetry,
   withTimeout,
+  withHedge,
   TimeoutError,
   normalizeError,
   parseJsonSafe,
@@ -1557,6 +1672,177 @@ function withDedupe(fn, opts = {}) {
 
 module.exports = { withDedupe };
 
+},
+"resilience/hedge": function (module, exports, require) {
+const { discardBody } = require("../internal/http");
+
+function defaultIsFailure(result) {
+  return Boolean(result) && typeof result.status === "number" && result.status >= 500;
+}
+
+function lostReason() {
+  const reason = new Error("Request cancelled: a faster hedged request won");
+  reason.name = "AbortError";
+  return reason;
+}
+
+/**
+ * Hedged requests: start `fn`; if it hasn't answered within `delayMs`, start
+ * a backup (a "hedge"); whichever succeeds first wins and the others are
+ * aborted. It trims the slow tail of latency — the occasional request that
+ * takes 10× longer than the rest — at the cost of a little extra load.
+ *
+ * ```js
+ * const res = await withHedge((signal) => fetch(url, { signal }), { delayMs: 200 });
+ * ```
+ *
+ * Only hedge requests that are safe to run twice (GETs, idempotent calls).
+ *
+ * Details:
+ *  - `fn(signal, index)` — `index` is 0 for the original and 1.. for backups.
+ *    Abort-aware code (like `fetch`) is actually cancelled when it loses.
+ *  - An attempt that throws, or returns a failed result (status >= 500 by
+ *    default), launches the next backup immediately instead of waiting.
+ *  - If every attempt fails: resolves with the last failed *result* if there was
+ *    one (a 503 `Response` isn't thrown), otherwise rejects with the last error.
+ *  - The bodies of responses that lose are cancelled so connections are freed.
+ *
+ * @template T
+ * @param {(signal: AbortSignal, index: number) => Promise<T>} fn
+ * @param {object} opts
+ * @param {number | ((index: number) => number)} opts.delayMs - wait before launching backup #index (1-based)
+ * @param {number} [opts.maxHedges=1] - how many backups at most
+ * @param {(result: T) => boolean} [opts.isFailure] - results that count as failed. Default: `result.status >= 500`
+ * @param {boolean} [opts.hedgeOnError=true] - launch the next backup right away when an attempt throws
+ * @param {(info: { index: number, afterMs: number }) => void} [opts.onHedge] - a backup was launched
+ * @param {(index: number) => void} [opts.onWinner] - which attempt produced the result (0 = the original)
+ * @param {AbortSignal} [opts.signal] - cancels everything; rejects with the signal's reason
+ * @returns {Promise<T>}
+ */
+function withHedge(fn, opts = {}) {
+  const { delayMs, maxHedges = 1, isFailure = defaultIsFailure, hedgeOnError = true, onHedge, onWinner, signal } = opts;
+
+  const delayFor = typeof delayMs === "function" ? delayMs : () => delayMs;
+  if (typeof delayMs !== "function" && !(typeof delayMs === "number" && delayMs >= 0 && Number.isFinite(delayMs))) {
+    return Promise.reject(new TypeError("withHedge: `delayMs` must be a non-negative number or a function returning one"));
+  }
+  if (!(Number.isInteger(maxHedges) && maxHedges >= 0)) {
+    return Promise.reject(new TypeError("withHedge: `maxHedges` must be an integer >= 0"));
+  }
+  if (signal && signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const attempts = []; // { controller, done }
+    let launched = 0;
+    let pending = 0;
+    let settled = false;
+    let timer = null;
+    let lastError;
+    let hasError = false;
+    let failedResult;
+    let hasFailedResult = false;
+
+    const onAbort = () => finish(reject, signal.reason, -1);
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+
+    function finish(settle, value, winnerIndex) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      attempts.forEach((attempt, index) => {
+        if (index !== winnerIndex && !attempt.done) attempt.controller.abort(lostReason());
+      });
+      if (hasFailedResult && failedResult !== value) discardBody(failedResult);
+      if (winnerIndex >= 0 && onWinner) {
+        try {
+          onWinner(winnerIndex);
+        } catch {
+          // ignore
+        }
+      }
+      settle(value);
+    }
+
+    function scheduleBackup() {
+      clearTimeout(timer);
+      if (launched > maxHedges) return; // `launched` counts the original too
+      timer = setTimeout(() => launch(), Math.max(0, Number(delayFor(launched)) || 0));
+    }
+
+    function launch() {
+      if (settled) return;
+      const index = launched++;
+      const controller = new AbortController();
+      const attempt = { controller, done: false };
+      attempts[index] = attempt;
+      pending++;
+
+      if (index > 0 && onHedge) {
+        try {
+          onHedge({ index, afterMs: Date.now() - startedAt });
+        } catch {
+          // ignore
+        }
+      }
+
+      let promise;
+      try {
+        promise = Promise.resolve(fn(controller.signal, index));
+      } catch (error) {
+        promise = Promise.reject(error);
+      }
+
+      promise.then(
+        (result) => {
+          attempt.done = true;
+          pending--;
+          if (settled) return discardBody(result); // too late — it lost
+          if (isFailure(result)) {
+            if (hasFailedResult) discardBody(failedResult);
+            failedResult = result;
+            hasFailedResult = true;
+            return next();
+          }
+          finish(resolve, result, index);
+        },
+        (error) => {
+          attempt.done = true;
+          pending--;
+          if (settled) return;
+          lastError = error;
+          hasError = true;
+          if (hedgeOnError) next();
+          else if (pending === 0 && launched > maxHedges) giveUp();
+        }
+      );
+
+      scheduleBackup();
+    }
+
+    // An attempt failed: start the next backup now, or give up if there are none left.
+    function next() {
+      if (settled) return;
+      if (launched <= maxHedges) {
+        clearTimeout(timer);
+        launch();
+      } else if (pending === 0) {
+        giveUp();
+      }
+    }
+
+    function giveUp() {
+      if (hasFailedResult) finish(resolve, failedResult, -1);
+      else finish(reject, hasError ? lastError : new Error("withHedge: no attempt succeeded"), -1);
+    }
+
+    launch();
+  });
+}
+
+module.exports = { withHedge };
+
 },
 "resilience/limiter": function (module, exports, require) {
 /**
@@ -2982,6 +3268,7 @@ export const {
   retryAfterAware,
   streamSSE,
   withDedupe,
+  withHedge,
   withProgress,
   withRetry,
   withTimeout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Small, composable HTTP helpers \u2014 retry with backoff and Retry-After, timeouts, normalized errors, rate limiter, circuit breaker, response cache, resumable downloads, SSE/NDJSON streams, mock fetch, and an opt-in createFetch. Not a client; works alongside fetch/axios/anything.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -65,7 +65,9 @@
     "link-header",
     "stale-if-error",
     "observability",
-    "logging"
+    "logging",
+    "hedged-requests",
+    "tail-latency"
   ],
   "author": "Boy Offi9",
   "license": "MIT",

package/src/http/createFetch.js

@@ -1,6 +1,8 @@
 const { withRetry, RetryAbortedError } = require("../resilience/retry");
 const { withTimeout } = require("../resilience/timeout");
 const { withDedupe } = require("../resilience/dedupe");
+const { withHedge } = require("../resilience/hedge");
+const { createLatencyTracker } = require("./latency");
 const { buildQuery } = require("./buildQuery");
 const { parseJsonSafe } = require("./parseJsonSafe");
 const { normalizeError } = require("../errors/normalizeError");
@@ -99,6 +101,8 @@ function mergeDefaults(base, extra) {
  *  - `onEvent`: one callback for everything that happens (request, attempt,
  *    retry, response, error, cache, rate-limit waits, circuit changes, token
  *    refreshes) — plug it into your logger or metrics
+ *  - `hedge`: if a request is slow, send a backup and take whichever answers
+ *    first (idempotent requests only) — trims tail latency
  *  - concurrent GET de-duplication (withDedupe)
  *  - `auth`: attach a token, and on a 401 refresh it ONCE (shared by all
  *    concurrent requests) and replay the request
@@ -131,6 +135,11 @@ function mergeDefaults(base, extra) {
  * @param {string[]} [defaults.trustedOrigins] - extra origins ("https://cdn.example.com") that may
  *   receive the default credentials, besides `baseUrl`'s. With neither `baseUrl` nor
  *   `trustedOrigins` set there is nothing to compare against and credentials go everywhere.
+ * @param {boolean | object} [defaults.hedge] - `{ delayMs, maxHedges, methods }` (or `true`). If an attempt
+ *   hasn't answered after `delayMs`, a backup request is sent and the first good answer wins. `delayMs`
+ *   is a number, or "auto" (default) to hedge at your own recent p95 latency per origin (tuned with
+ *   `percentile` = 0.95, `minDelayMs` = 20, `fallbackDelayMs` = 300 until 10 samples exist). Applies to
+ *   idempotent methods (or requests with an `Idempotency-Key`) only. Disables `dedupe` for hedged requests.
  * @param {boolean} [defaults.dedupe=false] - merge identical concurrent GET/HEAD calls
  * @param {boolean} [defaults.throwHttpErrors=true]
  * @param {typeof fetch} [defaults.fetch=globalThis.fetch]
@@ -152,6 +161,7 @@ function createFetch(defaults = {}) {
     cache,
     auth,
     trustedOrigins,
+    hedge,
     dedupe = false,
     throwHttpErrors: defaultThrow = true,
     fetch: customFetch,
@@ -237,6 +247,12 @@ function createFetch(defaults = {}) {
     emitEvent({ type: "cache", url, method: "GET", event: type });
   };
 
+  const hedgeDefaults = !hedge
+    ? null
+    : { delayMs: "auto", maxHedges: 1, ...(hedge === true ? {} : hedge) };
+  if (hedgeDefaults && !hedgeDefaults.tracker) hedgeDefaults.tracker = createLatencyTracker();
+  const fallbackTracker = hedgeDefaults ? null : createLatencyTracker(); // for per-request `hedge` on an instance with no defaults
+
   // Shared in-flight GETs. Every caller gets its own clone of the response so
   // body reads don't fight each other.
   const sharedFetch = withDedupe((key, url, init) => doFetch(url, init), { keyFn: (key) => key });
@@ -301,6 +317,7 @@ function createFetch(defaults = {}) {
       signal,
       headers: initHeaders,
       cache: cacheMode,
+      hedge: hedgeOpt,
       ...fetchInit
     } = init;
 
@@ -353,6 +370,26 @@ function createFetch(defaults = {}) {
       (methods.map((m) => m.toUpperCase()).includes(finalMethod) || hasIdempotencyKey);
     const { statusCodes, methods: _methods, retries = 2, shouldRetry: customShouldRetry, ...retryRest } = retryCfg || {};
 
+    // --- hedging policy ----------------------------------------------------
+    const hedgeCfg =
+      hedgeOpt === false || (!hedgeDefaults && !hedgeOpt)
+        ? null
+        : { delayMs: "auto", maxHedges: 1, ...(hedgeDefaults || {}), ...(hedgeOpt && hedgeOpt !== true ? hedgeOpt : {}) };
+    const hedgeMethods = ((hedgeCfg && hedgeCfg.methods) || DEFAULT_RETRY_METHODS).map((m) => m.toUpperCase());
+    const canHedge =
+      hedgeCfg !== null &&
+      hedgeCfg.maxHedges >= 1 &&
+      !isStreamBody(ctx.init.body) &&
+      (hedgeMethods.includes(finalMethod) || hasIdempotencyKey);
+    const tracker = canHedge ? (hedgeDefaults ? hedgeDefaults.tracker : fallbackTracker) : null;
+    const trackerKey = originOf(ctx.url);
+    const hedgeDelay = () => {
+      if (typeof hedgeCfg.delayMs === "number") return hedgeCfg.delayMs;
+      const { percentile = 0.95, minDelayMs = 20, fallbackDelayMs = 300, minSamples = 10 } = hedgeCfg;
+      if (tracker.count(trackerKey) < minSamples) return fallbackDelayMs;
+      return Math.max(minDelayMs, tracker.percentile(trackerKey, percentile));
+    };
+
     // One trip to the network: rate limit → circuit breaker → per-attempt
     // timeout → fetch, retried per the policy above. `netHeaders` and
     // `netSignal` are parameters so background revalidation can reuse this.
@@ -360,16 +397,21 @@ function createFetch(defaults = {}) {
       const attemptOnce = () => {
         state.attempts++;
         emitEvent({ type: "attempt", url: ctx.url, method: finalMethod, attempt: state.attempts });
-        const attempt = async () => {
+        // A single request: rate limit → per-attempt timeout → fetch. `sig` is what cancels it —
+        // the caller's signal normally, or the hedge's own signal when it can lose a race.
+        const runOnce = async (sig) => {
           if (limiter) {
-            const waitedMs = await limiter.acquire({ signal: netSignal });
-            if (waitedMs > 0) emitEvent({ type: "ratelimit", url: ctx.url, method: finalMethod, waitedMs });
+            const waitStart = Date.now();
+            await limiter.acquire({ signal: sig });
+            const waitedMs = Date.now() - waitStart;
+            // Only report waits that mean something; scheduling jitter on an immediate acquire is not a wait.
+            if (waitedMs >= 5) emitEvent({ type: "ratelimit", url: ctx.url, method: finalMethod, waitedMs });
           }
+          const startedOne = Date.now();
           const res = await withTimeout(
             (attemptSignal) => {
               const attemptInit = { ...ctx.init, method: finalMethod, headers: netHeaders, signal: attemptSignal };
-              const useDedupe =
-                dedupe && !netSignal && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
+              const useDedupe = dedupe && !sig && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
               if (!useDedupe) return doFetch(ctx.url, attemptInit);
               // No per-attempt signal on a shared request: aborting one caller
               // must never cancel everyone else's. It still gets its own
@@ -382,11 +424,27 @@ function createFetch(defaults = {}) {
               return sharedFetch(key, ctx.url, sharedInit).then((res) => res.clone());
             },
             timeout === false ? Infinity : timeout,
-            { signal: netSignal }
+            { signal: sig }
           );
           if (limiter) limiter.update(res);
+          if (tracker && res.status < 500) tracker.record(trackerKey, Date.now() - startedOne);
           return res;
         };
+        const attempt = canHedge
+          ? () =>
+              withHedge((hedgeSignal) => runOnce(hedgeSignal), {
+                delayMs: hedgeDelay,
+                maxHedges: hedgeCfg.maxHedges,
+                signal: netSignal,
+                onHedge: ({ index, afterMs }) => {
+                  state.hedges++;
+                  emitEvent({ type: "hedge", url: ctx.url, method: finalMethod, index, afterMs });
+                },
+                onWinner: (index) => {
+                  state.hedgeWon = index > 0;
+                },
+              })
+          : () => runOnce(netSignal);
         const breaker = breakerFor && breakerFor(ctx.url);
         return breaker ? breaker.run(attempt) : attempt();
       };
@@ -450,6 +508,8 @@ function createFetch(defaults = {}) {
         durationMs: Date.now() - state.startedAt,
         attempts: state.attempts,
         cache: state.cache,
+        hedges: state.hedges,
+        hedgeWon: state.hedgeWon,
       });
       if (onResponse) await onResponse({ url: ctx.url, init: ctx.init, response });
       if (throwHttpErrors && !response.ok) {
@@ -561,13 +621,21 @@ function createFetch(defaults = {}) {
   }
 
   async function request(input, init = {}) {
-    const state = { startedAt: Date.now(), attempts: 0, responded: false, cache: undefined, url: undefined, method: undefined };
+    const state = { startedAt: Date.now(), attempts: 0, hedges: 0, hedgeWon: false, responded: false, cache: undefined, url: undefined, method: undefined };
     try {
       return await execute(input, init, state);
     } catch (error) {
       // A non-2xx HTTPError was already reported as a "response" event.
       if (!state.responded) {
-        emitEvent({ type: "error", url: state.url, method: state.method, error, durationMs: Date.now() - state.startedAt, attempts: state.attempts });
+        emitEvent({
+          type: "error",
+          url: state.url,
+          method: state.method,
+          error,
+          durationMs: Date.now() - state.startedAt,
+          attempts: state.attempts,
+          hedges: state.hedges,
+        });
       }
       throw error;
     }
@@ -594,6 +662,7 @@ function createFetch(defaults = {}) {
           rateLimit: limiter || undefined,
           circuitBreaker: breakerFor || undefined,
           cache: cacheCfg || undefined,
+          hedge: hedgeDefaults || undefined,
         },
         overrides
       )

package/src/http/latency.js

@@ -0,0 +1,41 @@
+/**
+ * Remembers recent response times per key (an origin) so `createFetch` can
+ * hedge at "my usual slow" instead of a hand-tuned constant.
+ */
+function createLatencyTracker({ maxSamples = 100, maxKeys = 200 } = {}) {
+  const byKey = new Map();
+
+  return {
+    record(key, ms) {
+      if (!Number.isFinite(ms) || ms < 0) return;
+      let samples = byKey.get(key);
+      if (!samples) {
+        samples = [];
+        byKey.set(key, samples);
+        if (byKey.size > maxKeys) byKey.delete(byKey.keys().next().value); // forget the oldest origin
+      }
+      samples.push(ms);
+      if (samples.length > maxSamples) samples.shift();
+    },
+
+    count(key) {
+      const samples = byKey.get(key);
+      return samples ? samples.length : 0;
+    },
+
+    /** The p-th percentile (0–1) of the recent samples for `key`, or null when there are none. */
+    percentile(key, p) {
+      const samples = byKey.get(key);
+      if (!samples || samples.length === 0) return null;
+      const sorted = [...samples].sort((a, b) => a - b);
+      const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+      return sorted[index];
+    },
+
+    clear() {
+      byKey.clear();
+    },
+  };
+}
+
+module.exports = { createLatencyTracker };

package/src/index.js

@@ -1,5 +1,6 @@
 const { withRetry, RetryAbortedError, StopRetry } = require("./resilience/retry");
 const { withTimeout, TimeoutError } = require("./resilience/timeout");
+const { withHedge } = require("./resilience/hedge");
 const { normalizeError } = require("./errors/normalizeError");
 const { parseJsonSafe } = require("./http/parseJsonSafe");
 const { buildQuery } = require("./http/buildQuery");
@@ -22,6 +23,7 @@ module.exports = {
   RetryAbortedError,
   StopRetry,
   withTimeout,
+  withHedge,
   TimeoutError,
   normalizeError,
   parseJsonSafe,

package/src/index.mjs

@@ -5,6 +5,7 @@ export const {
   RetryAbortedError,
   StopRetry,
   withTimeout,
+  withHedge,
   TimeoutError,
   normalizeError,
   parseJsonSafe,

package/src/resilience/hedge.js

@@ -0,0 +1,168 @@
+const { discardBody } = require("../internal/http");
+
+function defaultIsFailure(result) {
+  return Boolean(result) && typeof result.status === "number" && result.status >= 500;
+}
+
+function lostReason() {
+  const reason = new Error("Request cancelled: a faster hedged request won");
+  reason.name = "AbortError";
+  return reason;
+}
+
+/**
+ * Hedged requests: start `fn`; if it hasn't answered within `delayMs`, start
+ * a backup (a "hedge"); whichever succeeds first wins and the others are
+ * aborted. It trims the slow tail of latency — the occasional request that
+ * takes 10× longer than the rest — at the cost of a little extra load.
+ *
+ * ```js
+ * const res = await withHedge((signal) => fetch(url, { signal }), { delayMs: 200 });
+ * ```
+ *
+ * Only hedge requests that are safe to run twice (GETs, idempotent calls).
+ *
+ * Details:
+ *  - `fn(signal, index)` — `index` is 0 for the original and 1.. for backups.
+ *    Abort-aware code (like `fetch`) is actually cancelled when it loses.
+ *  - An attempt that throws, or returns a failed result (status >= 500 by
+ *    default), launches the next backup immediately instead of waiting.
+ *  - If every attempt fails: resolves with the last failed *result* if there was
+ *    one (a 503 `Response` isn't thrown), otherwise rejects with the last error.
+ *  - The bodies of responses that lose are cancelled so connections are freed.
+ *
+ * @template T
+ * @param {(signal: AbortSignal, index: number) => Promise<T>} fn
+ * @param {object} opts
+ * @param {number | ((index: number) => number)} opts.delayMs - wait before launching backup #index (1-based)
+ * @param {number} [opts.maxHedges=1] - how many backups at most
+ * @param {(result: T) => boolean} [opts.isFailure] - results that count as failed. Default: `result.status >= 500`
+ * @param {boolean} [opts.hedgeOnError=true] - launch the next backup right away when an attempt throws
+ * @param {(info: { index: number, afterMs: number }) => void} [opts.onHedge] - a backup was launched
+ * @param {(index: number) => void} [opts.onWinner] - which attempt produced the result (0 = the original)
+ * @param {AbortSignal} [opts.signal] - cancels everything; rejects with the signal's reason
+ * @returns {Promise<T>}
+ */
+function withHedge(fn, opts = {}) {
+  const { delayMs, maxHedges = 1, isFailure = defaultIsFailure, hedgeOnError = true, onHedge, onWinner, signal } = opts;
+
+  const delayFor = typeof delayMs === "function" ? delayMs : () => delayMs;
+  if (typeof delayMs !== "function" && !(typeof delayMs === "number" && delayMs >= 0 && Number.isFinite(delayMs))) {
+    return Promise.reject(new TypeError("withHedge: `delayMs` must be a non-negative number or a function returning one"));
+  }
+  if (!(Number.isInteger(maxHedges) && maxHedges >= 0)) {
+    return Promise.reject(new TypeError("withHedge: `maxHedges` must be an integer >= 0"));
+  }
+  if (signal && signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const attempts = []; // { controller, done }
+    let launched = 0;
+    let pending = 0;
+    let settled = false;
+    let timer = null;
+    let lastError;
+    let hasError = false;
+    let failedResult;
+    let hasFailedResult = false;
+
+    const onAbort = () => finish(reject, signal.reason, -1);
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+
+    function finish(settle, value, winnerIndex) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      attempts.forEach((attempt, index) => {
+        if (index !== winnerIndex && !attempt.done) attempt.controller.abort(lostReason());
+      });
+      if (hasFailedResult && failedResult !== value) discardBody(failedResult);
+      if (winnerIndex >= 0 && onWinner) {
+        try {
+          onWinner(winnerIndex);
+        } catch {
+          // ignore
+        }
+      }
+      settle(value);
+    }
+
+    function scheduleBackup() {
+      clearTimeout(timer);
+      if (launched > maxHedges) return; // `launched` counts the original too
+      timer = setTimeout(() => launch(), Math.max(0, Number(delayFor(launched)) || 0));
+    }
+
+    function launch() {
+      if (settled) return;
+      const index = launched++;
+      const controller = new AbortController();
+      const attempt = { controller, done: false };
+      attempts[index] = attempt;
+      pending++;
+
+      if (index > 0 && onHedge) {
+        try {
+          onHedge({ index, afterMs: Date.now() - startedAt });
+        } catch {
+          // ignore
+        }
+      }
+
+      let promise;
+      try {
+        promise = Promise.resolve(fn(controller.signal, index));
+      } catch (error) {
+        promise = Promise.reject(error);
+      }
+
+      promise.then(
+        (result) => {
+          attempt.done = true;
+          pending--;
+          if (settled) return discardBody(result); // too late — it lost
+          if (isFailure(result)) {
+            if (hasFailedResult) discardBody(failedResult);
+            failedResult = result;
+            hasFailedResult = true;
+            return next();
+          }
+          finish(resolve, result, index);
+        },
+        (error) => {
+          attempt.done = true;
+          pending--;
+          if (settled) return;
+          lastError = error;
+          hasError = true;
+          if (hedgeOnError) next();
+          else if (pending === 0 && launched > maxHedges) giveUp();
+        }
+      );
+
+      scheduleBackup();
+    }
+
+    // An attempt failed: start the next backup now, or give up if there are none left.
+    function next() {
+      if (settled) return;
+      if (launched <= maxHedges) {
+        clearTimeout(timer);
+        launch();
+      } else if (pending === 0) {
+        giveUp();
+      }
+    }
+
+    function giveUp() {
+      if (hasFailedResult) finish(resolve, failedResult, -1);
+      else finish(reject, hasError ? lastError : new Error("withHedge: no attempt succeeded"), -1);
+    }
+
+    launch();
+  });
+}
+
+module.exports = { withHedge };

package/types/http.d.ts

@@ -53,6 +53,11 @@ export interface CreateFetchDefaults {
    * `trustedOrigins` there's nothing to compare against and credentials go everywhere.
    */
   trustedOrigins?: string[];
+  /**
+   * Send a backup request when an attempt is slow and take whichever answers first
+   * (idempotent methods, or requests with an Idempotency-Key). `true` = delayMs "auto".
+   */
+  hedge?: boolean | HedgeConfig;
   /** Attach a token and, on a 401, refresh it once (shared by all concurrent requests) and replay. */
   auth?: AuthOptions;
   /** In-memory GET cache with TTL, stale-while-revalidate and ETag/Last-Modified revalidation. `true` = 60s TTL. */
@@ -76,6 +81,8 @@ export interface ReqkitRequestInit extends Omit<RequestInit, "headers" | "cache"
   timeout?: number | false;
   retry?: false | CreateFetchRetryOptions;
   throwHttpErrors?: boolean;
+  /** `false` disables hedging for this call; an object overrides the defaults. */
+  hedge?: boolean | HedgeConfig;
   /** `false`/"no-store" bypass the cache; "reload" skips the read but refreshes the entry. */
   cache?: false | "no-store" | "reload";
 }
@@ -105,6 +112,23 @@ export interface MemoryCache extends CacheStore {
 
 export function createMemoryCache(opts?: { maxEntries?: number }): MemoryCache;
 
+export interface HedgeConfig {
+  /** Milliseconds before a backup is sent, or "auto" (default) to use your own recent latency. */
+  delayMs?: number | "auto";
+  /** Backups per attempt. Default 1. */
+  maxHedges?: number;
+  /** Methods that may be hedged. Default: the idempotent ones (GET, HEAD, OPTIONS, PUT, DELETE). */
+  methods?: string[];
+  /** For "auto": which percentile of recent latency to wait for. Default 0.95. */
+  percentile?: number;
+  /** For "auto": never hedge sooner than this. Default 20. */
+  minDelayMs?: number;
+  /** For "auto": the delay used until `minSamples` responses were seen. Default 300. */
+  fallbackDelayMs?: number;
+  /** For "auto": samples needed before trusting the percentile. Default 10. */
+  minSamples?: number;
+}
+
 export interface CacheEvent {
   type: "hit" | "stale" | "revalidated" | "miss" | "store" | "stale-if-error";
   url: string;
@@ -172,8 +196,13 @@ export type FetchEvent =
       attempts: number;
       /** How the cache was involved, if it was. */
       cache?: "hit" | "stale" | "revalidated" | "miss" | "stale-if-error";
+      /** Backup requests sent for this call. */
+      hedges: number;
+      /** True when a backup request produced the response. */
+      hedgeWon: boolean;
     }
-  | { type: "error"; url?: string; method?: string; error: unknown; durationMs: number; attempts: number }
+  | { type: "error"; url?: string; method?: string; error: unknown; durationMs: number; attempts: number; hedges: number }
+  | { type: "hedge"; url: string; method: string; /** 1-based backup number */ index: number; /** ms since the call's attempt began */ afterMs: number }
   | { type: "cache"; url: string; method: "GET"; event: CacheEvent["type"] }
   | { type: "ratelimit"; url: string; method: string; waitedMs: number }
   | { type: "circuit"; origin: string; state: CircuitState; previous: CircuitState }

package/types/resilience.d.ts

@@ -169,3 +169,26 @@ export interface CircuitBreaker {
 }
 
 export function createCircuitBreaker(opts?: CircuitBreakerOptions): CircuitBreaker;
+
+export interface HedgeOptions<T = any> {
+  /** Wait before launching backup #index (1-based): a number of ms, or a function of the index. */
+  delayMs: number | ((index: number) => number);
+  /** How many backups at most. Default 1. */
+  maxHedges?: number;
+  /** Results that count as failed (and launch the next backup at once). Default: `result.status >= 500`. */
+  isFailure?: (result: T) => boolean;
+  /** Launch the next backup immediately when an attempt throws. Default true. */
+  hedgeOnError?: boolean;
+  /** A backup was launched. */
+  onHedge?: (info: { index: number; afterMs: number }) => void;
+  /** Which attempt produced the result (0 = the original). */
+  onWinner?: (index: number) => void;
+  /** Cancels everything; rejects with the signal's reason. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Hedged requests: if `fn` hasn't answered after `delayMs`, start a backup and take whichever
+ * succeeds first; the others are aborted. Only hedge calls that are safe to run twice.
+ */
+export function withHedge<T>(fn: (signal: AbortSignal, index: number) => Promise<T> | T, opts: HedgeOptions<T>): Promise<T>;