@boy-offi9-inc/reqkit 0.7.1 → 0.9.0

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/src/{createRateLimiter.js → resilience/rateLimiter.js}

@@ -1,5 +1,5 @@
-const { abortableSleep } = require("./_sleep");
-const { getRateLimitInfo } = require("./_http");
+const { abortableSleep } = require("../internal/sleep");
+const { getRateLimitInfo } = require("../internal/http");
 
 function abortable(promise, signal) {
   if (!signal) return promise;
@@ -50,6 +50,7 @@ function createRateLimiter(opts = {}) {
   let tail = Promise.resolve();
 
   async function take(signal) {
+    let waitedMs = 0;
     for (;;) {
       signal?.throwIfAborted?.();
       const now = Date.now();
@@ -61,13 +62,15 @@ function createRateLimiter(opts = {}) {
 
       if (waitMs <= 0) {
         stamps.push(now);
-        return;
+        return waitedMs;
       }
+      const waitStartedAt = Date.now();
       await abortableSleep(waitMs, signal);
+      waitedMs += Date.now() - waitStartedAt;
     }
   }
 
-  /** Resolves when it's your turn. Rejects with the signal's reason if aborted while waiting. */
+  /** Resolves with the time spent waiting. Rejects if aborted while waiting. */
   function acquire({ signal } = {}) {
     const turn = tail.then(() => take(signal));
     tail = turn.catch(() => {});

package/src/{withRetry.js → resilience/retry.js}

@@ -1,5 +1,5 @@
-const { RetryAbortedError, sleep } = require("./_sleep");
-const { getWaitMsFromHeaders, discardBody } = require("./_http");
+const { RetryAbortedError, sleep } = require("../internal/sleep");
+const { getWaitMsFromHeaders, discardBody } = require("../internal/http");
 
 function defaultShouldRetry(err) {
   // Retry thrown errors except deliberate aborts. Narrow it with `shouldRetry`

package/src/{retryAfterAware.js → resilience/retryAfterAware.js}

@@ -1,6 +1,6 @@
-const { withRetry } = require("./withRetry");
-const { normalizeError } = require("./normalizeError");
-const { parseRetryAfter, getWaitMsFromHeaders } = require("./_http");
+const { withRetry } = require("./retry");
+const { normalizeError } = require("../errors/normalizeError");
+const { parseRetryAfter, getWaitMsFromHeaders } = require("../internal/http");
 
 function defaultShouldRetryError(err) {
   const normalized = normalizeError(err);

package/src/{downloadResumable.js → streams/download.js}

@@ -1,8 +1,8 @@
-const { HTTPError } = require("./HTTPError");
-const { BodyTooLargeError } = require("./withProgress");
-const { normalizeError } = require("./normalizeError");
-const { getWaitMsFromHeaders } = require("./_http");
-const { abortableSleep } = require("./_sleep");
+const { HTTPError } = require("../errors/HTTPError");
+const { BodyTooLargeError } = require("./progress");
+const { normalizeError } = require("../errors/normalizeError");
+const { getWaitMsFromHeaders } = require("../internal/http");
+const { abortableSleep } = require("../internal/sleep");
 
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 

package/src/{streamSSE.js → streams/streamSSE.js}

@@ -1,8 +1,8 @@
-const { readSSE } = require("./streams");
-const { HTTPError } = require("./HTTPError");
-const { normalizeError } = require("./normalizeError");
-const { getWaitMsFromHeaders, discardBody } = require("./_http");
-const { abortableSleep } = require("./_sleep");
+const { readSSE } = require("./readers");
+const { HTTPError } = require("../errors/HTTPError");
+const { normalizeError } = require("../errors/normalizeError");
+const { getWaitMsFromHeaders, discardBody } = require("../internal/http");
+const { abortableSleep } = require("../internal/sleep");
 
 function isRetryableStatus(status) {
   return status === 408 || status === 425 || status === 429 || status >= 500;

package/src/{createMockFetch.js → testing/createMockFetch.js}

@@ -1,4 +1,4 @@
-const { abortableSleep } = require("./_sleep");
+const { abortableSleep } = require("../internal/sleep");
 
 const BODYLESS = new Set([101, 204, 205, 304]);
 

package/types/errors.d.ts

@@ -0,0 +1,24 @@
+// Error types and classification — src/errors/
+
+export interface NormalizedError {
+  message: string;
+  status: number | null;
+  code: string | null;
+  isNetworkError: boolean;
+  isTimeout: boolean;
+  /** True when the request was cancelled on purpose (AbortController, axios cancel). */
+  isAborted: boolean;
+  cause: unknown;
+}
+
+export function normalizeError(err: unknown): NormalizedError;
+
+export class HTTPError extends Error {
+  name: "HTTPError";
+  status: number;
+  statusText: string;
+  response: Response;
+  url: string;
+  method: string;
+  constructor(response: Response, request: { method: string; url: string });
+}

package/types/http.d.ts

@@ -0,0 +1,209 @@
+// createFetch and the request/response helpers — src/http/
+import type { CircuitBreaker, CircuitBreakerOptions, CircuitState, RateLimiter, RateLimiterOptions, RetryOptions } from "./resilience";
+
+export interface JsonSafeResult<T = unknown> {
+  data: T | null;
+  error: Error | null;
+}
+
+export function parseJsonSafe<T = unknown>(input: Response | string): Promise<JsonSafeResult<T>>;
+
+export function buildQuery(params: Record<string, unknown> | null | undefined): string;
+
+export interface CreateFetchRetryOptions {
+  /** Default 2. */
+  retries?: number;
+  /** Default [408, 425, 429, 500, 502, 503, 504]. */
+  statusCodes?: number[];
+  /** Methods that may be retried. Default GET, HEAD, OPTIONS, PUT, DELETE. */
+  methods?: string[];
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  factor?: number;
+  jitter?: number | "full";
+  maxRetryTime?: number;
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+  calculateDelay?: RetryOptions["calculateDelay"];
+  onRetry?: RetryOptions["onRetry"];
+}
+
+export interface FetchHookContext {
+  url: string;
+  init: RequestInit & { headers: Headers };
+}
+
+export interface CreateFetchDefaults {
+  baseUrl?: string;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  /** Per attempt, in ms. false disables. Default 30000. */
+  timeout?: number | false;
+  /** false disables retrying. */
+  retry?: false | CreateFetchRetryOptions;
+  /**
+   * `true` only learns from X-RateLimit-* / Retry-After headers; `{ requests, perMs }`
+   * also enforces a budget; or share a createRateLimiter() instance.
+   */
+  rateLimit?: boolean | RateLimiterOptions | RateLimiter;
+  /** Options for a per-origin breaker, a shared breaker instance, or `(url) => breaker`. */
+  circuitBreaker?: boolean | CircuitBreakerOptions | CircuitBreaker | ((url: string) => CircuitBreaker);
+  /**
+   * Extra origins ("https://cdn.example.com") that may receive the default credentials
+   * (`auth` and default Authorization/Cookie/X-API-Key headers), besides `baseUrl`'s.
+   * Absolute URLs to any other origin don't get them. With neither `baseUrl` nor
+   * `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. */
+  cache?: boolean | CacheOptions;
+  /** Merge identical concurrent GET/HEAD calls. Default false. */
+  dedupe?: boolean;
+  /** Throw HTTPError on non-2xx. Default true. */
+  throwHttpErrors?: boolean;
+  fetch?: typeof fetch;
+  onRequest?: (ctx: FetchHookContext) => void | Promise<void>;
+  onResponse?: (ctx: FetchHookContext & { response: Response }) => void | Promise<void>;
+  /** One callback for everything that happens. Errors thrown by the handler are ignored. */
+  onEvent?: (event: FetchEvent) => void | Promise<void>;
+}
+
+export interface ReqkitRequestInit extends Omit<RequestInit, "headers" | "cache"> {
+  headers?: HeadersInit;
+  query?: Record<string, unknown>;
+  /** Serialized as the body with a JSON content-type. */
+  json?: unknown;
+  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";
+}
+
+export interface ReqkitFetch {
+  (input: string, init?: ReqkitRequestInit): Promise<Response>;
+  /** The `baseUrl` this instance was created with. */
+  readonly baseUrl: string | undefined;
+  /** Resolves to the parsed JSON body (null for an empty body). */
+  json<T = unknown>(input: string, init?: ReqkitRequestInit): Promise<T>;
+  /** New instance with these defaults merged over the current ones. */
+  extend(overrides?: CreateFetchDefaults): ReqkitFetch;
+}
+
+export function createFetch(defaults?: CreateFetchDefaults): ReqkitFetch;
+
+export interface CacheStore {
+  get(key: string): any | Promise<any>;
+  set(key: string, value: any): void | Promise<void>;
+  delete(key: string): any;
+}
+
+export interface MemoryCache extends CacheStore {
+  clear(): void;
+  readonly size: number;
+}
+
+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;
+}
+
+export interface CacheOptions {
+  /** How long an entry is served without asking the server, in ms. Default 60000. */
+  ttl?: number;
+  /** After the TTL, keep serving the stale copy for this long while refreshing in the background. Default 0. */
+  staleWhileRevalidate?: number;
+  /**
+   * How long past the TTL a cached copy may still be served when the origin is failing
+   * (network error, timeout, open circuit, or a 5xx). 4xx responses and aborts are never masked. Default 0 (off).
+   */
+  staleIfError?: number;
+  /** For the built-in memory store. Default 100. */
+  maxEntries?: number;
+  /** Responses larger than this aren't cached. Default 1 MiB. */
+  maxBodyBytes?: number;
+  /** Bring your own store (Redis, IndexedDB, a Map...). */
+  store?: CacheStore;
+  onEvent?: (event: CacheEvent) => void;
+}
+
+export interface AuthOptions {
+  /** The current token (sync or async). Falsy = send no auth header. */
+  getToken(): string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Called ONCE when requests are rejected (401 by default), no matter how many
+   * are waiting. Return the new token, or update your store and return nothing
+   * (reqkit then calls getToken() again). Throwing rejects every waiting request.
+   */
+  refresh(ctx: { token: string; response: Response }): string | void | undefined | Promise<string | void | undefined>;
+  /** Default "authorization". */
+  header?: string;
+  /** Default "Bearer". Use "" to send the bare token (e.g. for an X-API-Key header). */
+  scheme?: string;
+  /** Default: `res.status === 401`. */
+  shouldRefresh?: (response: Response) => boolean;
+}
+
+/** Events delivered to `createFetch({ onEvent })`. */
+export type FetchEvent =
+  | { type: "request"; url: string; method: string }
+  | { type: "attempt"; url: string; method: string; /** 1-based */ attempt: number }
+  | {
+      type: "retry";
+      url: string;
+      method: string;
+      /** The attempt that failed (1-based). */
+      attempt: number;
+      delayMs: number;
+      reason: "error" | "status";
+      status?: number;
+      error?: unknown;
+    }
+  | {
+      type: "response";
+      url: string;
+      method: string;
+      status: number;
+      ok: boolean;
+      durationMs: number;
+      /** Network attempts made (0 for a cache hit). */
+      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; 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 }
+  | { type: "auth"; url: string; method: string; outcome: "refreshed" | "reused" | "failed"; error?: unknown };