@boy-offi9-inc/reqkit 0.2.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.2.0",
-  "description": "Small, composable HTTP helper functions — retry with backoff, timeouts, normalized errors, safe JSON parsing, rate-limit-aware retry, and download progress. Not a client, works alongside fetch/axios/anything.",
+  "version": "0.5.0",
+  "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.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "exports": {
@@ -15,12 +15,19 @@
         "default": "./src/index.js"
       }
     },
+    "./browser": {
+      "types": "./types/index.d.mts",
+      "default": "./dist/reqkit.mjs"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "scripts": {
+    "build": "node scripts/build-esm.js",
     "test": "node --test",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json",
+    "smoke": "node smoke/run.mjs",
+    "prepublishOnly": "npm run build && npm test && npm run typecheck"
   },
   "keywords": [
     "http",
@@ -32,7 +39,25 @@
     "retry-after",
     "download-progress",
     "error-normalization",
-    "utility"
+    "utility",
+    "limiter",
+    "concurrency",
+    "dedupe",
+    "http-client",
+    "fetch-wrapper",
+    "abort-signal",
+    "circuit-breaker",
+    "cache",
+    "sse",
+    "ndjson",
+    "streaming",
+    "resumable-download",
+    "mock",
+    "browser",
+    "deno",
+    "bun",
+    "cloudflare-workers",
+    "esm"
   ],
   "author": "Boy Offi9",
   "license": "MIT",
@@ -53,7 +78,9 @@
   "files": [
     "src",
     "types",
+    "dist",
     "README.md",
+    "RECIPES.md",
     "LICENSE"
   ],
   "devDependencies": {

package/src/HTTPError.js

@@ -0,0 +1,14 @@
+class HTTPError extends Error {
+  constructor(response, request) {
+    const statusText = response.statusText ? ` ${response.statusText}` : "";
+    super(`Request failed with status ${response.status}${statusText}: ${request.method} ${request.url}`);
+    this.name = "HTTPError";
+    this.status = response.status;
+    this.statusText = response.statusText || "";
+    this.response = response;
+    this.url = request.url;
+    this.method = request.method;
+  }
+}
+
+module.exports = { HTTPError };

package/src/_cache.js

@@ -0,0 +1,55 @@
+// Helpers for createFetch's response cache.
+
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+
+function cacheKey(method, url, headers) {
+  // Every request header is part of the key, so responses fetched with one
+  // user's Authorization header can never be served to another.
+  return `${method} ${url} ${JSON.stringify([...headers.entries()].sort())}`;
+}
+
+/**
+ * Reads a response (via a clone — the original stays usable) into a plain,
+ * storable entry. Returns null when the response must not be cached.
+ */
+async function snapshotResponse(response, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
+  if (response.status !== 200) return null;
+
+  const cacheControl = (response.headers.get("cache-control") || "").toLowerCase();
+  if (/\bno-store\b/.test(cacheControl)) return null;
+  if ((response.headers.get("vary") || "").trim() === "*") return null;
+
+  const declared = Number(response.headers.get("content-length"));
+  if (response.headers.has("content-length") && declared > maxBodyBytes) return null;
+
+  const copy = response.clone();
+  const buffer = await copy.arrayBuffer();
+  if (buffer.byteLength > maxBodyBytes) return null;
+
+  const headers = [];
+  response.headers.forEach((value, key) => {
+    // The body we stored is already decoded; replaying these would corrupt it.
+    if (key === "content-encoding" || key === "content-length" || key === "transfer-encoding") return;
+    headers.push([key, value]);
+  });
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+    body: new Uint8Array(buffer),
+    storedAt: Date.now(),
+    etag: response.headers.get("etag"),
+    lastModified: response.headers.get("last-modified"),
+  };
+}
+
+function entryToResponse(entry) {
+  return new Response(entry.body.slice(), {
+    status: entry.status,
+    statusText: entry.statusText,
+    headers: entry.headers,
+  });
+}
+
+module.exports = { cacheKey, snapshotResponse, entryToResponse, DEFAULT_MAX_BODY_BYTES };

package/src/_http.js

@@ -0,0 +1,90 @@
+/**
+ * Parses a Retry-After header value into milliseconds. Per HTTP spec it's
+ * either an integer number of seconds, or an HTTP-date.
+ */
+function parseRetryAfter(headerValue) {
+  if (headerValue === null || headerValue === undefined) return null;
+  const value = String(headerValue).trim();
+  if (!value) return null;
+
+  // delta-seconds (spec says integer; tolerate "1.5" from sloppy servers)
+  if (/^\d+(\.\d+)?$/.test(value)) {
+    return Number(value) * 1000;
+  }
+
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+
+  return null;
+}
+
+// Reset headers come in two flavors: a delta in seconds ("30", the IETF
+// RateLimit-Reset draft, Discord's *-Reset-After) or an absolute epoch
+// (GitHub/Twitter style, seconds or ms). Anything under ~31 years in seconds
+// can't be a real epoch, so treat it as a delta.
+function parseResetMs(value) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const n = Number(value);
+  if (Number.isNaN(n) || n < 0) return null;
+  if (n < 1e9) return n * 1000;
+  const epochMs = n > 4102444800 ? n : n * 1000;
+  return Math.max(0, epochMs - Date.now());
+}
+
+function readHeader(headers, ...names) {
+  for (const name of names) {
+    const v = headers.get(name);
+    if (v !== null && v !== undefined && v !== "") return v;
+  }
+  return null;
+}
+
+/**
+ * Reads a wait time from common rate-limit headers, trying Retry-After first,
+ * then falling back to X-RateLimit-Reset(-After) if present.
+ */
+function getWaitMsFromHeaders(headers) {
+  if (!headers || typeof headers.get !== "function") return null;
+
+  const retryAfter = parseRetryAfter(headers.get("retry-after"));
+  if (retryAfter !== null) return retryAfter;
+
+  return parseResetMs(
+    readHeader(headers, "x-ratelimit-reset-after", "x-ratelimit-reset", "x-rate-limit-reset", "ratelimit-reset")
+  );
+}
+
+/**
+ * Everything useful a response says about rate limits:
+ *   { remaining: number|null, resetMs: number|null, retryAfterMs: number|null }
+ * Understands X-RateLimit-*, X-Rate-Limit-*, RateLimit-* and Retry-After.
+ */
+function getRateLimitInfo(headers) {
+  const info = { remaining: null, resetMs: null, retryAfterMs: null };
+  if (!headers || typeof headers.get !== "function") return info;
+
+  const remaining = readHeader(headers, "x-ratelimit-remaining", "x-rate-limit-remaining", "ratelimit-remaining");
+  if (remaining !== null && !Number.isNaN(Number(remaining))) info.remaining = Number(remaining);
+
+  info.resetMs = parseResetMs(
+    readHeader(headers, "x-ratelimit-reset-after", "x-ratelimit-reset", "x-rate-limit-reset", "ratelimit-reset")
+  );
+  info.retryAfterMs = parseRetryAfter(headers.get("retry-after"));
+  return info;
+}
+
+async function discardBody(response) {
+  // An unread body keeps the underlying connection busy; cancel it before
+  // we sit through a backoff and fire the next request.
+  try {
+    if (response.body && typeof response.body.cancel === "function" && !response.bodyUsed) {
+      await response.body.cancel();
+    }
+  } catch {
+    // locked / already consumed / not a web stream — safe to ignore
+  }
+}
+
+module.exports = { parseRetryAfter, parseResetMs, getWaitMsFromHeaders, getRateLimitInfo, discardBody };

