fastfetch-api-fetch-enhancer 2.0.0

package/src/client.ts

@@ -0,0 +1,591 @@
+/**
+ * FastFetch client factory — `createClient()`.
+ *
+ * Creates a pre-configured `FastFetchClient` instance with:
+ *  - Base URL + default headers
+ *  - Request / Response / Error interceptors (v1.x, preserved)
+ *  - Koa-style middleware pipeline  (`api.use()`)
+ *  - Circuit breaker
+ *  - Concurrency-limited request queue
+ *  - Built-in metrics
+ *  - SSE streaming  (`api.stream()`)
+ *  - Offline request queue
+ *  - Typed HTTP method helpers (get / post / put / patch / delete / json)
+ *  - Auto-serialisation of request body (plain objects → JSON)
+ */
+
+import { fastFetch, FastFetchOptions } from "./fastFetch.js";
+import { HttpError, NetworkError } from "./errors.js";
+import { MetricsCollector } from "./metrics.js";
+import {
+  CircuitBreaker,
+  CircuitBreakerOptions,
+} from "./circuit-breaker.js";
+import { RequestQueue, QueuePriority } from "./queue.js";
+import {
+  compose,
+  FastFetchContext,
+  MiddlewareFn,
+} from "./middleware.js";
+import { consumeSSE, SSEHandler } from "./streaming.js";
+import { OfflineQueue } from "./offline-queue.js";
+
+// ---------------------------------------------------------------------------
+// Interceptor types (v1.x API — kept for backward compatibility)
+// ---------------------------------------------------------------------------
+
+export type RequestInterceptor = (
+  url: string,
+  init: RequestInit & FastFetchOptions,
+) => (RequestInit & FastFetchOptions) | Promise<RequestInit & FastFetchOptions>;
+
+export type ResponseInterceptor = (
+  response: Response,
+) => Response | Promise<Response>;
+
+export type ErrorInterceptor = (error: unknown) => unknown | Promise<unknown>;
+
+// ---------------------------------------------------------------------------
+// ClientOptions
+// ---------------------------------------------------------------------------
+
+export interface ClientOptions extends FastFetchOptions {
+  /**
+   * Base URL prepended to all relative paths.
+   * @example `'https://api.example.com/v1'`
+   */
+  baseURL?: string;
+
+  /**
+   * Default headers merged into every request.
+   * Per-request headers take precedence.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Throw an `HttpError` for non-2xx responses (default: `true`).
+   * Set to `false` to receive the raw Response regardless of status.
+   */
+  throwOnError?: boolean;
+
+  /**
+   * Circuit breaker configuration.
+   * When provided, the circuit breaker wraps every request.
+   */
+  circuitBreaker?: CircuitBreakerOptions;
+
+  /**
+   * Maximum number of concurrent in-flight requests for this client.
+   * Additional requests are queued until a slot becomes free.
+   */
+  maxConcurrent?: number;
+
+  /**
+   * Rolling window size for the built-in metrics collector (default: 1 000).
+   */
+  metricsWindowSize?: number;
+
+  /**
+   * When `true`, mutating requests (POST/PUT/PATCH/DELETE) made while
+   * `navigator.onLine === false` are queued and replayed on reconnect.
+   * No-op in non-browser environments.
+   */
+  offlineQueue?: boolean;
+
+  /** v1.x interceptors — still supported. Prefer `use()` for new code. */
+  interceptors?: {
+    request?: RequestInterceptor[];
+    response?: ResponseInterceptor[];
+    error?: ErrorInterceptor[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// FastFetchClient
+// ---------------------------------------------------------------------------
+
+export class FastFetchClient {
+  // Configuration
+  private readonly baseURL: string;
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly defaultOptions: FastFetchOptions & { throwOnError?: boolean };
+  private readonly clientThrowOnError: boolean;
+
+  // v1.x interceptors
+  private readonly requestInterceptors: RequestInterceptor[];
+  private readonly responseInterceptors: ResponseInterceptor[];
+  private readonly errorInterceptors: ErrorInterceptor[];
+
+  // v2.x systems
+  private readonly middlewares: MiddlewareFn[] = [];
+  private readonly _circuitBreaker?: CircuitBreaker;
+  private readonly _queue?: RequestQueue;
+  private readonly _offlineQueue?: OfflineQueue;
+  private readonly _metrics: MetricsCollector;
+
+  constructor(options: ClientOptions = {}) {
+    const {
+      baseURL = "",
+      headers = {},
+      interceptors = {},
+      throwOnError = true,
+      circuitBreaker: cbOptions,
+      maxConcurrent,
+      metricsWindowSize,
+      offlineQueue: useOfflineQueue,
+      // FastFetchOptions passed to every request
+      retries,
+      retryDelay,
+      deduplicate,
+      shouldRetry,
+      timeout,
+      fastCache,
+      cacheTTL,
+      onRetry,
+      debug,
+    } = options;
+
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.defaultHeaders = headers;
+    this.clientThrowOnError = throwOnError;
+    this.defaultOptions = {
+      retries,
+      retryDelay,
+      deduplicate,
+      shouldRetry,
+      timeout,
+      fastCache,
+      cacheTTL,
+      onRetry,
+      debug,
+    };
+
+    // v1.x interceptors
+    this.requestInterceptors = interceptors.request ?? [];
+    this.responseInterceptors = interceptors.response ?? [];
+    this.errorInterceptors = interceptors.error ?? [];
+
+    // v2.x systems
+    this._metrics = new MetricsCollector(metricsWindowSize);
+
+    if (cbOptions) {
+      this._circuitBreaker = new CircuitBreaker(cbOptions);
+    }
+    if (maxConcurrent !== undefined) {
+      this._queue = new RequestQueue(maxConcurrent);
+    }
+    if (useOfflineQueue) {
+      this._offlineQueue = new OfflineQueue();
+      this._offlineQueue.start();
+    }
+  }
+
+  // ── Middleware registration ──────────────────────────────────────────────
+
+  /**
+   * Register a middleware function.
+   *
+   * Middleware runs in registration order (Koa onion model):
+   * - Code *before* `await next()` executes on the way *down* (pre-request).
+   * - Code *after* `await next()` executes on the way *up* (post-response).
+   *
+   * @example
+   * ```ts
+   * api.use(async (ctx, next) => {
+   *   ctx.init.headers['X-Request-Id'] = crypto.randomUUID();
+   *   const start = Date.now();
+   *   await next();
+   *   console.log(`${ctx.method} ${ctx.url} — ${Date.now() - start}ms ${ctx.response?.status}`);
+   * });
+   * ```
+   */
+  use(middleware: MiddlewareFn): this {
+    this.middlewares.push(middleware);
+    return this; // chainable
+  }
+
+  // ── Metrics ──────────────────────────────────────────────────────────────
+
+  /**
+   * Built-in metrics collector.
+   * Call `.metrics.snapshot()` to get request counts, error rates, and latency percentiles.
+   *
+   * @example
+   * ```ts
+   * console.table(api.metrics.snapshot().byEndpoint);
+   * ```
+   */
+  get metrics(): MetricsCollector {
+    return this._metrics;
+  }
+
+  // ── Circuit breaker ───────────────────────────────────────────────────────
+
+  /**
+   * Direct access to the circuit breaker (if configured).
+   * Useful for inspecting state or manually resetting in tests.
+   */
+  get circuitBreaker(): CircuitBreaker | undefined {
+    return this._circuitBreaker;
+  }
+
+  // ── Concurrency queue ────────────────────────────────────────────────────
+
+  /**
+   * Direct access to the concurrency queue (if configured).
+   * Useful for observing `pending` / `active` counts.
+   */
+  get queue(): RequestQueue | undefined {
+    return this._queue;
+  }
+
+  // ── Internal helpers ─────────────────────────────────────────────────────
+
+  private resolveURL(path: string): string {
+    if (
+      !this.baseURL ||
+      path.startsWith("http://") ||
+      path.startsWith("https://")
+    ) {
+      return path;
+    }
+    const sep = path.startsWith("/") ? "" : "/";
+    return `${this.baseURL}${sep}${path}`;
+  }
+
+  private mergeInit(
+    init?: RequestInit & FastFetchOptions,
+  ): RequestInit & FastFetchOptions {
+    return {
+      ...(this.defaultOptions as object),
+      ...(init as object),
+      headers: {
+        ...this.defaultHeaders,
+        ...(init?.headers as Record<string, string> | undefined),
+      },
+    } as RequestInit & FastFetchOptions;
+  }
+
+  /**
+   * Auto-serialise the request body.
+   * - Plain objects / arrays → JSON string + `Content-Type: application/json`
+   * - FormData / URLSearchParams / Blob / ArrayBuffer / string → passed through
+   */
+  private autoSerializeBody(
+    body: unknown,
+    headers: Record<string, string>,
+  ): { body: BodyInit | undefined; headers: Record<string, string> } {
+    if (body === undefined || body === null) {
+      return { body: undefined, headers };
+    }
+    if (
+      body instanceof FormData ||
+      body instanceof URLSearchParams ||
+      body instanceof Blob ||
+      body instanceof ArrayBuffer ||
+      typeof body === "string"
+    ) {
+      return { body: body as BodyInit, headers };
+    }
+    // Plain object or array — serialize to JSON
+    return {
+      body: JSON.stringify(body),
+      headers: { "Content-Type": "application/json", ...headers },
+    };
+  }
+
+  // ── Core fetch method ────────────────────────────────────────────────────
+
+  /**
+   * Make an HTTP request. Runs the full pipeline:
+   * request interceptors → middleware → circuit breaker → queue → fastFetch → response interceptors.
+   *
+   * Throws `HttpError` on non-2xx by default (disable with `throwOnError: false`).
+   */
+  async fetch(
+    path: string,
+    init?: RequestInit & FastFetchOptions & { throwOnError?: boolean },
+  ): Promise<Response> {
+    const url = this.resolveURL(path);
+    const mergedInit = this.mergeInit(init);
+    const method = ((mergedInit as any).method ?? "GET").toUpperCase();
+
+    // ── Offline queue check ──────────────────────────────────────────────
+    if (this._offlineQueue?.shouldQueue(method)) {
+      this._offlineQueue.enqueue(url, mergedInit as RequestInit);
+      return new Response(JSON.stringify({ queued: true, offline: true }), {
+        status: 202,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    // ── Build context ────────────────────────────────────────────────────
+    const ctx: FastFetchContext = {
+      url,
+      method,
+      init: mergedInit,
+      meta: {},
+    };
+
+    const start = Date.now();
+    let success = false;
+    let httpStatus: number | undefined;
+
+    try {
+      // ── v1.x request interceptors ──────────────────────────────────────
+      for (const interceptor of this.requestInterceptors) {
+        ctx.init = await interceptor(ctx.url, ctx.init);
+      }
+
+      // ── Determine effective throwOnError ───────────────────────────────
+      const shouldThrow =
+        (init as any)?.throwOnError !== undefined
+          ? (init as any).throwOnError
+          : this.clientThrowOnError;
+
+      // ── Innermost middleware: actual HTTP request ───────────────────────
+      const coreMiddleware: MiddlewareFn = async (ctx, next) => {
+        const doFetch = async (): Promise<Response> => {
+          // fastFetch handles retries + dedup + cache internally
+          const response = await fastFetch(ctx.url, ctx.init);
+          if (!response.ok && shouldThrow) {
+            throw new HttpError(response);
+          }
+          return response;
+        };
+
+        let response: Response;
+
+        if (this._circuitBreaker && this._queue) {
+          response = await this._queue.enqueue(
+            () => this._circuitBreaker!.execute(doFetch),
+            "normal",
+          );
+        } else if (this._circuitBreaker) {
+          response = await this._circuitBreaker.execute(doFetch);
+        } else if (this._queue) {
+          response = await this._queue.enqueue(doFetch, "normal");
+        } else {
+          response = await doFetch();
+        }
+
+        ctx.response = response;
+        httpStatus = response.status;
+        success = response.ok;
+        ctx.duration = Date.now() - start;
+
+        await next(); // nothing beyond this in the chain
+      };
+
+      // ── Compose and run pipeline ───────────────────────────────────────
+      const pipeline = compose([...this.middlewares, coreMiddleware]);
+      await pipeline(ctx);
+
+      // ── v1.x response interceptors ─────────────────────────────────────
+      let finalResponse = ctx.response!;
+      for (const interceptor of this.responseInterceptors) {
+        finalResponse = await interceptor(finalResponse);
+      }
+
+      return finalResponse;
+    } catch (err) {
+      ctx.duration = ctx.duration ?? Date.now() - start;
+      success = false;
+
+      // ── v1.x error interceptors ────────────────────────────────────────
+      let handledErr: unknown = err;
+      for (const interceptor of this.errorInterceptors) {
+        handledErr = await interceptor(handledErr);
+      }
+      throw handledErr;
+    } finally {
+      this._metrics.record(
+        url,
+        ctx.duration ?? Date.now() - start,
+        success,
+        httpStatus,
+      );
+    }
+  }
+
+  // ── Typed JSON helper ────────────────────────────────────────────────────
+
+  /**
+   * Fetch and automatically parse the response body as JSON.
+   * Returns a typed `Promise<T>`.
+   *
+   * @example
+   * ```ts
+   * const user = await api.json<User>('/users/1');
+   * const posts = await api.json<Post[]>('/posts?limit=10');
+   * ```
+   */
+  async json<T = unknown>(
+    path: string,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<T> {
+    const res = await this.fetch(path, {
+      ...init,
+      headers: {
+        Accept: "application/json",
+        ...(init?.headers as Record<string, string> | undefined),
+      },
+    });
+    return res.json() as Promise<T>;
+  }
+
+  // ── SSE streaming ─────────────────────────────────────────────────────────
+
+  /**
+   * Open a Server-Sent Events stream and call `handler` for each event.
+   *
+   * The method resolves when the stream ends or the provided `AbortSignal` fires.
+   * Automatically sets `Accept: text/event-stream` and `Cache-Control: no-cache`.
+   *
+   * @example
+   * ```ts
+   * const ctrl = new AbortController();
+   * await api.stream('/api/ai/generate', (event) => {
+   *   process.stdout.write(event.data);
+   * }, { signal: ctrl.signal });
+   * ```
+   */
+  async stream(
+    path: string,
+    handler: SSEHandler,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<void> {
+    const res = await this.fetch(path, {
+      ...init,
+      // SSE streams should always throw on error
+      ...({"throwOnError": true} as any),
+      headers: {
+        Accept: "text/event-stream",
+        "Cache-Control": "no-cache",
+        ...(init?.headers as Record<string, string> | undefined),
+      },
+    });
+
+    if (!res.body) {
+      throw new NetworkError(
+        "Response body is null — cannot open SSE stream. " +
+          "Ensure the server returns a `Content-Type: text/event-stream` response.",
+      );
+    }
+
+    const reader =
+      res.body.getReader() as ReadableStreamDefaultReader<Uint8Array>;
+    await consumeSSE(reader, handler, (init as any)?.signal);
+  }
+
+  // ── HTTP method shorthands ───────────────────────────────────────────────
+
+  /** GET request — returns raw `Response`. Use `.json<T>()` for parsed data. */
+  get(path: string, init?: RequestInit & FastFetchOptions): Promise<Response> {
+    return this.fetch(path, { ...init, method: "GET" });
+  }
+
+  /**
+   * POST request. Body is automatically serialised:
+   * - Plain objects / arrays → JSON (+ `Content-Type: application/json`)
+   * - FormData / URLSearchParams / string → passed through as-is
+   */
+  post<B = unknown>(
+    path: string,
+    body?: B,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response> {
+    const headers = init?.headers as Record<string, string> | undefined;
+    const serialized = this.autoSerializeBody(body, headers ?? {});
+    return this.fetch(path, {
+      ...init,
+      method: "POST",
+      body: serialized.body,
+      headers: serialized.headers,
+    });
+  }
+
+  /**
+   * PUT request with auto body serialisation.
+   */
+  put<B = unknown>(
+    path: string,
+    body?: B,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response> {
+    const headers = init?.headers as Record<string, string> | undefined;
+    const serialized = this.autoSerializeBody(body, headers ?? {});
+    return this.fetch(path, {
+      ...init,
+      method: "PUT",
+      body: serialized.body,
+      headers: serialized.headers,
+    });
+  }
+
+  /**
+   * PATCH request with auto body serialisation.
+   */
+  patch<B = unknown>(
+    path: string,
+    body?: B,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response> {
+    const headers = init?.headers as Record<string, string> | undefined;
+    const serialized = this.autoSerializeBody(body, headers ?? {});
+    return this.fetch(path, {
+      ...init,
+      method: "PATCH",
+      body: serialized.body,
+      headers: serialized.headers,
+    });
+  }
+
+  /** DELETE request. */
+  delete(
+    path: string,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response> {
+    return this.fetch(path, { ...init, method: "DELETE" });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a pre-configured `FastFetchClient` instance.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'fastfetch-api-fetch-enhancer';
+ *
+ * const api = createClient({
+ *   baseURL: 'https://api.example.com/v1',
+ *   headers: { Authorization: `Bearer ${token}` },
+ *   retries: 3,
+ *   timeout: 8_000,
+ *   circuitBreaker: { threshold: 5, timeout: 30_000 },
+ *   maxConcurrent: 10,
+ *   offlineQueue: true,
+ * });
+ *
+ * // Register middleware
+ * api.use(async (ctx, next) => {
+ *   ctx.init.headers['X-Request-Id'] = crypto.randomUUID();
+ *   await next();
+ *   console.log(`${ctx.method} ${ctx.url} → ${ctx.response?.status} in ${ctx.duration}ms`);
+ * });
+ *
+ * const user  = await api.json<User>('/users/1');
+ * const posts = await api.json<Post[]>('/posts');
+ * await api.post('/users', { name: 'Alice', role: 'admin' }); // auto-JSON
+ * await api.stream('/events', (e) => console.log(e.data));
+ *
+ * console.table(api.metrics.snapshot().byEndpoint);
+ * ```
+ */
+export function createClient(options?: ClientOptions): FastFetchClient {
+  return new FastFetchClient(options);
+}

package/src/errors.ts

@@ -0,0 +1,110 @@
+/**
+ * FastFetch typed error hierarchy.
+ *
+ * All errors extend `FastFetchError` so callers can do:
+ *   catch (e) { if (e instanceof HttpError) { ... } }
+ */
+
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+
+export class FastFetchError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "FastFetchError";
+    if (cause !== undefined) {
+      (this as any).cause = cause;
+    }
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP-level error  (response received, status not ok)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when the server returns a non-2xx response and `throwOnError` is
+ * enabled. Provides direct access to the original Response so callers can
+ * still read the body.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.json<User>('/users/99');
+ * } catch (e) {
+ *   if (e instanceof HttpError) {
+ *     console.error(e.status, e.statusText);
+ *     const body = await e.response.json(); // still accessible
+ *   }
+ * }
+ * ```
+ */
+export class HttpError extends FastFetchError {
+  readonly status: number;
+  readonly statusText: string;
+  /** The original Response — body is still consumable. */
+  readonly response: Response;
+
+  constructor(response: Response) {
+    super(`HTTP ${response.status} ${response.statusText}`);
+    this.name = "HttpError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.response = response;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Timeout error  (AbortController fired our timer)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a request is aborted by FastFetch's own timeout mechanism
+ * (not a user-supplied `AbortSignal`).
+ */
+export class TimeoutError extends FastFetchError {
+  readonly timeout: number;
+
+  constructor(timeoutMs: number) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+    this.timeout = timeoutMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Network error  (no response at all — DNS, CORS, connection refused…)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown on network-level failures where no HTTP response was received.
+ * Wraps the underlying `TypeError` or `DOMException` as `cause`.
+ */
+export class NetworkError extends FastFetchError {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause);
+    this.name = "NetworkError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Circuit-open error  (circuit breaker is OPEN, request immediately rejected)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown immediately when the circuit breaker is in the OPEN state.
+ * No network request is made, protecting the downstream service.
+ */
+export class CircuitOpenError extends FastFetchError {
+  constructor() {
+    super(
+      "Circuit breaker is OPEN — request rejected to protect the downstream service. " +
+        "The circuit will attempt a probe request after the configured timeout.",
+    );
+    this.name = "CircuitOpenError";
+  }
+}