@boy-offi9-inc/reqkit 0.7.1 → 0.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.7.1",
-  "description": "Small, composable HTTP helpers — 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.",
+  "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",
   "exports": {
@@ -27,7 +27,8 @@
     "test": "node --test",
     "typecheck": "tsc -p tsconfig.json",
     "smoke": "node smoke/run.mjs",
-    "prepublishOnly": "npm run build && npm test && npm run typecheck"
+    "check": "npm run build && npm test && npm run typecheck && npm run smoke",
+    "prepublishOnly": "npm run check"
   },
   "keywords": [
     "http",
@@ -61,7 +62,12 @@
     "pagination",
     "auth",
     "token-refresh",
-    "link-header"
+    "link-header",
+    "stale-if-error",
+    "observability",
+    "logging",
+    "hedged-requests",
+    "tail-latency"
   ],
   "author": "Boy Offi9",
   "license": "MIT",
@@ -83,8 +89,8 @@
     "src",
     "types",
     "dist",
+    "docs/recipes.md",
     "README.md",
-    "RECIPES.md",
     "LICENSE"
   ],
   "devDependencies": {

package/src/{createFetch.js → http/createFetch.js}

@@ -1,15 +1,17 @@
-const { withRetry, RetryAbortedError } = require("./withRetry");
-const { withTimeout } = require("./withTimeout");
-const { withDedupe } = require("./withDedupe");
+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("./normalizeError");
-const { HTTPError } = require("./HTTPError");
-const { createRateLimiter } = require("./createRateLimiter");
-const { createCircuitBreaker } = require("./createCircuitBreaker");
-const { createMemoryCache } = require("./createMemoryCache");
-const { cacheKey, snapshotResponse, entryToResponse } = require("./_cache");
-const { discardBody, getOrigin } = require("./_http");
+const { normalizeError } = require("../errors/normalizeError");
+const { HTTPError } = require("../errors/HTTPError");
+const { createRateLimiter } = require("../resilience/rateLimiter");
+const { createCircuitBreaker } = require("../resilience/circuitBreaker");
+const { createMemoryCache } = require("./cache/memoryCache");
+const { cacheKey, snapshotResponse, entryToResponse } = require("./cache/entry");
+const { discardBody, getOrigin } = require("../internal/http");
 
 const DEFAULT_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
 // Safe to repeat without side effects. POST/PATCH are deliberately absent.
@@ -94,8 +96,13 @@ function mergeDefaults(base, extra) {
  *  - `rateLimit`: stay under a budget and obey X-RateLimit-* / Retry-After
  *    *before* the server has to say 429
  *  - `circuitBreaker`: fail fast against a service that keeps failing
- *  - `cache`: in-memory GET cache with TTL, stale-while-revalidate and
- *    ETag / Last-Modified revalidation (304s)
+ *  - `cache`: in-memory GET cache with TTL, stale-while-revalidate,
+ *    stale-if-error and ETag / Last-Modified revalidation (304s)
+ *  - `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
@@ -117,8 +124,9 @@ function mergeDefaults(base, extra) {
  *   createRateLimiter() instance to share one budget
  * @param {boolean | object | Function} [defaults.circuitBreaker] - options for
  *   a per-origin breaker, a createCircuitBreaker() instance, or `(url) => breaker`
- * @param {boolean | object} [defaults.cache] - `{ ttl, staleWhileRevalidate,
- *   maxEntries, maxBodyBytes, store, onEvent }`; `true` = 60s TTL
+ * @param {boolean | object} [defaults.cache] - `{ ttl, staleWhileRevalidate, staleIfError,
+ *   maxEntries, maxBodyBytes, store, onEvent }`; `true` = 60s TTL. `staleIfError` (ms) lets a
+ *   cached copy be served for that long past its TTL when the network fails or the server answers 5xx.
  * @param {object} [defaults.auth] - `{ getToken, refresh, header?, scheme?, shouldRefresh? }`.
  *   `getToken()` supplies the current token (sync or async); on a 401 (or
  *   whatever `shouldRefresh(response)` says) `refresh({ token, response })` is
@@ -127,12 +135,20 @@ 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]
  * @param {(ctx: {url: string, init: object}) => void | Promise<void>} [defaults.onRequest] -
  *   runs once per call; may mutate ctx.url / ctx.init (e.g. add a header)
  * @param {(ctx: {url: string, init: object, response: Response}) => void | Promise<void>} [defaults.onResponse]
+ * @param {(event: object) => void | Promise<void>} [defaults.onEvent] - receives `{ type, ... }` events:
+ *   "request", "attempt", "retry", "response", "error", "cache", "ratelimit", "circuit", "auth".
+ *   Errors thrown by the handler are swallowed — logging must never break a request.
  */
 function createFetch(defaults = {}) {
   const {
@@ -145,15 +161,28 @@ function createFetch(defaults = {}) {
     cache,
     auth,
     trustedOrigins,
+    hedge,
     dedupe = false,
     throwHttpErrors: defaultThrow = true,
     fetch: customFetch,
     onRequest,
     onResponse,
+    onEvent,
   } = defaults;
 
   const doFetch = (...args) => (customFetch || globalThis.fetch)(...args);
 
+  // A throwing (or rejecting) handler must never break a request.
+  const emitEvent = (event) => {
+    if (!onEvent) return;
+    try {
+      const result = onEvent(event);
+      if (result && typeof result.catch === "function") result.catch(() => {});
+    } catch {
+      // ignore
+    }
+  };
+
   // Origins allowed to receive default credentials. Empty = no baseUrl to compare against = unrestricted.
   const trusted = new Set();
   for (const o of [baseUrl, ...(trustedOrigins || [])]) {
@@ -183,7 +212,13 @@ function createFetch(defaults = {}) {
         : (url) => {
             const origin = originOf(url);
             if (!breakerRegistry.has(origin)) {
-              breakerRegistry.set(origin, createCircuitBreaker(circuitBreaker === true ? {} : circuitBreaker));
+              const options = circuitBreaker === true ? {} : { ...circuitBreaker };
+              const userOnStateChange = options.onStateChange;
+              options.onStateChange = (state, previous) => {
+                if (userOnStateChange) userOnStateChange(state, previous);
+                emitEvent({ type: "circuit", origin, state, previous });
+              };
+              breakerRegistry.set(origin, createCircuitBreaker(options));
             }
             return breakerRegistry.get(origin);
           };
@@ -193,6 +228,7 @@ function createFetch(defaults = {}) {
     : {
         ttl: 60000,
         staleWhileRevalidate: 0,
+        staleIfError: 0,
         maxEntries: 100,
         maxBodyBytes: undefined,
         ...(cache === true ? {} : cache),
@@ -206,7 +242,16 @@ function createFetch(defaults = {}) {
   }
   const pendingStores = cacheCfg ? cacheCfg.pending : null;
   const revalidating = cacheCfg ? cacheCfg.revalidating : null;
-  const emit = (type, url) => cacheCfg && cacheCfg.onEvent && cacheCfg.onEvent({ type, url });
+  const emit = (type, url) => {
+    if (cacheCfg && cacheCfg.onEvent) cacheCfg.onEvent({ type, url });
+    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.
@@ -230,9 +275,12 @@ function createFetch(defaults = {}) {
   // Returns a token newer than `usedToken`, refreshing at most once no matter
   // how many requests were rejected at the same time. If someone else already
   // refreshed (the current token isn't the one we used), just use that.
-  async function obtainFreshToken(authCfg, tokenUsed, response) {
+  async function obtainFreshToken(authCfg, tokenUsed, response, info) {
     const current = await authCfg.getToken();
-    if (current && current !== tokenUsed) return current;
+    if (current && current !== tokenUsed) {
+      emitEvent({ type: "auth", ...info, outcome: "reused" });
+      return current;
+    }
 
     const state = refreshStateFor(authCfg);
     if (!state.inflight) {
@@ -245,10 +293,21 @@ function createFetch(defaults = {}) {
         }
       })();
     }
-    return state.inflight;
+    try {
+      const token = await state.inflight;
+      emitEvent({ type: "auth", ...info, outcome: "refreshed" });
+      return token;
+    } catch (error) {
+      emitEvent({ type: "auth", ...info, outcome: "failed", error });
+      throw error;
+    }
   }
 
-  async function request(input, init = {}) {
+  // May a cached copy be served because the origin is failing?
+  const withinStaleIfError = (entry) =>
+    cacheCfg && cacheCfg.staleIfError > 0 && Date.now() - entry.storedAt < cacheCfg.ttl + cacheCfg.staleIfError;
+
+  async function execute(input, init, state) {
     const {
       query,
       json,
@@ -258,11 +317,14 @@ function createFetch(defaults = {}) {
       signal,
       headers: initHeaders,
       cache: cacheMode,
+      hedge: hedgeOpt,
       ...fetchInit
     } = init;
 
     const method = String(fetchInit.method || "GET").toUpperCase();
     const url = joinUrl(baseUrl, input, query);
+    state.url = url;
+    state.method = method;
     const credentialsAllowed = isTrustedTarget(url);
 
     const defaultHeaderSet = await resolveHeaders(defaultHeaders);
@@ -285,6 +347,9 @@ function createFetch(defaults = {}) {
     if (onRequest) await onRequest(ctx);
     const finalHeaders = ctx.init.headers instanceof Headers ? ctx.init.headers : new Headers(ctx.init.headers);
     const finalMethod = String(ctx.init.method || method).toUpperCase();
+    state.url = ctx.url;
+    state.method = finalMethod;
+    emitEvent({ type: "request", url: ctx.url, method: finalMethod });
 
     // --- auth: attach the current token (unless the caller set the header) ----
     const authHeader = auth ? String(auth.header || "authorization").toLowerCase() : null;
@@ -305,18 +370,48 @@ 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.
     function network(netHeaders, netSignal) {
       const attemptOnce = () => {
-        const attempt = async () => {
-          if (limiter) await limiter.acquire({ signal: netSignal });
+        state.attempts++;
+        emitEvent({ type: "attempt", url: ctx.url, method: finalMethod, attempt: state.attempts });
+        // 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 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
@@ -329,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();
       };
@@ -343,6 +454,19 @@ function createFetch(defaults = {}) {
             ...retryRest,
             retries,
             retryStatusCodes: statusCodes || DEFAULT_RETRY_STATUS_CODES,
+            onRetry: (err, attempt, delayMs, rctx) => {
+              if (retryRest.onRetry) retryRest.onRetry(err, attempt, delayMs, rctx);
+              emitEvent({
+                type: "retry",
+                url: ctx.url,
+                method: finalMethod,
+                attempt: attempt + 1,
+                delayMs,
+                reason: rctx.reason === "result" ? "status" : "error",
+                status: rctx.status,
+                error: err,
+              });
+            },
             shouldRetry:
               customShouldRetry ||
               ((err) => {
@@ -374,6 +498,19 @@ function createFetch(defaults = {}) {
     let entry = null;
 
     const finish = async (response) => {
+      state.responded = true;
+      emitEvent({
+        type: "response",
+        url: ctx.url,
+        method: finalMethod,
+        status: response.status,
+        ok: response.ok,
+        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) {
         throw new HTTPError(response, { method: finalMethod, url: ctx.url });
@@ -388,10 +525,12 @@ function createFetch(defaults = {}) {
         const age = Date.now() - entry.storedAt;
         if (age < cacheCfg.ttl) {
           emit("hit", ctx.url);
+          state.cache = "hit";
           return finish(entryToResponse(entry));
         }
         if (age < cacheCfg.ttl + cacheCfg.staleWhileRevalidate) {
           emit("stale", ctx.url);
+          state.cache = "stale";
           if (!revalidating.has(key)) {
             revalidating.add(key);
             const staleEntry = entry;
@@ -428,13 +567,19 @@ function createFetch(defaults = {}) {
     } catch (err) {
       // Present a user abort as the plain AbortError they caused, not as retry internals.
       if (err instanceof RetryAbortedError && signal && signal.aborted) throw signal.reason ?? err;
+      // The network failed but we still hold a usable copy: serve it (never for a deliberate abort).
+      if (entry && withinStaleIfError(entry) && !(signal && signal.aborted) && !(err && err.name === "AbortError")) {
+        emit("stale-if-error", ctx.url);
+        state.cache = "stale-if-error";
+        return finish(entryToResponse(entry));
+      }
       throw err;
     }
 
     // --- auth: a rejected token is refreshed once, then the request replays ----
     const needsRefresh = auth && (auth.shouldRefresh ? auth.shouldRefresh(response) : response.status === 401);
     if (usedToken && needsRefresh && !isStreamBody(ctx.init.body)) {
-      const fresh = await obtainFreshToken(auth, usedToken, response);
+      const fresh = await obtainFreshToken(auth, usedToken, response, { url: ctx.url, method: finalMethod });
       if (fresh) {
         await discardBody(response);
         finalHeaders.set(authHeader, formatToken(fresh));
@@ -449,15 +594,25 @@ function createFetch(defaults = {}) {
       }
     }
 
+    // The server answered, but with an error, and we still hold a usable copy.
+    if (useCache && entry && response.status >= 500 && withinStaleIfError(entry)) {
+      await discardBody(response);
+      emit("stale-if-error", ctx.url);
+      state.cache = "stale-if-error";
+      return finish(entryToResponse(entry));
+    }
+
     if (useCache) {
       if (response.status === 304 && entry) {
         entry.storedAt = Date.now();
         await cacheCfg.store.set(key, entry);
         emit("revalidated", ctx.url);
+        state.cache = "revalidated";
         await discardBody(response);
         response = entryToResponse(entry);
       } else {
         emit("miss", ctx.url);
+        state.cache = "miss";
         if (response.status === 200) scheduleStore(key, response, ctx.url);
       }
     }
@@ -465,6 +620,27 @@ function createFetch(defaults = {}) {
     return finish(response);
   }
 
+  async function request(input, init = {}) {
+    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,
+          hedges: state.hedges,
+        });
+      }
+      throw error;
+    }
+  }
+
   /** The `baseUrl` this instance was created with (paginateLinks uses it to stay on-origin). */
   request.baseUrl = baseUrl;
 
@@ -486,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,27 +1,29 @@
-const { withRetry, RetryAbortedError, StopRetry } = require("./withRetry");
-const { withTimeout, TimeoutError } = require("./withTimeout");
-const { normalizeError } = require("./normalizeError");
-const { parseJsonSafe } = require("./parseJsonSafe");
-const { buildQuery } = require("./buildQuery");
-const { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders } = require("./retryAfterAware");
-const { withProgress, BodyTooLargeError } = require("./withProgress");
-const { withDedupe } = require("./withDedupe");
-const { createLimiter } = require("./createLimiter");
-const { createFetch, HTTPError } = require("./createFetch");
-const { createRateLimiter } = require("./createRateLimiter");
-const { createCircuitBreaker, CircuitOpenError } = require("./createCircuitBreaker");
-const { createMemoryCache } = require("./createMemoryCache");
-const { createMockFetch } = require("./createMockFetch");
-const { downloadResumable } = require("./downloadResumable");
-const { readLines, readNDJSON, readSSE } = require("./streams");
-const { streamSSE } = require("./streamSSE");
-const { paginate, paginatePages, paginateLinks, parseLinkHeader } = require("./paginate");
+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");
+const { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders } = require("./resilience/retryAfterAware");
+const { withProgress, BodyTooLargeError } = require("./streams/progress");
+const { withDedupe } = require("./resilience/dedupe");
+const { createLimiter } = require("./resilience/limiter");
+const { createFetch, HTTPError } = require("./http/createFetch");
+const { createRateLimiter } = require("./resilience/rateLimiter");
+const { createCircuitBreaker, CircuitOpenError } = require("./resilience/circuitBreaker");
+const { createMemoryCache } = require("./http/cache/memoryCache");
+const { createMockFetch } = require("./testing/createMockFetch");
+const { downloadResumable } = require("./streams/download");
+const { readLines, readNDJSON, readSSE } = require("./streams/readers");
+const { streamSSE } = require("./streams/streamSSE");
+const { paginate, paginatePages, paginateLinks, parseLinkHeader } = require("./pagination/paginate");
 
 module.exports = {
   withRetry,
   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/{paginate.js → pagination/paginate.js}

@@ -1,5 +1,5 @@
-const { HTTPError } = require("./HTTPError");
-const { getOrigin } = require("./_http");
+const { HTTPError } = require("../errors/HTTPError");
+const { getOrigin } = require("../internal/http");
 
 const MAX_LINK_HEADER_LENGTH = 64 * 1024;