@boy-offi9-inc/reqkit 0.1.7 → 0.3.0

package/src/withProgress.js

@@ -1,48 +1,107 @@
+class BodyTooLargeError extends Error {
+  constructor(maxBytes) {
+    super(`Response body exceeded the ${maxBytes}-byte limit`);
+    this.name = "BodyTooLargeError";
+    this.code = "EBODYTOOLARGE";
+    this.maxBytes = maxBytes;
+  }
+}
+
+function cancelQuietly(reader) {
+  try {
+    const p = reader.cancel();
+    if (p && typeof p.catch === "function") p.catch(() => {});
+  } catch {
+    // already closed / released — nothing to do
+  }
+}
+
 /**
  * Reads a fetch Response body while reporting progress, and returns the
  * fully collected bytes as a Uint8Array. Works for any streamed response,
  * not just file downloads — same shape whether it's a media file, a large
  * JSON payload, or anything else worth showing progress for.
  *
- * If the server doesn't send Content-Length, `total` will be null in the
- * progress callback — the loaded count is still accurate.
+ * `total` is null (and `percent` with it) when the size isn't trustworthy:
+ * no Content-Length, or a Content-Encoding is applied (Content-Length is then
+ * the *compressed* size while fetch hands you *decompressed* bytes, so
+ * loaded could exceed total). `percent` is always clamped to 0–100.
  *
  * @param {Response} response
- * @param {(progress: { loaded: number, total: number | null, percent: number | null }) => void} onProgress
+ * @param {(progress: { loaded: number, total: number | null, percent: number | null }) => void} [onProgress]
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes] - abort with BodyTooLargeError once more
+ *   than this many bytes have been received
+ * @param {AbortSignal} [opts.signal] - cancels the read; rejects with the
+ *   signal's reason (an AbortError by default)
  * @returns {Promise<Uint8Array>}
  */
-async function withProgress(response, onProgress) {
+async function withProgress(response, onProgress, opts = {}) {
+  const { maxBytes, signal } = opts;
+  signal?.throwIfAborted?.();
+
   if (!response.body || typeof response.body.getReader !== "function") {
     // No streaming support available — fall back to a single-shot read,
     // still reporting one final progress event so callers don't need a branch.
     const buf = new Uint8Array(await response.arrayBuffer());
+    signal?.throwIfAborted?.();
+    if (maxBytes !== undefined && buf.byteLength > maxBytes) {
+      throw new BodyTooLargeError(maxBytes);
+    }
     if (onProgress) {
       onProgress({ loaded: buf.byteLength, total: buf.byteLength, percent: 100 });
     }
     return buf;
   }
 
+  const encoding = response.headers?.get?.("content-encoding");
+  const encoded = Boolean(encoding) && encoding.trim().toLowerCase() !== "identity";
   const contentLength = response.headers?.get?.("content-length");
-  const total = contentLength ? Number(contentLength) : null;
+  const parsed = contentLength ? Number(contentLength) : NaN;
+  const total = !encoded && Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 
   const reader = response.body.getReader();
+
+  // Fail fast when the declared size already exceeds the cap.
+  if (maxBytes !== undefined && total !== null && total > maxBytes) {
+    cancelQuietly(reader);
+    throw new BodyTooLargeError(maxBytes);
+  }
+
+  const onAbort = () => cancelQuietly(reader);
+  signal?.addEventListener("abort", onAbort, { once: true });
+
   const chunks = [];
   let loaded = 0;
+  let finished = false;
 
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      // reader.cancel() on abort makes read() resolve as done — check the
+      // signal first so an aborted read never looks like a complete one.
+      signal?.throwIfAborted?.();
+      if (done) break;
 
-    chunks.push(value);
-    loaded += value.byteLength;
+      chunks.push(value);
+      loaded += value.byteLength;
 
-    if (onProgress) {
-      onProgress({
-        loaded,
-        total,
-        percent: total ? Math.round((loaded / total) * 100) : null,
-      });
+      if (maxBytes !== undefined && loaded > maxBytes) {
+        throw new BodyTooLargeError(maxBytes);
+      }
+
+      if (onProgress) {
+        onProgress({
+          loaded,
+          total,
+          percent: total ? Math.min(100, Math.round((loaded / total) * 100)) : null,
+        });
+      }
     }
+    finished = true;
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    if (!finished) cancelQuietly(reader);
   }
 
   const result = new Uint8Array(loaded);
@@ -54,4 +113,4 @@ async function withProgress(response, onProgress) {
   return result;
 }
 
-module.exports = { withProgress };
+module.exports = { withProgress, BodyTooLargeError };

package/src/withRetry.js

@@ -1,83 +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";
 }
 
-class RetryAbortedError extends Error {
-  constructor() {
-    super("Retry loop was aborted");
-    this.name = "RetryAbortedError";
+/**
+ * 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;
   }
 }
 
-function delay(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new RetryAbortedError());
-      return;
-    }
-    const timer = setTimeout(resolve, ms);
-    if (signal) {
-      signal.addEventListener(
-        "abort",
-        () => {
-          clearTimeout(timer);
-          reject(new RetryAbortedError());
-        },
-        { once: true }
-      );
-    }
-  });
-}
-
 /**
- * Retries an async function with exponential backoff + jitter.
+ * 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();
+      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);
-      await delay(waitMs, signal);
+      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.mts

@@ -0,0 +1,3 @@
+import * as reqkit from "./index.js";
+export * from "./index.js";
+export default reqkit;

package/types/index.d.ts

@@ -1,14 +1,60 @@
+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. */
+  cause?: unknown;
 }
 
 export function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
@@ -18,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;
@@ -26,6 +82,8 @@ export interface NormalizedError {
   code: string | null;
   isNetworkError: boolean;
   isTimeout: boolean;
+  /** True when the request was cancelled on purpose (AbortController, axios cancel). */
+  isAborted: boolean;
   cause: unknown;
 }
 
@@ -46,6 +104,11 @@ export interface RetryAfterAwareOptions {
   fallbackDelayMs?: number;
   maxDelayMs?: number;
   onRetry?: (status: number, waitMs: number, attempt: number) => void;
+  /** Decide whether a thrown error is retried. Default: network errors and timeouts only. */
+  shouldRetryError?: (err: unknown, attempt: number) => boolean;
+  onRetryError?: (err: unknown, waitMs: number, attempt: number) => void;
+  /** Cancels the retry loop, including any pending wait. Throws RetryAbortedError. */
+  signal?: AbortSignal;
 }
 
 export function retryAfterAware(
@@ -62,9 +125,24 @@ export interface DownloadProgress {
   percent: number | null;
 }
 
+export interface WithProgressOptions {
+  /** Reject with BodyTooLargeError once more than this many bytes arrive. */
+  maxBytes?: number;
+  /** Cancels the read; rejects with the signal's reason. */
+  signal?: AbortSignal;
+}
+
+export class BodyTooLargeError extends Error {
+  name: "BodyTooLargeError";
+  code: "EBODYTOOLARGE";
+  maxBytes: number;
+  constructor(maxBytes: number);
+}
+
 export function withProgress(
   response: Response,
-  onProgress?: (progress: DownloadProgress) => void
+  onProgress?: (progress: DownloadProgress) => void,
+  opts?: WithProgressOptions
 ): Promise<Uint8Array>;
 
 export interface DedupeOptions {
@@ -75,3 +153,81 @@ 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;
+  /** 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"> {
+  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;
+}
+
+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;