fastfetch-api-fetch-enhancer 2.0.0

package/dist/offline-queue.js

@@ -0,0 +1,120 @@
+/**
+ * FastFetch offline request queue.
+ *
+ * When the environment reports `navigator.onLine === false`, mutating requests
+ * (POST / PUT / PATCH / DELETE) are held in memory and replayed automatically
+ * once the `"online"` event fires.
+ *
+ * Notes:
+ * - Only mutating HTTP methods are queued; GET / HEAD / OPTIONS are always
+ *   passed through so read operations fail fast with a network error.
+ * - This is intentionally an in-memory queue. For durable offline support
+ *   (e.g. across page refreshes) consider combining with Service Workers or
+ *   IndexedDB persistence on top of this class.
+ * - In non-browser environments (Node.js, Deno) the queue is always disabled
+ *   (`isOffline` returns false, `start()` is a no-op).
+ */
+import fetch from "cross-fetch";
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+// ---------------------------------------------------------------------------
+// OfflineQueue
+// ---------------------------------------------------------------------------
+export class OfflineQueue {
+    constructor() {
+        this._queue = [];
+        this._listening = false;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────────
+    /**
+     * Start listening for browser `online` / `offline` events.
+     * Safe to call multiple times (idempotent).
+     */
+    start() {
+        if (this._listening || !this.isBrowser)
+            return;
+        this._listening = true;
+        this._boundOnline = () => void this.replay();
+        window.addEventListener("online", this._boundOnline);
+    }
+    /**
+     * Stop listening and discard all queued requests.
+     * Call this when you no longer need the queue (e.g. component unmount).
+     */
+    stop() {
+        if (this._boundOnline) {
+            if (typeof window !== "undefined") {
+                window.removeEventListener("online", this._boundOnline);
+            }
+            this._boundOnline = undefined;
+        }
+        this._listening = false;
+        this._queue = [];
+    }
+    // ── Status ─────────────────────────────────────────────────────────────
+    get isBrowser() {
+        return typeof window !== "undefined" && typeof navigator !== "undefined";
+    }
+    /**
+     * `true` when the environment reports no network connectivity.
+     * Always `false` in non-browser environments (Node.js / Deno).
+     */
+    get isOffline() {
+        return this.isBrowser && !navigator.onLine;
+    }
+    /**
+     * Returns `true` if this request should be queued (mutating method + offline).
+     */
+    shouldQueue(method) {
+        return this.isOffline && MUTATING_METHODS.has(method.toUpperCase());
+    }
+    // ── Queue management ───────────────────────────────────────────────────
+    /** Add a request to the offline queue. */
+    enqueue(url, init) {
+        this._queue.push({ url, init, queuedAt: Date.now() });
+    }
+    /**
+     * Replay all queued requests in chronological order.
+     * Requests that fail are returned in the result with `success: false`.
+     */
+    async replay() {
+        const pending = this._queue.splice(0); // atomic drain
+        const results = [];
+        for (const req of pending) {
+            const method = (req.init.method ?? "GET").toUpperCase();
+            try {
+                const res = await fetch(req.url, req.init);
+                results.push({
+                    url: req.url,
+                    method,
+                    success: res.ok,
+                    status: res.status,
+                });
+                if (!res.ok) {
+                    // Non-2xx — don't re-queue, just report
+                }
+            }
+            catch (err) {
+                // Network error during replay — re-enqueue at front
+                this._queue.unshift(req);
+                results.push({
+                    url: req.url,
+                    method,
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+    /** Number of requests currently queued. */
+    get size() {
+        return this._queue.length;
+    }
+    /** Snapshot of queued requests (read-only). */
+    get queue() {
+        return this._queue;
+    }
+}

package/dist/queue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FastFetch concurrency-limited async request queue with priority support.
+ *
+ * Ensures at most `maxConcurrent` requests are in-flight at any time.
+ * Excess requests are queued and dispatched as slots become free.
+ */
+export type QueuePriority = "high" | "normal" | "low";
+export declare class RequestQueue {
+    private readonly max;
+    private _active;
+    private readonly waiting;
+    /**
+     * @param maxConcurrent Maximum number of concurrently running requests.
+     * @throws RangeError if `maxConcurrent` < 1.
+     */
+    constructor(maxConcurrent: number);
+    /**
+     * Enqueue a request factory function. If a slot is free it runs immediately;
+     * otherwise it waits until one becomes available.
+     *
+     * @param fn       A zero-argument factory that returns a Promise.
+     * @param priority Execution priority. High-priority jobs skip ahead of normal/low ones.
+     */
+    enqueue<T>(fn: () => Promise<T>, priority?: QueuePriority): Promise<T>;
+    private drain;
+    /** Number of requests currently queued (not yet started). */
+    get pending(): number;
+    /** Number of requests currently running. */
+    get active(): number;
+    /** Configured maximum concurrency. */
+    get concurrency(): number;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAmBtD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAK;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;OAGG;gBACS,aAAa,EAAE,MAAM;IAOjC;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,EACP,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,GAAE,aAAwB,GACjC,OAAO,CAAC,CAAC,CAAC;IAgBb,OAAO,CAAC,KAAK;IAwBb,6DAA6D;IAC7D,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,4CAA4C;IAC5C,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,sCAAsC;IACtC,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/queue.js

@@ -0,0 +1,76 @@
+/**
+ * FastFetch concurrency-limited async request queue with priority support.
+ *
+ * Ensures at most `maxConcurrent` requests are in-flight at any time.
+ * Excess requests are queued and dispatched as slots become free.
+ */
+const PRIORITY_WEIGHT = {
+    high: 0,
+    normal: 1,
+    low: 2,
+};
+// ---------------------------------------------------------------------------
+// RequestQueue
+// ---------------------------------------------------------------------------
+export class RequestQueue {
+    /**
+     * @param maxConcurrent Maximum number of concurrently running requests.
+     * @throws RangeError if `maxConcurrent` < 1.
+     */
+    constructor(maxConcurrent) {
+        this._active = 0;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.waiting = [];
+        if (maxConcurrent < 1) {
+            throw new RangeError(`maxConcurrent must be ≥ 1, got ${maxConcurrent}`);
+        }
+        this.max = maxConcurrent;
+    }
+    /**
+     * Enqueue a request factory function. If a slot is free it runs immediately;
+     * otherwise it waits until one becomes available.
+     *
+     * @param fn       A zero-argument factory that returns a Promise.
+     * @param priority Execution priority. High-priority jobs skip ahead of normal/low ones.
+     */
+    enqueue(fn, priority = "normal") {
+        return new Promise((resolve, reject) => {
+            this.waiting.push({ fn, priority, resolve, reject });
+            // Sort descending by weight so index 0 is the highest-priority entry.
+            // Use a stable insertion to avoid reordering equal-priority entries.
+            this.waiting.sort((a, b) => PRIORITY_WEIGHT[a.priority] - PRIORITY_WEIGHT[b.priority]);
+            this.drain();
+        });
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    drain() {
+        while (this._active < this.max && this.waiting.length > 0) {
+            const entry = this.waiting.shift();
+            this._active++;
+            entry
+                .fn()
+                .then((value) => {
+                this._active--;
+                entry.resolve(value);
+                this.drain();
+            }, (err) => {
+                this._active--;
+                entry.reject(err);
+                this.drain();
+            });
+        }
+    }
+    // ── Observability ────────────────────────────────────────────────────────
+    /** Number of requests currently queued (not yet started). */
+    get pending() {
+        return this.waiting.length;
+    }
+    /** Number of requests currently running. */
+    get active() {
+        return this._active;
+    }
+    /** Configured maximum concurrency. */
+    get concurrency() {
+        return this.max;
+    }
+}

package/dist/streaming.d.ts

@@ -0,0 +1,40 @@
+/**
+ * FastFetch Server-Sent Events (SSE) streaming support.
+ *
+ * Consumes a `ReadableStream` from a `fetch()` Response body and calls
+ * `handler` for each well-formed SSE event received.
+ *
+ * SSE spec reference: https://html.spec.whatwg.org/#server-sent-events
+ */
+export interface SSEEvent {
+    /** Event type field (defaults to `"message"` if not specified by server). */
+    type: string;
+    /** The `data` field value. Multi-line data fields are joined with `\n`. */
+    data: string;
+    /** Optional `id` field from the server. */
+    id?: string;
+    /** Optional `retry` field in milliseconds. */
+    retry?: number;
+}
+export type SSEHandler = (event: SSEEvent) => void | Promise<void>;
+/**
+ * Consume a Server-Sent Events stream and invoke `handler` for each event.
+ *
+ * The function resolves when the stream ends (or `signal` is aborted).
+ * The underlying reader is always released in the `finally` block.
+ *
+ * @param reader  A `ReadableStreamDefaultReader<Uint8Array>` from `response.body.getReader()`.
+ * @param handler Called for each complete SSE event.
+ * @param signal  Optional `AbortSignal` to stop consuming early.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch('/api/stream');
+ * if (!res.body) throw new Error('No body');
+ * await consumeSSE(res.body.getReader(), (event) => {
+ *   console.log(event.type, event.data);
+ * });
+ * ```
+ */
+export declare function consumeSSE(reader: ReadableStreamDefaultReader<Uint8Array>, handler: SSEHandler, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAMnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAC/C,OAAO,EAAE,UAAU,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyEf"}

package/dist/streaming.js

@@ -0,0 +1,98 @@
+/**
+ * FastFetch Server-Sent Events (SSE) streaming support.
+ *
+ * Consumes a `ReadableStream` from a `fetch()` Response body and calls
+ * `handler` for each well-formed SSE event received.
+ *
+ * SSE spec reference: https://html.spec.whatwg.org/#server-sent-events
+ */
+// ---------------------------------------------------------------------------
+// consumeSSE
+// ---------------------------------------------------------------------------
+/**
+ * Consume a Server-Sent Events stream and invoke `handler` for each event.
+ *
+ * The function resolves when the stream ends (or `signal` is aborted).
+ * The underlying reader is always released in the `finally` block.
+ *
+ * @param reader  A `ReadableStreamDefaultReader<Uint8Array>` from `response.body.getReader()`.
+ * @param handler Called for each complete SSE event.
+ * @param signal  Optional `AbortSignal` to stop consuming early.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch('/api/stream');
+ * if (!res.body) throw new Error('No body');
+ * await consumeSSE(res.body.getReader(), (event) => {
+ *   console.log(event.type, event.data);
+ * });
+ * ```
+ */
+export async function consumeSSE(reader, handler, signal) {
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    function parseAndEmit(block) {
+        // SSE field defaults
+        let eventType = "message";
+        let data = "";
+        let id;
+        let retry;
+        for (const line of block.split("\n")) {
+            const colon = line.indexOf(":");
+            if (colon === -1)
+                continue; // ignore malformed lines
+            const field = line.slice(0, colon).trim();
+            // A space immediately after ":" is part of the spec and must be stripped.
+            const value = line.slice(colon + 1).replace(/^ /, "");
+            switch (field) {
+                case "event":
+                    eventType = value;
+                    break;
+                case "data":
+                    data = data ? `${data}\n${value}` : value;
+                    break;
+                case "id":
+                    id = value;
+                    break;
+                case "retry": {
+                    const ms = parseInt(value, 10);
+                    if (!isNaN(ms))
+                        retry = ms;
+                    break;
+                }
+                // "comment" lines (field === "") are silently ignored per spec
+            }
+        }
+        // Dispatch only if a data field was present (spec §9.2.6)
+        if (data !== "") {
+            void handler({ type: eventType, data, id, retry });
+        }
+    }
+    try {
+        while (true) {
+            if (signal?.aborted)
+                break;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Events are separated by two newlines (\n\n or \r\n\r\n)
+            // Split on double-newline — keep trailing incomplete chunk in buffer.
+            const parts = buffer.split(/\n\n|\r\n\r\n/);
+            buffer = parts.pop() ?? "";
+            for (const block of parts) {
+                const trimmed = block.trim();
+                if (trimmed) {
+                    parseAndEmit(trimmed);
+                }
+            }
+        }
+        // Flush any remaining data in the buffer
+        if (buffer.trim()) {
+            parseAndEmit(buffer.trim());
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/index.d.ts

@@ -0,0 +1,167 @@
+// ---------------------------------------------------------------------------
+// FastFetch core options
+// ---------------------------------------------------------------------------
+
+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 count (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 `DOMException` with name `"AbortError"` on timeout.
+   */
+  timeout?: number;
+  /**
+   * Cache successful GET responses in memory (default: false).
+   * Only applies to GET requests.
+   */
+  cache?: boolean;
+  /** How long (ms) to keep a cached response fresh (default: 30 000). */
+  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 or Response that triggered 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;
+}
+
+/** The main fastFetch function — a smarter fetch() wrapper. */
+export declare function fastFetch(
+  input: RequestInfo,
+  init?: RequestInit & FastFetchOptions,
+): Promise<Response>;
+
+/**
+ * Clear all TTL-cached responses, or only entries matching a specific URL.
+ * @param url  If supplied, only cache entries whose key contains this string are removed.
+ */
+export declare function clearCache(url?: string): void;
+
+// ---------------------------------------------------------------------------
+// createClient — interceptors & types
+// ---------------------------------------------------------------------------
+
+/** Mutates and returns the request init before it is sent. */
+export type RequestInterceptor = (
+  url: string,
+  init: RequestInit & FastFetchOptions,
+) => (RequestInit & FastFetchOptions) | Promise<RequestInit & FastFetchOptions>;
+
+/** Transforms the Response after a successful fetch. */
+export type ResponseInterceptor = (
+  response: Response,
+) => Response | Promise<Response>;
+
+/** Called when a request ultimately fails (after all retries). */
+export type ErrorInterceptor = (error: unknown) => unknown | Promise<unknown>;
+
+/** Options passed to `createClient()`. */
+export interface ClientOptions extends FastFetchOptions {
+  /**
+   * Base URL prepended to relative paths.
+   * @example `'https://api.example.com/v1'`
+   */
+  baseURL?: string;
+  /** Default headers merged into every request. */
+  headers?: Record<string, string>;
+  interceptors?: {
+    /** Run before the request — inject auth, signing, tracing headers, etc. */
+    request?: RequestInterceptor[];
+    /** Run after a successful response — unwrap envelopes, log, transform, etc. */
+    response?: ResponseInterceptor[];
+    /** Run when a request ultimately fails — centralise error handling. */
+    error?: ErrorInterceptor[];
+  };
+}
+
+/**
+ * A pre-configured FastFetch client with base URL, default headers,
+ * interceptors, and typed HTTP method shorthands.
+ *
+ * @example
+ * ```ts
+ * const api = createClient({
+ *   baseURL: 'https://api.example.com',
+ *   headers: { Authorization: 'Bearer token' },
+ *   retries: 3,
+ *   timeout: 8000,
+ * });
+ *
+ * const user  = await api.json<User>('/users/1');
+ * const posts = await api.json<Post[]>('/posts');
+ * await api.post('/users', { name: 'Alice' });
+ * await api.delete('/users/42');
+ * ```
+ */
+export declare class FastFetchClient {
+  constructor(options?: ClientOptions);
+
+  /** Core fetch — resolves URL, runs interceptors, returns raw Response. */
+  fetch(path: string, init?: RequestInit & FastFetchOptions): Promise<Response>;
+
+  /**
+   * Fetch and auto-parse JSON. Returns typed `Promise<T>`.
+   * @example `const user = await api.json<User>('/users/1');`
+   */
+  json<T = unknown>(
+    path: string,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<T>;
+
+  get(path: string, init?: RequestInit & FastFetchOptions): Promise<Response>;
+
+  post<T = unknown>(
+    path: string,
+    body?: T,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response>;
+
+  put<T = unknown>(
+    path: string,
+    body?: T,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response>;
+
+  patch<T = unknown>(
+    path: string,
+    body?: T,
+    init?: RequestInit & FastFetchOptions,
+  ): Promise<Response>;
+
+  delete(path: string, init?: RequestInit & FastFetchOptions): Promise<Response>;
+}
+
+/**
+ * Create a pre-configured `FastFetchClient` instance.
+ *
+ * @example
+ * ```ts
+ * const api = createClient({
+ *   baseURL: 'https://api.example.com/v1',
+ *   headers: { Authorization: `Bearer ${token}` },
+ *   retries: 3,
+ *   timeout: 8000,
+ *   interceptors: {
+ *     request: [(url, init) => { init.headers['X-Trace'] = 'abc'; return init; }],
+ *   },
+ * });
+ * ```
+ */
+export declare function createClient(options?: ClientOptions): FastFetchClient;

package/jest.config.js

@@ -0,0 +1,16 @@
+export default {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  extensionsToTreatAsEsm: [".ts"],
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "fastfetch-api-fetch-enhancer",
+  "displayName": "FastFetch – Smart API Fetcher",
+  "version": "2.0.0",
+  "description": "Production-grade HTTP client with circuit breakers, concurrency queues, metrics, SSE streaming, and typed errors.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build",
+    "demo": "node __tests__/demo.js",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,css,scss,md,html}\""
+  },
+  "keywords": [
+    "fetch",
+    "http-client",
+    "circuit-breaker",
+    "middleware",
+    "concurrency-queue",
+    "sse",
+    "telemetry",
+    "offline-queue",
+    "retry",
+    "axios-alternative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/softsideof/FastFetch-API-Fetch-Enhancer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/softsideof/FastFetch-API-Fetch-Enhancer/issues"
+  },
+  "homepage": "https://github.com/softsideof/FastFetch-API-Fetch-Enhancer#readme",
+  "license": "MIT",
+  "author": "softsideof",
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "cross-fetch": "^4.1.0"
+  }
+}