@boy-offi9-inc/reqkit 0.3.0 → 0.5.0

package/src/downloadResumable.js

@@ -0,0 +1,193 @@
+const { HTTPError } = require("./HTTPError");
+const { BodyTooLargeError } = require("./withProgress");
+const { normalizeError } = require("./normalizeError");
+const { getWaitMsFromHeaders } = require("./_http");
+const { abortableSleep } = require("./_sleep");
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+function parseContentRange(header) {
+  // "bytes 100-199/1000" (total may be "*")
+  const m = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/i.exec(String(header || "").trim());
+  if (!m) return null;
+  return { start: Number(m[1]), end: Number(m[2]), total: m[3] === "*" ? null : Number(m[3]) };
+}
+
+function isRetryable(err) {
+  if (err instanceof BodyTooLargeError) return false;
+  if (err instanceof HTTPError) return RETRYABLE_STATUS.has(err.status);
+  const n = normalizeError(err);
+  if (n.isAborted) return false;
+  return n.isNetworkError || n.isTimeout;
+}
+
+/**
+ * Downloads a URL into memory and, if the connection drops mid-body, resumes
+ * from where it stopped with an HTTP `Range` request instead of starting
+ * over. Uses `If-Range` with the first response's strong ETag (or
+ * Last-Modified) so a file that changed on the server is restarted rather
+ * than stitched together wrongly. If the server ignores Range, it simply
+ * restarts from zero.
+ *
+ * `retries` counts consecutive attempts *without progress* — a flaky link
+ * that keeps making headway keeps going. Honors Retry-After on 429/503.
+ *
+ * ```js
+ * const bytes = await downloadResumable(url, {
+ *   onProgress: ({ percent }) => console.log(percent),
+ *   maxBytes: 200 * 1024 * 1024,
+ * });
+ * ```
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetch=globalThis.fetch] - e.g. `createFetch(...)` or a mock
+ * @param {HeadersInit} [opts.headers]
+ * @param {number} [opts.retries=5]
+ * @param {number} [opts.baseDelayMs=500]
+ * @param {number} [opts.maxDelayMs=10000]
+ * @param {(p: {loaded: number, total: number | null, percent: number | null}) => void} [opts.onProgress]
+ * @param {number} [opts.maxBytes] - throws BodyTooLargeError past this
+ * @param {AbortSignal} [opts.signal]
+ * @param {(err: any, attempt: number, delayMs: number, info: {resumeFrom: number}) => void} [opts.onRetry]
+ * @returns {Promise<Uint8Array>}
+ */
+async function downloadResumable(url, opts = {}) {
+  const {
+    fetch: fetchFn = globalThis.fetch,
+    headers,
+    retries = 5,
+    baseDelayMs = 500,
+    maxDelayMs = 10000,
+    onProgress,
+    maxBytes,
+    signal,
+    onRetry,
+  } = opts;
+
+  const chunks = [];
+  let loaded = 0;
+  let total = null;
+  let validator = null;
+  let attempt = 0; // consecutive attempts without progress
+
+  const report = () => {
+    if (onProgress) {
+      onProgress({ loaded, total, percent: total ? Math.min(100, Math.round((loaded / total) * 100)) : null });
+    }
+  };
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+    const loadedBefore = loaded;
+
+    try {
+      const reqHeaders = new Headers(headers || undefined);
+      // Range offsets count encoded bytes, so ask for an uncompressed body.
+      if (!reqHeaders.has("accept-encoding")) reqHeaders.set("accept-encoding", "identity");
+      if (loaded > 0) {
+        reqHeaders.set("range", `bytes=${loaded}-`);
+        if (validator) reqHeaders.set("if-range", validator);
+      }
+
+      const res = await fetchFn(url, { headers: reqHeaders, signal });
+
+      if (res.status === 416 && loaded > 0) {
+        // Our offset no longer fits the file — start over, without burning a retry.
+        await res.body?.cancel?.().catch(() => {});
+        chunks.length = 0;
+        loaded = 0;
+        continue;
+      }
+      if (!res.ok) {
+        await res.body?.cancel?.().catch(() => {});
+        throw new HTTPError(res, { method: "GET", url });
+      }
+
+      const encoding = res.headers.get("content-encoding");
+      const encoded = Boolean(encoding) && encoding.trim().toLowerCase() !== "identity";
+
+      if (loaded > 0) {
+        const range = res.status === 206 ? parseContentRange(res.headers.get("content-range")) : null;
+        if (!range || range.start !== loaded || encoded) {
+          // Server ignored Range, the file changed (If-Range failed), or the
+          // bytes don't line up: discard and restart from the beginning.
+          chunks.length = 0;
+          loaded = 0;
+        }
+      }
+
+      if (loaded === 0) {
+        const range = res.status === 206 ? parseContentRange(res.headers.get("content-range")) : null;
+        const length = Number(res.headers.get("content-length"));
+        total = encoded ? null : range ? range.total : Number.isFinite(length) && res.headers.has("content-length") ? length : null;
+        const etag = res.headers.get("etag");
+        validator = etag && !etag.startsWith("W/") ? etag : res.headers.get("last-modified");
+      }
+
+      if (maxBytes !== undefined && total !== null && total > maxBytes) {
+        await res.body?.cancel?.().catch(() => {});
+        throw new BodyTooLargeError(maxBytes);
+      }
+
+      if (!res.body || typeof res.body.getReader !== "function") {
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (maxBytes !== undefined && buf.byteLength > maxBytes) throw new BodyTooLargeError(maxBytes);
+        chunks.push(buf);
+        loaded += buf.byteLength;
+        total = total ?? loaded;
+        report();
+      } else {
+        const reader = res.body.getReader();
+        const onAbort = () => reader.cancel(signal.reason).catch(() => {});
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let finished = false;
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            signal?.throwIfAborted?.();
+            if (done) break;
+            chunks.push(value);
+            loaded += value.byteLength;
+            if (maxBytes !== undefined && loaded > maxBytes) throw new BodyTooLargeError(maxBytes);
+            report();
+          }
+          finished = true;
+        } finally {
+          signal?.removeEventListener("abort", onAbort);
+          if (!finished) reader.cancel().catch(() => {});
+        }
+      }
+
+      if (total !== null && loaded < total) {
+        // Stream ended early without an error (some servers just close the socket).
+        throw Object.assign(new Error(`Incomplete download: got ${loaded} of ${total} bytes`), { code: "ECONNRESET" });
+      }
+
+      const out = new Uint8Array(loaded);
+      let offset = 0;
+      for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return out;
+    } catch (err) {
+      if (signal?.aborted) throw signal.reason ?? err;
+      if (!isRetryable(err)) throw err;
+
+      if (loaded > loadedBefore) attempt = 0; // it made progress — doesn't count against the budget
+      if (attempt >= retries) throw err;
+
+      let delayMs = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+      if (err instanceof HTTPError) {
+        const headerMs = getWaitMsFromHeaders(err.response && err.response.headers);
+        if (headerMs !== null) delayMs = Math.min(headerMs, 60000);
+      }
+      attempt++;
+      if (onRetry) onRetry(err, attempt, delayMs, { resumeFrom: loaded });
+      await abortableSleep(delayMs, signal);
+    }
+  }
+}
+
+module.exports = { downloadResumable };

