fastfetch-api-fetch-enhancer 2.0.0

package/src/fastFetch.ts

@@ -0,0 +1,320 @@
+import fetch from "cross-fetch";
+import {
+  HttpError,
+  TimeoutError,
+  NetworkError,
+} from "./errors.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for controlling FastFetch behavior.
+ */
+export interface FastFetchOptions {
+  /** Number of retries on failure (default: 0). */
+  retries?: number;
+  /**
+   * Base delay in ms before next retry — applied with exponential backoff (default: 1000).
+   * Ignored when a `Retry-After` header is present on a 429 response.
+   */
+  retryDelay?: number;
+  /** Deduplicate identical in-flight requests (default: true). */
+  deduplicate?: boolean;
+  /**
+   * Custom retry predicate. Return `true` to retry.
+   * Receives the raw Response (for HTTP errors) or an Error (for network failures),
+   * plus the current attempt number (1-indexed).
+   * Overrides the built-in smart retry logic when provided.
+   */
+  shouldRetry?: (errorOrResponse: any, attempt: number) => boolean;
+  /**
+   * Abort the request after this many milliseconds.
+   * Throws a `TimeoutError` when the request is aborted by FastFetch's own timer.
+   */
+  timeout?: number;
+  /**
+   * Throw an `HttpError` instead of returning a non-ok Response (default: false).
+   * `FastFetchClient` sets this to `true` by default.
+   */
+  throwOnError?: boolean;
+  /**
+   * Cache successful GET responses in memory (default: false).
+   * Only applies to GET requests.
+   */
+  fastCache?: boolean;
+  /** How long (ms) to keep a cached response fresh (default: 30 000 ms = 30 s). */
+  cacheTTL?: number;
+  /**
+   * Called each time a retry is about to happen.
+   * @param attempt   The attempt number that just failed (1-indexed).
+   * @param error     The error/Response that caused the retry.
+   * @param delay     How long (ms) FastFetch will wait before the next attempt.
+   */
+  onRetry?: (attempt: number, error: any, delay: number) => void;
+  /** Enable verbose debug logging to console (default: false). */
+  debug?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/**
+ * In-flight request map for deduplication.
+ * Maps a stable request signature → the pending Promise<Response>.
+ */
+const inFlightMap = new Map<string, Promise<Response>>();
+
+/** TTL cache entry. */
+interface CacheEntry {
+  response: Response;
+  expiresAt: number;
+}
+
+/** In-memory TTL cache. */
+const responseCache = new Map<string, CacheEntry>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Stable key for dedup and cache, based on URL + method + headers + body. */
+function makeKey(input: RequestInfo, init?: RequestInit): string {
+  const normalized = {
+    url: typeof input === "string" ? input : (input as Request).url,
+    method: (init?.method ?? "GET").toUpperCase(),
+    headers: init?.headers ?? {},
+    body: init?.body ?? null,
+  };
+  return JSON.stringify(normalized);
+}
+
+/** Returns true for HTTP status codes that we retry by default. */
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+/**
+ * Parse the `Retry-After` response header and return the delay in ms.
+ * Supports both numeric (seconds) and HTTP-date formats.
+ * Returns `null` if the header is missing or unparseable.
+ */
+function parseRetryAfter(response: Response): number | null {
+  const header = response.headers?.get("Retry-After");
+  if (!header) return null;
+
+  // Numeric: number of seconds
+  const seconds = Number(header);
+  if (!isNaN(seconds)) return Math.max(0, seconds * 1000);
+
+  // HTTP-date: "Wed, 21 Oct 2025 07:28:00 GMT"
+  const date = new Date(header);
+  if (!isNaN(date.getTime())) {
+    return Math.max(0, date.getTime() - Date.now());
+  }
+
+  return null;
+}
+
+/** Run fetch with an AbortController-based timeout. */
+async function fetchWithTimeout(
+  input: RequestInfo,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Core fastFetch function
+// ---------------------------------------------------------------------------
+
+/**
+ * FastFetch — A smarter `fetch()` wrapper.
+ *
+ * Features:
+ * - **Retry** with exponential backoff (`retries`, `retryDelay`, `shouldRetry`, `onRetry`)
+ * - **Smart default retry** — automatically retries 5xx and 429 responses
+ * - **Retry-After** — respects the `Retry-After` header on 429 responses
+ * - **Timeout** — aborts the request after `timeout` ms
+ * - **Deduplication** — merges identical in-flight requests
+ * - **TTL Cache** — caches successful GET responses for `cacheTTL` ms
+ * - **Debug logging** — optional verbose logging via `debug: true`
+ */
+export async function fastFetch(
+  input: RequestInfo,
+  init?: RequestInit & FastFetchOptions,
+): Promise<Response> {
+  const {
+    retries = 0,
+    retryDelay = 1000,
+    deduplicate = true,
+    shouldRetry,
+    timeout,
+    fastCache = false,
+    cacheTTL = 30_000,
+    onRetry,
+    throwOnError = false,
+    debug = false,
+  } = init || {};
+
+  const method = (init?.method ?? "GET").toUpperCase();
+  const isGet = method === "GET";
+
+  const log = (...args: any[]) => {
+    if (debug) console.log("[FastFetch]", ...args);
+  };
+
+  log("Starting request:", method, input);
+
+  // ── TTL Cache check (GET only) ─────────────────────────────────────────
+  const cacheKey = makeKey(input, init);
+  if (fastCache && isGet) {
+    const entry = responseCache.get(cacheKey);
+    if (entry && Date.now() < entry.expiresAt) {
+      log("Cache hit:", cacheKey);
+      return entry.response.clone();
+    }
+    // Stale or missing — remove if it was there
+    responseCache.delete(cacheKey);
+  }
+
+  // ── Deduplication check ────────────────────────────────────────────────
+  const dedupKey = cacheKey; // same key works for both
+  if (deduplicate) {
+    if (inFlightMap.has(dedupKey)) {
+      log("Reusing in-flight request:", dedupKey);
+      const shared = await inFlightMap.get(dedupKey)!;
+      return shared.clone();
+    }
+  }
+
+  // ── Build the retry loop ───────────────────────────────────────────────
+  let attempt = 0;
+
+  const promise = (async function fetchWithRetry(): Promise<Response> {
+    while (true) {
+      attempt++;
+      log(`Attempt #${attempt}`);
+
+      let response: Response;
+      try {
+        response = timeout
+          ? await fetchWithTimeout(input, init ?? {}, timeout)
+          : await fetch(input, init);
+      } catch (rawError: any) {
+        // Wrap raw DOMException / TypeError into typed FastFetch errors
+        let typedError: Error;
+        if (rawError?.name === "AbortError" && timeout) {
+          typedError = new TimeoutError(timeout);
+        } else if (
+          rawError instanceof TypeError ||
+          rawError?.name === "TypeError"
+        ) {
+          typedError = new NetworkError(rawError.message, rawError);
+        } else {
+          typedError = rawError; // pass CircuitOpenError & others through
+        }
+
+        log(`Network/abort error on attempt #${attempt}:`, typedError.message);
+
+        // TimeoutError — don't retry by default (retrying a timed-out request
+        // will just time out again and waste the user's time).
+        const isTimeout = typedError instanceof TimeoutError;
+
+        const shouldDoRetry = shouldRetry
+          ? shouldRetry(typedError, attempt)
+          : !isTimeout && attempt <= retries;
+
+        if (shouldDoRetry && attempt <= retries) {
+          const delay = retryDelay * Math.pow(2, attempt - 1);
+          log(`Retrying in ${delay}ms…`);
+          onRetry?.(attempt, typedError, delay);
+          await sleep(delay);
+          continue;
+        }
+
+        throw typedError;
+      }
+
+      // HTTP-level failure
+      if (!response.ok) {
+        const shouldDoRetry = shouldRetry
+          ? shouldRetry(response, attempt)
+          : isRetryableStatus(response.status) && attempt <= retries;
+
+        if (shouldDoRetry && attempt <= retries) {
+          // Respect Retry-After header (e.g. on 429)
+          const retryAfterMs = parseRetryAfter(response);
+          const delay = retryAfterMs ?? retryDelay * Math.pow(2, attempt - 1);
+          log(
+            `HTTP ${response.status} — retrying in ${delay}ms (attempt ${attempt}/${retries})`,
+          );
+          onRetry?.(attempt, response, delay);
+          await sleep(delay);
+          continue;
+        }
+      }
+
+      log(`Succeeded on attempt #${attempt} (status: ${response.status})`);
+
+      // Throw HttpError if caller opted in and response is not ok
+      if (!response.ok && throwOnError) {
+        throw new HttpError(response);
+      }
+
+      return response;
+    }
+  })();
+
+  // ── Register in-flight for dedup ───────────────────────────────────────
+  if (deduplicate) {
+    inFlightMap.set(dedupKey, promise);
+  }
+
+  let result: Response;
+  try {
+    result = await promise;
+  } finally {
+    if (deduplicate) {
+      inFlightMap.delete(dedupKey);
+    }
+  }
+
+  // ── Populate TTL cache ─────────────────────────────────────────────────
+  if (fastCache && isGet && result!.ok) {
+    responseCache.set(cacheKey, {
+      response: result!.clone(),
+      expiresAt: Date.now() + cacheTTL,
+    });
+    log(`Cached response for ${cacheTTL}ms`);
+  }
+
+  return result!.clone();
+}
+
+/**
+ * Manually clear all TTL-cached responses, or a single entry by URL.
+ */
+export function clearCache(url?: string): void {
+  if (url) {
+    // Remove any entry whose key contains the URL
+    for (const key of responseCache.keys()) {
+      if (key.includes(url)) responseCache.delete(key);
+    }
+  } else {
+    responseCache.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Core fetch function + options
+export { fastFetch, clearCache } from "./fastFetch.js";
+export type { FastFetchOptions } from "./fastFetch.js";
+
+// Client factory + types
+export { createClient, FastFetchClient } from "./client.js";
+export type {
+  ClientOptions,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+} from "./client.js";
+
+// Typed error hierarchy
+export {
+  FastFetchError,
+  HttpError,
+  TimeoutError,
+  NetworkError,
+  CircuitOpenError,
+} from "./errors.js";
+
+// Metrics
+export { MetricsCollector } from "./metrics.js";
+export type {
+  MetricsSnapshot,
+  EndpointMetrics,
+  LatencyPercentiles,
+} from "./metrics.js";
+
+// Circuit breaker
+export { CircuitBreaker } from "./circuit-breaker.js";
+export type {
+  CircuitBreakerOptions,
+  CircuitState,
+} from "./circuit-breaker.js";
+
+// Concurrency queue
+export { RequestQueue } from "./queue.js";
+export type { QueuePriority } from "./queue.js";
+
+// Middleware
+export { compose } from "./middleware.js";
+export type { FastFetchContext, MiddlewareFn } from "./middleware.js";
+
+// SSE Streaming
+export { consumeSSE } from "./streaming.js";
+export type { SSEEvent, SSEHandler } from "./streaming.js";
+
+// Offline queue
+export { OfflineQueue } from "./offline-queue.js";
+export type { OfflineRequest, ReplayResult } from "./offline-queue.js";

package/src/metrics.ts

@@ -0,0 +1,200 @@
+/**
+ * FastFetch lightweight metrics collector.
+ *
+ * Tracks request latencies, success/error rates, and per-endpoint breakdowns
+ * using a rolling window of the last N samples.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface LatencyPercentiles {
+  /** Median (50th percentile) latency in ms. */
+  p50: number;
+  /** 95th percentile latency in ms. */
+  p95: number;
+  /** 99th percentile latency in ms. */
+  p99: number;
+  min: number;
+  max: number;
+  /** Mean (average) latency in ms. */
+  mean: number;
+}
+
+export interface EndpointMetrics {
+  /** Total requests recorded for this endpoint. */
+  count: number;
+  /** Number of failed requests (non-2xx or thrown error). */
+  errors: number;
+  /** Success rate in [0, 1]. */
+  successRate: number;
+  latency: LatencyPercentiles;
+}
+
+export interface MetricsSnapshot {
+  /** Total requests in the current rolling window. */
+  totalRequests: number;
+  /** Overall success rate in [0, 1]. */
+  successRate: number;
+  /** Overall error rate in [0, 1]. */
+  errorRate: number;
+  /** Aggregated latency across all endpoints. */
+  latency: LatencyPercentiles;
+  /** Per-endpoint breakdown (URL paths normalised — numeric IDs replaced with :id). */
+  byEndpoint: Record<string, EndpointMetrics>;
+}
+
+interface Sample {
+  url: string;
+  duration: number;
+  success: boolean;
+  status?: number;
+}
+
+// ---------------------------------------------------------------------------
+// MetricsCollector
+// ---------------------------------------------------------------------------
+
+export class MetricsCollector {
+  private samples: Sample[] = [];
+  private readonly windowSize: number;
+
+  /**
+   * @param windowSize Maximum number of samples to retain (default: 1 000).
+   *                   Older samples are evicted when the window is full.
+   */
+  constructor(windowSize = 1_000) {
+    this.windowSize = windowSize;
+  }
+
+  /** Record a completed request. Called automatically by FastFetchClient. */
+  record(
+    url: string,
+    duration: number,
+    success: boolean,
+    status?: number,
+  ): void {
+    this.samples.push({ url, duration, success, status });
+    if (this.samples.length > this.windowSize) {
+      this.samples.shift(); // evict oldest
+    }
+  }
+
+  // ── Percentile computation ───────────────────────────────────────────────
+
+  private percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return 0;
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+  }
+
+  private computeLatency(durations: number[]): LatencyPercentiles {
+    if (durations.length === 0) {
+      return { p50: 0, p95: 0, p99: 0, min: 0, max: 0, mean: 0 };
+    }
+    const sorted = [...durations].sort((a, b) => a - b);
+    const sum = sorted.reduce((s, v) => s + v, 0);
+    return {
+      p50: this.percentile(sorted, 50),
+      p95: this.percentile(sorted, 95),
+      p99: this.percentile(sorted, 99),
+      min: sorted[0],
+      max: sorted[sorted.length - 1],
+      mean: Math.round(sum / sorted.length),
+    };
+  }
+
+  /**
+   * Normalise a URL for grouping — strips query params and replaces numeric
+   * path segments with `:id` so `/users/1` and `/users/2` are the same bucket.
+   */
+  private normalizeUrl(url: string): string {
+    try {
+      const u = new URL(url);
+      // Replace numeric-only path segments with :id
+      const path = u.pathname.replace(/\/\d+(?=\/|$)/g, "/:id");
+      return u.hostname + path;
+    } catch {
+      return url.replace(/\/\d+(?=\/|$)/g, "/:id");
+    }
+  }
+
+  // ── Public API ───────────────────────────────────────────────────────────
+
+  /**
+   * Return a serialisable metrics snapshot of the current rolling window.
+   *
+   * @example
+   * ```ts
+   * console.table(api.metrics.snapshot().byEndpoint);
+   * ```
+   */
+  snapshot(): MetricsSnapshot {
+    const total = this.samples.length;
+    const emptyLatency: LatencyPercentiles = {
+      p50: 0,
+      p95: 0,
+      p99: 0,
+      min: 0,
+      max: 0,
+      mean: 0,
+    };
+
+    if (total === 0) {
+      return {
+        totalRequests: 0,
+        successRate: 1,
+        errorRate: 0,
+        latency: emptyLatency,
+        byEndpoint: {},
+      };
+    }
+
+    const errors = this.samples.filter((s) => !s.success).length;
+    const allDurations = this.samples.map((s) => s.duration);
+
+    // Group samples by normalised URL path
+    const groups = new Map<string, Sample[]>();
+    for (const sample of this.samples) {
+      const key = this.normalizeUrl(sample.url);
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(sample);
+      } else {
+        groups.set(key, [sample]);
+      }
+    }
+
+    const byEndpoint: Record<string, EndpointMetrics> = {};
+    for (const [key, bucket] of groups) {
+      const bucketErrors = bucket.filter((s) => !s.success).length;
+      byEndpoint[key] = {
+        count: bucket.length,
+        errors: bucketErrors,
+        successRate: parseFloat(
+          ((bucket.length - bucketErrors) / bucket.length).toFixed(4),
+        ),
+        latency: this.computeLatency(bucket.map((s) => s.duration)),
+      };
+    }
+
+    return {
+      totalRequests: total,
+      successRate: parseFloat(((total - errors) / total).toFixed(4)),
+      errorRate: parseFloat((errors / total).toFixed(4)),
+      latency: this.computeLatency(allDurations),
+      byEndpoint,
+    };
+  }
+
+  /** Reset all collected samples. */
+  reset(): void {
+    this.samples = [];
+  }
+
+  /** Current number of samples in the rolling window. */
+  get size(): number {
+    return this.samples.length;
+  }
+}

package/src/middleware.ts

@@ -0,0 +1,106 @@
+/**
+ * FastFetch Koa-style middleware (plugin) system.
+ *
+ * Middleware functions receive a `FastFetchContext` object and a `next()`
+ * callback. They can:
+ *  - Mutate `ctx.init` (headers, body, options) before the request is sent.
+ *  - Await `next()` and then inspect / transform `ctx.response` after.
+ *  - Attach data to `ctx.meta` for consumption by later middleware.
+ *
+ * Execution order follows the classic onion model:
+ *   mw[0] wraps mw[1] wraps mw[2] wraps … wraps the actual fetch.
+ */
+
+import type { FastFetchOptions } from "./fastFetch.js";
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutable request/response context passed through the middleware pipeline.
+ */
+export interface FastFetchContext {
+  /** Fully-resolved URL (baseURL + path). */
+  url: string;
+  /** Uppercase HTTP method (GET, POST, …). */
+  method: string;
+  /**
+   * Mutable request init — mutate `ctx.init.headers`, `ctx.init.body`, etc.
+   * inside request middleware.
+   */
+  init: RequestInit & FastFetchOptions;
+  /**
+   * Set to the raw `Response` after the request completes.
+   * Available inside response middleware (i.e., code after `await next()`).
+   */
+  response?: Response;
+  /**
+   * Request duration in milliseconds.
+   * Available after `await next()` completes.
+   */
+  duration?: number;
+  /**
+   * Free-form metadata bag. Attach anything here and read it in later
+   * middleware or after the final `await next()`.
+   *
+   * @example
+   * ```ts
+   * ctx.meta.requestId = crypto.randomUUID();
+   * await next();
+   * console.log(`${ctx.meta.requestId} — ${ctx.duration}ms`);
+   * ```
+   */
+  meta: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Middleware type
+// ---------------------------------------------------------------------------
+
+export type MiddlewareFn = (
+  ctx: FastFetchContext,
+  next: () => Promise<void>,
+) => Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Compose
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose an array of middleware functions into a single callable.
+ *
+ * Works identically to Koa's `koa-compose`:
+ * - Middleware runs in insertion order during the "down" pass.
+ * - Code after `await next()` runs in reverse order during the "up" pass.
+ * - Calling `next()` more than once throws an Error.
+ *
+ * @example
+ * ```ts
+ * const run = compose([loggerMiddleware, authMiddleware]);
+ * await run(ctx);
+ * ```
+ */
+export function compose(
+  middlewares: MiddlewareFn[],
+): (ctx: FastFetchContext) => Promise<void> {
+  return async function (ctx: FastFetchContext): Promise<void> {
+    let lastIndex = -1;
+
+    async function dispatch(i: number): Promise<void> {
+      if (i <= lastIndex) {
+        throw new Error(
+          "FastFetch middleware: next() was called more than once in the same middleware.",
+        );
+      }
+      lastIndex = i;
+
+      if (i >= middlewares.length) return; // reached the end of the chain
+
+      const fn = middlewares[i];
+      await fn(ctx, () => dispatch(i + 1));
+    }
+
+    await dispatch(0);
+  };
+}