@boy-offi9-inc/reqkit 0.7.0 → 0.8.0

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

@@ -34,46 +34,83 @@ async function* chunks(source, signal) {
   }
 }
 
+const DEFAULT_MAX_LINE_LENGTH = 16 * 1024 * 1024;
+
+function lineTooLong(limit) {
+  return Object.assign(
+    new Error(`reqkit streams: a line exceeded ${limit} characters without a line break (raise \`maxLineLength\` if that's expected)`),
+    { code: "LINE_TOO_LONG" }
+  );
+}
+
 /**
  * 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.
  *
+ * Runs in linear time and bounded memory: only newly arrived text is scanned,
+ * and a "line" longer than `maxLineLength` characters (default 16 Mi — a
+ * server that never sends a newline) throws `code: "LINE_TOO_LONG"` instead
+ * of buffering forever.
+ *
  * ```js
  * for await (const line of readLines(response)) console.log(line);
  * ```
  *
  * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
- * @param {{ signal?: AbortSignal }} [opts]
+ * @param {{ signal?: AbortSignal, maxLineLength?: number }} [opts]
  * @returns {AsyncGenerator<string>}
  */
 async function* readLines(source, opts = {}) {
+  const { maxLineLength = DEFAULT_MAX_LINE_LENGTH } = opts;
   const decoder = new TextDecoder("utf-8");
-  let buffer = "";
+  const terminator = /[\r\n]/g;
+
+  let parts = []; // pieces of the line being assembled (no terminators in them)
+  let partsLength = 0;
+  let skipLF = false; // the previous line ended with "\r", so a leading "\n" belongs to it
   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/, "");
+    let text = decoder.decode(chunk, { stream: true });
+    if (first && text.length > 0) {
+      text = text.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);
+    let start = 0;
+    terminator.lastIndex = 0;
+    let match;
+    while ((match = terminator.exec(text)) !== null) {
+      const ch = match[0];
+      if (ch === "\n" && skipLF && match.index === start) {
+        skipLF = false; // the "\n" of a "\r\n" pair — swallow it
+        start = match.index + 1;
+        continue;
+      }
+      skipLF = false;
+
+      const piece = text.slice(start, match.index);
+      if (partsLength + piece.length > maxLineLength) throw lineTooLong(maxLineLength);
+      const line = parts.length > 0 ? parts.join("") + piece : piece;
+      parts = [];
+      partsLength = 0;
+      yield line;
+
+      start = match.index + 1;
+      skipLF = ch === "\r";
+    }
+
+    if (start < text.length) {
+      const rest = text.slice(start);
+      partsLength += rest.length;
+      if (partsLength > maxLineLength) throw lineTooLong(maxLineLength);
+      parts.push(rest);
+      skipLF = false;
     }
-    buffer = buffer.slice(pos);
   }
 
-  buffer += decoder.decode();
-  if (buffer.endsWith("\r")) buffer = buffer.slice(0, -1);
-  if (buffer.length > 0) yield buffer;
+  const tail = parts.join("") + decoder.decode();
+  if (tail.length > 0) yield tail;
 }
 
 /**
@@ -113,11 +150,13 @@ async function* readNDJSON(source, opts = {}) {
  * ```
  *
  * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
- * @param {{ signal?: AbortSignal }} [opts]
+ * @param {{ signal?: AbortSignal, maxLineLength?: number }} [opts] - `maxLineLength` also caps the data of a single event
  */
 async function* readSSE(source, opts = {}) {
+  const maxEventLength = opts.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
   let event = "";
   let data = [];
+  let dataLength = 0;
   let retry;
   let lastId = "";
 
@@ -126,6 +165,7 @@ async function* readSSE(source, opts = {}) {
       if (data.length > 0) yield { event: event || "message", data: data.join("\n"), id: lastId, retry };
       event = "";
       data = [];
+      dataLength = 0;
       retry = undefined;
       continue;
     }
@@ -137,7 +177,11 @@ async function* readSSE(source, opts = {}) {
     if (value.startsWith(" ")) value = value.slice(1);
 
     if (field === "event") event = value;
-    else if (field === "data") data.push(value);
+    else if (field === "data") {
+      dataLength += value.length + 1;
+      if (dataLength > maxEventLength) throw lineTooLong(maxEventLength);
+      data.push(value);
+    }
     else if (field === "id") {
       if (!value.includes("\0")) lastId = value;
     } else if (field === "retry") {

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,180 @@
+// 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[];
+  /** 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`/"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 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";
+    }
+  | { type: "error"; url?: string; method?: string; error: unknown; durationMs: number; attempts: 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 };