package/src/_sleep.js

@@ -29,4 +29,23 @@ function sleep(ms, signal, cause) {
   });
 }
 
-module.exports = { RetryAbortedError, sleep };
+/** Like sleep(), but rejects with the signal's own reason (an AbortError by default). */
+function abortableSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+module.exports = { RetryAbortedError, sleep, abortableSleep };

package/src/createCircuitBreaker.js

@@ -0,0 +1,124 @@
+class CircuitOpenError extends Error {
+  constructor(retryAfterMs) {
+    super("Circuit is open — failing fast instead of calling a service that keeps failing");
+    this.name = "CircuitOpenError";
+    // Deliberately not an E-code: this is *not* a network error and must not be retried as one.
+    this.code = "CIRCUIT_OPEN";
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+function defaultIsFailure(valueOrError, isError) {
+  if (isError) return !(valueOrError && valueOrError.name === "AbortError");
+  return Boolean(valueOrError) && typeof valueOrError.status === "number" && valueOrError.status >= 500;
+}
+
+/**
+ * Circuit breaker: after `failureThreshold` consecutive failures it "opens"
+ * and fails fast with CircuitOpenError for `resetTimeoutMs`, so a dying
+ * service isn't hammered (and your callers don't wait on it). Then it goes
+ * "half-open" and lets `halfOpenMax` probe through: success closes the
+ * circuit, failure re-opens it.
+ *
+ * By default a thrown error (except AbortError) or a result with status >= 500
+ * counts as a failure; override with `isFailure(valueOrError, isError)`.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.failureThreshold=5]
+ * @param {number} [opts.resetTimeoutMs=30000]
+ * @param {number} [opts.halfOpenMax=1]
+ * @param {(valueOrError: any, isError: boolean) => boolean} [opts.isFailure]
+ * @param {(state: string, prev: string) => void} [opts.onStateChange]
+ */
+function createCircuitBreaker(opts = {}) {
+  const {
+    failureThreshold = 5,
+    resetTimeoutMs = 30000,
+    halfOpenMax = 1,
+    isFailure = defaultIsFailure,
+    onStateChange,
+  } = opts;
+
+  let state = "closed";
+  let failures = 0;
+  let openedAt = 0;
+  let probes = 0;
+
+  function setState(next) {
+    if (next === state) return;
+    const prev = state;
+    state = next;
+    if (onStateChange) onStateChange(next, prev);
+  }
+
+  function open() {
+    openedAt = Date.now();
+    setState("open");
+  }
+
+  function current() {
+    if (state === "open" && Date.now() - openedAt >= resetTimeoutMs) {
+      probes = 0;
+      setState("half-open");
+    }
+    return state;
+  }
+
+  function recordFailure() {
+    if (state === "half-open") {
+      open();
+      return;
+    }
+    failures++;
+    if (failures >= failureThreshold) open();
+  }
+
+  function recordSuccess() {
+    failures = 0;
+    if (state === "half-open") setState("closed");
+  }
+
+  async function run(fn) {
+    const s = current();
+    if (s === "open") {
+      throw new CircuitOpenError(Math.max(0, resetTimeoutMs - (Date.now() - openedAt)));
+    }
+    let probing = false;
+    if (s === "half-open") {
+      if (probes >= halfOpenMax) throw new CircuitOpenError(0);
+      probes++;
+      probing = true;
+    }
+
+    let result;
+    try {
+      result = await fn();
+    } catch (err) {
+      if (isFailure(err, true)) recordFailure();
+      else if (probing) probes--; // e.g. an abort — free the probe slot
+      throw err;
+    }
+
+    if (isFailure(result, false)) recordFailure();
+    else recordSuccess();
+    return result;
+  }
+
+  return {
+    run,
+    get state() {
+      return current();
+    },
+    get failures() {
+      return failures;
+    },
+    /** Force the circuit closed and forget the failure count. */
+    reset() {
+      failures = 0;
+      probes = 0;
+      setState("closed");
+    },
+  };
+}
+
+module.exports = { createCircuitBreaker, CircuitOpenError };