package/src/index.js

@@ -8,6 +8,12 @@ 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");
 
 module.exports = {
   withRetry,
@@ -27,4 +33,13 @@ module.exports = {
   createLimiter,
   createFetch,
   HTTPError,
+  createRateLimiter,
+  createCircuitBreaker,
+  CircuitOpenError,
+  createMemoryCache,
+  createMockFetch,
+  downloadResumable,
+  readLines,
+  readNDJSON,
+  readSSE,
 };

package/src/index.mjs

@@ -18,6 +18,15 @@ export const {
   createLimiter,
   createFetch,
   HTTPError,
+  createRateLimiter,
+  createCircuitBreaker,
+  CircuitOpenError,
+  createMemoryCache,
+  createMockFetch,
+  downloadResumable,
+  readLines,
+  readNDJSON,
+  readSSE,
 } = reqkit;
 
 export default reqkit;

package/src/streams.js

@@ -0,0 +1,149 @@
+const encoder = new TextEncoder();
+
+// Yields Uint8Array chunks from a fetch Response, a web ReadableStream, or any
+// async iterable (e.g. a Node Readable). Cancels the underlying stream when
+// the consumer stops early or the signal aborts, so the connection is freed.
+async function* chunks(source, signal) {
+  let body = source;
+  if (body && typeof body.getReader !== "function" && "body" in body) body = body.body; // a Response
+  if (body === null || body === undefined) return;
+  signal?.throwIfAborted?.();
+
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    const onAbort = () => reader.cancel(signal.reason).catch(() => {});
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        signal?.throwIfAborted?.(); // cancel() makes read() resolve as done — don't mistake that for the end
+        if (done) return;
+        yield value;
+      }
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+      reader.cancel().catch(() => {});
+    }
+  } else if (typeof body[Symbol.asyncIterator] === "function") {
+    for await (const chunk of body) {
+      signal?.throwIfAborted?.();
+      yield typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+    }
+  } else {
+    throw new TypeError("reqkit streams: expected a Response, a ReadableStream or an async iterable");
+  }
+}
+
+/**
+ * Async-iterates the text lines of a streamed body. Handles \n, \r\n and \r,
+ * multi-byte characters split across chunks, and a leading BOM.
+ *
+ * ```js
+ * for await (const line of readLines(response)) console.log(line);
+ * ```
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {AsyncGenerator<string>}
+ */
+async function* readLines(source, opts = {}) {
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let first = true;
+
+  for await (const chunk of chunks(source, opts.signal)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    if (first && buffer.length > 0) {
+      buffer = buffer.replace(/^\uFEFF/, "");
+      first = false;
+    }
+
+    let pos = 0;
+    for (;;) {
+      const rest = buffer.slice(pos);
+      const i = rest.search(/\r\n|\n|\r/);
+      if (i === -1) break;
+      // A trailing "\r" might be the first half of "\r\n" — wait for more data.
+      if (rest[i] === "\r" && i === rest.length - 1) break;
+      yield rest.slice(0, i);
+      pos += i + (rest.startsWith("\r\n", i) ? 2 : 1);
+    }
+    buffer = buffer.slice(pos);
+  }
+
+  buffer += decoder.decode();
+  if (buffer.endsWith("\r")) buffer = buffer.slice(0, -1);
+  if (buffer.length > 0) yield buffer;
+}
+
+/**
+ * Async-iterates parsed JSON values from a newline-delimited JSON stream
+ * (NDJSON / JSON Lines). Blank lines are skipped. A malformed line throws a
+ * SyntaxError naming the line, unless `skipInvalid` is true.
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal, skipInvalid?: boolean }} [opts]
+ */
+async function* readNDJSON(source, opts = {}) {
+  let lineNo = 0;
+  for await (const line of readLines(source, opts)) {
+    lineNo++;
+    if (line.trim() === "") continue;
+    try {
+      yield JSON.parse(line);
+    } catch (err) {
+      if (opts.skipInvalid) continue;
+      throw new SyntaxError(`readNDJSON: invalid JSON on line ${lineNo}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Async-iterates Server-Sent Events (text/event-stream) as
+ * `{ event, data, id, retry }`, following the spec: multi-line `data:` is
+ * joined with "\n", comments (`:`) are ignored, `event` defaults to
+ * "message", `id` carries over between events, and an event cut off by the end
+ * of the stream is discarded. Great for LLM token streams.
+ *
+ * ```js
+ * for await (const { data } of readSSE(response)) {
+ *   if (data === "[DONE]") break;
+ *   console.log(JSON.parse(data));
+ * }
+ * ```
+ *
+ * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
+ * @param {{ signal?: AbortSignal }} [opts]
+ */
+async function* readSSE(source, opts = {}) {
+  let event = "";
+  let data = [];
+  let retry;
+  let lastId = "";
+
+  for await (const line of readLines(source, opts)) {
+    if (line === "") {
+      if (data.length > 0) yield { event: event || "message", data: data.join("\n"), id: lastId, retry };
+      event = "";
+      data = [];
+      retry = undefined;
+      continue;
+    }
+    if (line.startsWith(":")) continue;
+
+    const idx = line.indexOf(":");
+    const field = idx === -1 ? line : line.slice(0, idx);
+    let value = idx === -1 ? "" : line.slice(idx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+    else if (field === "id") {
+      if (!value.includes("\0")) lastId = value;
+    } else if (field === "retry") {
+      if (/^\d+$/.test(value)) retry = Number(value);
+    }
+  }
+}
+
+module.exports = { readLines, readNDJSON, readSSE };

package/types/index.d.ts

@@ -203,6 +203,15 @@ export interface CreateFetchDefaults {
   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. */
@@ -212,7 +221,7 @@ export interface CreateFetchDefaults {
   onResponse?: (ctx: FetchHookContext & { response: Response }) => void | Promise<void>;
 }
 
-export interface ReqkitRequestInit extends Omit<RequestInit, "headers"> {
+export interface ReqkitRequestInit extends Omit<RequestInit, "headers" | "cache"> {
   headers?: HeadersInit;
   query?: Record<string, unknown>;
   /** Serialized as the body with a JSON content-type. */
@@ -220,6 +229,8 @@ export interface ReqkitRequestInit extends Omit<RequestInit, "headers"> {
   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 {
@@ -231,3 +242,166 @@ export interface 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>;