@boy-offi9-inc/reqkit 0.2.0 → 0.5.0

package/src/withRetry.js

@@ -1,58 +1,147 @@
 const { RetryAbortedError, sleep } = require("./_sleep");
+const { getWaitMsFromHeaders, discardBody } = require("./_http");
 
 function defaultShouldRetry(err) {
-  // Retry network-level failures by default. HTTP status handling is the
-  // caller's job (they know what "failure" means for their response shape) —
-  // see retryAfterAware.js for a version that understands status codes.
+  // Retry thrown errors except deliberate aborts. Narrow it with `shouldRetry`
+  // (e.g. network errors only). HTTP *statuses* aren't errors with fetch, so
+  // opt in with `retryStatusCodes` / `shouldRetryResult`.
   return Boolean(err) && err.name !== "AbortError";
 }
 
 /**
- * Retries an async function with exponential backoff + jitter.
+ * Throw this from inside `fn` to stop retrying immediately. If you pass an
+ * Error, that exact error is what withRetry rethrows; with a string, the
+ * StopRetry itself is thrown. (Same idea as p-retry's AbortError.)
+ */
+class StopRetry extends Error {
+  constructor(reasonOrMessage) {
+    const isError = reasonOrMessage instanceof Error;
+    super(isError ? reasonOrMessage.message : String(reasonOrMessage ?? "Retrying was stopped"));
+    this.name = "StopRetry";
+    this.original = isError ? reasonOrMessage : null;
+  }
+}
+
+/**
+ * Retries an async function with exponential backoff + jitter. Retries on
+ * thrown errors, and — opt-in — on *results* too (HTTP status codes, or any
+ * predicate), honoring Retry-After / X-RateLimit-Reset when the result has
+ * headers.
  *
  * @param {(attempt: number) => Promise<any>} fn
  * @param {object} [opts]
- * @param {number} [opts.retries=3] - max retry attempts after the first try
+ * @param {number} [opts.retries=3] - max retry attempts after the first try (Infinity is fine with maxRetryTime)
  * @param {number} [opts.baseDelayMs=300] - initial delay
- * @param {number} [opts.maxDelayMs=10000] - delay ceiling
- * @param {(err: any, attempt: number) => boolean} [opts.shouldRetry]
- * @param {(err: any, attempt: number, delayMs: number) => void} [opts.onRetry]
+ * @param {number} [opts.maxDelayMs=10000] - backoff ceiling
+ * @param {number} [opts.factor=2] - backoff multiplier
+ * @param {number|"full"} [opts.jitter=0.2] - fraction of extra random delay
+ *   added on top (0 disables); "full" picks uniformly in [0, delay] — the
+ *   AWS "full jitter" strategy, best when many clients retry at once
+ * @param {number} [opts.maxRetryTime=Infinity] - total time budget in ms
+ *   across all attempts and waits; once the next wait would blow it, stop
+ *   and surface the last error/result
+ * @param {(err: any, attempt: number) => boolean} [opts.shouldRetry] - for thrown errors
+ * @param {number[]} [opts.retryStatusCodes=[]] - retry when the result's `.status` is in this list
+ * @param {(result: any, attempt: number) => boolean} [opts.shouldRetryResult] - retry on any result predicate
+ * @param {boolean} [opts.respectRetryAfter=true] - use Retry-After/X-RateLimit-Reset from `result.headers`
+ * @param {number} [opts.maxRetryAfterMs=60000] - cap on a header-provided wait
+ * @param {(info: {attempt: number, error: any, result: any, delayMs: number}) => number|false} [opts.calculateDelay]
+ *   - override the wait; return a number of ms, or false to stop retrying
+ * @param {(err: any, attempt: number, delayMs: number, ctx: {reason: "error"|"result", result?: any, status?: number}) => void} [opts.onRetry]
+ *   - `err` is undefined when the retry was triggered by a result
  * @param {AbortSignal} [opts.signal] - cancels the whole retry loop,
- *   including any pending backoff wait, throwing RetryAbortedError. This is
- *   separate from a per-call AbortSignal you might pass into `fn` yourself —
- *   this one governs whether *another attempt starts at all*.
+ *   including any pending backoff wait, throwing RetryAbortedError (with the
+ *   last failure as `cause`). Separate from a per-call signal you pass into
+ *   `fn` yourself — this one governs whether *another attempt starts at all*.
  */
 async function withRetry(fn, opts = {}) {
   const {
     retries = 3,
     baseDelayMs = 300,
     maxDelayMs = 10000,
+    factor = 2,
+    jitter = 0.2,
+    maxRetryTime = Infinity,
     shouldRetry = defaultShouldRetry,
+    retryStatusCodes = [],
+    shouldRetryResult,
+    respectRetryAfter = true,
+    maxRetryAfterMs = 60000,
+    calculateDelay,
     onRetry,
     signal,
   } = opts;
 
+  const startedAt = Date.now();
+
+  function backoff(attempt) {
+    const exponential = Math.min(baseDelayMs * factor ** attempt, maxDelayMs);
+    if (jitter === "full") return Math.round(Math.random() * exponential);
+    const extra = Math.random() * exponential * (Number(jitter) || 0);
+    return Math.round(exponential + extra);
+  }
+
+  // Returns the wait in ms, or null if retrying should stop (custom
+  // calculateDelay said so, or the time budget would be exceeded).
+  function planWait(defaultMs, attempt, error, result) {
+    let waitMs = defaultMs;
+    if (calculateDelay) {
+      const custom = calculateDelay({ attempt, error, result, delayMs: defaultMs });
+      if (custom === false || custom === null || custom === undefined) return null;
+      waitMs = Math.max(0, Number(custom) || 0);
+    }
+    if (Date.now() - startedAt + waitMs > maxRetryTime) return null;
+    return waitMs;
+  }
+
+  function wantsResultRetry(result, attempt) {
+    if (
+      retryStatusCodes.length > 0 &&
+      result &&
+      typeof result.status === "number" &&
+      retryStatusCodes.includes(result.status)
+    ) {
+      return true;
+    }
+    return shouldRetryResult ? Boolean(shouldRetryResult(result, attempt)) : false;
+  }
+
   let lastErr;
-  for (let attempt = 0; attempt <= retries; attempt++) {
+  for (let attempt = 0; ; attempt++) {
     if (signal?.aborted) {
       throw new RetryAbortedError(lastErr);
     }
+
+    let result;
     try {
-      return await fn(attempt);
+      result = await fn(attempt);
     } catch (err) {
+      if (err instanceof StopRetry) throw err.original ?? err;
       lastErr = err;
-      const isLastAttempt = attempt === retries;
-      if (isLastAttempt || !shouldRetry(err, attempt)) {
-        throw err;
-      }
-      const exponential = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-      const jitter = Math.random() * exponential * 0.2;
-      const waitMs = Math.round(exponential + jitter);
-      if (onRetry) onRetry(err, attempt, waitMs);
+      if (attempt >= retries || !shouldRetry(err, attempt)) throw err;
+
+      const waitMs = planWait(backoff(attempt), attempt, err, undefined);
+      if (waitMs === null) throw err;
+
+      if (onRetry) onRetry(err, attempt, waitMs, { reason: "error" });
       await sleep(waitMs, signal, err);
+      continue;
     }
+
+    if (attempt >= retries || !wantsResultRetry(result, attempt)) return result;
+
+    let defaultMs = backoff(attempt);
+    if (respectRetryAfter) {
+      const headerMs = getWaitMsFromHeaders(result && result.headers);
+      if (headerMs !== null) defaultMs = Math.min(headerMs, maxRetryAfterMs);
+    }
+    const waitMs = planWait(defaultMs, attempt, undefined, result);
+    if (waitMs === null) return result;
+
+    await discardBody(result);
+    if (onRetry) onRetry(undefined, attempt, waitMs, { reason: "result", result, status: result && result.status });
+    await sleep(waitMs, signal);
   }
-  throw lastErr;
 }
 
-module.exports = { withRetry, RetryAbortedError };
+module.exports = { withRetry, RetryAbortedError, StopRetry };

package/src/withTimeout.js

@@ -7,34 +7,62 @@ class TimeoutError extends Error {
 }
 
 /**
- * Races an async function against a timeout. If `fn` accepts an AbortSignal
- * as its argument, it's passed one so the underlying request can actually be
- * cancelled (not just abandoned) — e.g. `withTimeout(signal => fetch(url, { signal }), 5000)`.
+ * Races an async function against a timeout. `fn` is handed an AbortSignal
+ * so the underlying request can actually be cancelled (not just abandoned) —
+ * e.g. `withTimeout(signal => fetch(url, { signal }), 5000)`.
+ *
+ * Pass your own `signal` to also cancel from the outside (user navigated
+ * away, shutdown...). That signal is linked into the one `fn` receives, and
+ * aborting it rejects with its reason even if `fn` ignores the signal.
+ * `ms: Infinity` disables the timer (handy to only link a signal).
  *
  * @param {(signal: AbortSignal) => Promise<any>} fn
  * @param {number} ms
+ * @param {object} [opts]
+ * @param {AbortSignal} [opts.signal] - external cancellation
  */
-async function withTimeout(fn, ms) {
+async function withTimeout(fn, ms, opts = {}) {
+  const { signal } = opts;
+
+  if (typeof ms !== "number" || Number.isNaN(ms) || ms < 0) {
+    throw new TypeError("withTimeout: `ms` must be a non-negative number (or Infinity)");
+  }
+  signal?.throwIfAborted?.();
+
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), ms);
+  let timedOut = false;
+
+  const timer =
+    ms === Infinity
+      ? null
+      : setTimeout(() => {
+          timedOut = true;
+          controller.abort(new TimeoutError(ms));
+        }, ms);
+
+  const onExternalAbort = () => controller.abort(signal.reason);
+  signal?.addEventListener("abort", onExternalAbort, { once: true });
 
-  const timeoutPromise = new Promise((_, reject) => {
-    controller.signal.addEventListener("abort", () => reject(new TimeoutError(ms)));
+  const guard = new Promise((_, reject) => {
+    controller.signal.addEventListener(
+      "abort",
+      () => reject(timedOut ? new TimeoutError(ms) : controller.signal.reason),
+      { once: true }
+    );
   });
 
   try {
-    return await Promise.race([fn(controller.signal), timeoutPromise]);
+    return await Promise.race([fn(controller.signal), guard]);
   } catch (err) {
     // If our timeout is what triggered the abort, always surface TimeoutError —
-    // regardless of whether fn's own rejection or our timeout promise "won"
-    // the race (that's a listener-registration-order detail callers shouldn't
-    // have to think about).
-    if (controller.signal.aborted) {
-      throw new TimeoutError(ms);
-    }
+    // regardless of whether fn's own rejection or our guard "won" the race
+    // (that's a listener-registration-order detail callers shouldn't have to
+    // think about).
+    if (timedOut) throw new TimeoutError(ms);
     throw err;
   } finally {
-    clearTimeout(timer);
+    if (timer) clearTimeout(timer);
+    signal?.removeEventListener("abort", onExternalAbort);
   }
 }
 

package/types/index.d.ts

@@ -1,12 +1,56 @@
+export interface RetryContext {
+  reason: "error" | "result";
+  /** The result that triggered the retry (reason "result"). */
+  result?: unknown;
+  /** The result's HTTP status (reason "result"). */
+  status?: number;
+}
+
+export interface CalculateDelayInfo {
+  attempt: number;
+  error: unknown;
+  result: unknown;
+  /** The delay reqkit would have used. */
+  delayMs: number;
+}
+
 export interface RetryOptions {
+  /** Max retries after the first try. Infinity is fine together with maxRetryTime. Default 3. */
   retries?: number;
+  /** Default 300. */
   baseDelayMs?: number;
+  /** Backoff ceiling. Default 10000. */
   maxDelayMs?: number;
+  /** Backoff multiplier. Default 2. */
+  factor?: number;
+  /** Extra random fraction (default 0.2), or "full" for uniform [0, delay]. */
+  jitter?: number | "full";
+  /** Total time budget across attempts and waits, in ms. */
+  maxRetryTime?: number;
+  /** For thrown errors. */
   shouldRetry?: (err: unknown, attempt: number) => boolean;
-  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+  /** Retry when the result's `.status` is in this list. */
+  retryStatusCodes?: number[];
+  /** Retry on any result predicate. */
+  shouldRetryResult?: (result: any, attempt: number) => boolean;
+  /** Use Retry-After / X-RateLimit-Reset from `result.headers`. Default true. */
+  respectRetryAfter?: boolean;
+  /** Cap on a header-provided wait. Default 60000. */
+  maxRetryAfterMs?: number;
+  /** Return ms to wait, or false to stop retrying. */
+  calculateDelay?: (info: CalculateDelayInfo) => number | false | null | undefined;
+  /** `err` is undefined when a result (not an error) triggered the retry. */
+  onRetry?: (err: unknown, attempt: number, delayMs: number, ctx: RetryContext) => void;
   signal?: AbortSignal;
 }
 
+/** Throw inside `fn` to stop retrying. An Error argument is rethrown as-is. */
+export class StopRetry extends Error {
+  name: "StopRetry";
+  original: Error | null;
+  constructor(reasonOrMessage?: unknown);
+}
+
 export class RetryAbortedError extends Error {
   name: "RetryAbortedError";
   /** The last failure before the loop was aborted, if there was one. */
@@ -20,7 +64,17 @@ export class TimeoutError extends Error {
   constructor(ms: number);
 }
 
-export function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, ms: number): Promise<T>;
+export interface TimeoutOptions {
+  /** External cancellation, linked into the signal `fn` receives. */
+  signal?: AbortSignal;
+}
+
+/** `ms` may be Infinity to disable the timer (only link `signal`). */
+export function withTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  opts?: TimeoutOptions
+): Promise<T>;
 
 export interface NormalizedError {
   message: string;
@@ -99,3 +153,255 @@ export function withDedupe<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts?: DedupeOptions
 ): Fn;
+
+export interface Limiter {
+  <A extends any[], R>(fn: (...args: A) => R | Promise<R>, ...args: A): Promise<R>;
+  readonly activeCount: number;
+  readonly pendingCount: number;
+  /** Runs fn(item, index) for each item through the limiter; keeps input order. */
+  map<T, R>(items: Iterable<T>, fn: (item: T, index: number) => R | Promise<R>): Promise<R[]>;
+}
+
+export function createLimiter(concurrency?: number): Limiter;
+
+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 });
+}
+
+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);
+  /** 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>;
+}
+
+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`/"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>;
+  /** 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 RateLimiterOptions {
+  /** Max requests per window. Default Infinity. */
+  requests?: number;
+  /** Window length in ms. Default 1000. */
+  perMs?: number;
+}
+
+export interface RateLimiter {
+  /** Resolves when it's your turn (FIFO). Rejects with the signal's reason if aborted while waiting. */
+  acquire(opts?: { signal?: AbortSignal }): Promise<void>;
+  /** Learn from a response's X-RateLimit-* / RateLimit-* / Retry-After headers. */
+  update(response: { status?: number; headers?: { get(name: string): string | null } } | null | undefined): void;
+  /** acquire → fn() → update(result). */
+  run<T>(fn: () => Promise<T>, opts?: { signal?: AbortSignal }): Promise<T>;
+  /** Ms until a server-imposed pause ends (0 if none). */
+  readonly blockedForMs: number;
+  reset(): void;
+}
+
+export function createRateLimiter(opts?: RateLimiterOptions): RateLimiter;
+
+export class CircuitOpenError extends Error {
+  name: "CircuitOpenError";
+  code: "CIRCUIT_OPEN";
+  /** Ms until the breaker will let a probe through. */
+  retryAfterMs: number;
+  constructor(retryAfterMs: number);
+}
+
+export interface CircuitBreakerOptions {
+  /** Consecutive failures before opening. Default 5. */
+  failureThreshold?: number;
+  /** How long to stay open before allowing a probe. Default 30000. */
+  resetTimeoutMs?: number;
+  /** Concurrent probes allowed while half-open. Default 1. */
+  halfOpenMax?: number;
+  /** Default: any thrown error except AbortError, or a result with status >= 500. */
+  isFailure?: (valueOrError: any, isError: boolean) => boolean;
+  onStateChange?: (state: CircuitState, previous: CircuitState) => void;
+}
+
+export type CircuitState = "closed" | "open" | "half-open";
+
+export interface CircuitBreaker {
+  run<T>(fn: () => Promise<T>): Promise<T>;
+  readonly state: CircuitState;
+  readonly failures: number;
+  reset(): void;
+}
+
+export function createCircuitBreaker(opts?: CircuitBreakerOptions): CircuitBreaker;
+
+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 CacheEvent {
+  type: "hit" | "stale" | "revalidated" | "miss" | "store";
+  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;
+  /** 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 MockCall {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: BodyInit | null | undefined;
+  signal?: AbortSignal;
+  /** The body parsed as JSON, if it was a JSON string. */
+  readonly json: any;
+}
+
+export interface MockReplyOptions {
+  headers?: HeadersInit;
+  /** Wait this long before answering; respects the request's AbortSignal. */
+  delayMs?: number;
+}
+
+export interface MockRoute {
+  reply(status?: number, body?: unknown, opts?: MockReplyOptions): MockRoute;
+  replyOnce(status?: number, body?: unknown, opts?: MockReplyOptions): MockRoute;
+  replyWith(fn: (call: MockCall) => Response | { status?: number; body?: unknown; headers?: HeadersInit } | Promise<Response | { status?: number; body?: unknown; headers?: HeadersInit }>): MockRoute;
+  replyWithOnce(fn: (call: MockCall) => Response | { status?: number; body?: unknown; headers?: HeadersInit } | Promise<Response | { status?: number; body?: unknown; headers?: HeadersInit }>): MockRoute;
+  fail(err?: unknown): MockRoute;
+  failOnce(err?: unknown): MockRoute;
+}
+
+export type MockMatcher = string | RegExp | ((url: string) => boolean);
+
+export interface MockFetch {
+  fetch: typeof fetch;
+  on(method: string, matcher: MockMatcher): MockRoute;
+  get(matcher: MockMatcher): MockRoute;
+  post(matcher: MockMatcher): MockRoute;
+  put(matcher: MockMatcher): MockRoute;
+  patch(matcher: MockMatcher): MockRoute;
+  delete(matcher: MockMatcher): MockRoute;
+  /** A TypeError("fetch failed") whose `cause.code` is set, like Node's fetch throws. */
+  networkError(code?: string): TypeError;
+  readonly calls: MockCall[];
+  reset(): void;
+}
+
+export function createMockFetch(): MockFetch;
+
+export interface DownloadResumableOptions {
+  fetch?: typeof fetch;
+  headers?: HeadersInit;
+  /** Consecutive attempts without progress before giving up. Default 5. */
+  retries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  onProgress?: (progress: DownloadProgress) => void;
+  /** Throws BodyTooLargeError past this many bytes. */
+  maxBytes?: number;
+  signal?: AbortSignal;
+  onRetry?: (err: unknown, attempt: number, delayMs: number, info: { resumeFrom: number }) => void;
+}
+
+export function downloadResumable(url: string, opts?: DownloadResumableOptions): Promise<Uint8Array>;
+
+export type StreamSource = Response | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
+
+export interface StreamOptions {
+  signal?: AbortSignal;
+}
+
+export interface SSEEvent {
+  event: string;
+  data: string;
+  id: string;
+  retry: number | undefined;
+}
+
+export function readLines(source: StreamSource, opts?: StreamOptions): AsyncGenerator<string, void, undefined>;
+export function readNDJSON<T = unknown>(
+  source: StreamSource,
+  opts?: StreamOptions & { skipInvalid?: boolean }
+): AsyncGenerator<T, void, undefined>;
+export function readSSE(source: StreamSource, opts?: StreamOptions): AsyncGenerator<SSEEvent, void, undefined>;