fastfetch-api-fetch-enhancer 2.0.0

package/src/offline-queue.ts

@@ -0,0 +1,150 @@
+/**
+ * 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"]);
+
+export interface OfflineRequest {
+  url: string;
+  init: RequestInit;
+  queuedAt: number;
+}
+
+export interface ReplayResult {
+  url: string;
+  method: string;
+  success: boolean;
+  status?: number;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// OfflineQueue
+// ---------------------------------------------------------------------------
+
+export class OfflineQueue {
+  private _queue: OfflineRequest[] = [];
+  private _listening = false;
+  private _boundOnline?: () => void;
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────
+
+  /**
+   * Start listening for browser `online` / `offline` events.
+   * Safe to call multiple times (idempotent).
+   */
+  start(): void {
+    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(): void {
+    if (this._boundOnline) {
+      if (typeof window !== "undefined") {
+        window.removeEventListener("online", this._boundOnline);
+      }
+      this._boundOnline = undefined;
+    }
+    this._listening = false;
+    this._queue = [];
+  }
+
+  // ── Status ─────────────────────────────────────────────────────────────
+
+  private get isBrowser(): boolean {
+    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(): boolean {
+    return this.isBrowser && !navigator.onLine;
+  }
+
+  /**
+   * Returns `true` if this request should be queued (mutating method + offline).
+   */
+  shouldQueue(method: string): boolean {
+    return this.isOffline && MUTATING_METHODS.has(method.toUpperCase());
+  }
+
+  // ── Queue management ───────────────────────────────────────────────────
+
+  /** Add a request to the offline queue. */
+  enqueue(url: string, init: RequestInit): void {
+    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(): Promise<ReplayResult[]> {
+    const pending = this._queue.splice(0); // atomic drain
+    const results: ReplayResult[] = [];
+
+    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: unknown) {
+        // 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(): number {
+    return this._queue.length;
+  }
+
+  /** Snapshot of queued requests (read-only). */
+  get queue(): ReadonlyArray<OfflineRequest> {
+    return this._queue;
+  }
+}

package/src/queue.ts

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type QueuePriority = "high" | "normal" | "low";
+
+const PRIORITY_WEIGHT: Record<QueuePriority, number> = {
+  high: 0,
+  normal: 1,
+  low: 2,
+};
+
+interface QueueEntry<T> {
+  fn: () => Promise<T>;
+  priority: QueuePriority;
+  resolve: (value: T) => void;
+  reject: (reason: unknown) => void;
+}
+
+// ---------------------------------------------------------------------------
+// RequestQueue
+// ---------------------------------------------------------------------------
+
+export class RequestQueue {
+  private readonly max: number;
+  private _active = 0;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private readonly waiting: QueueEntry<any>[] = [];
+
+  /**
+   * @param maxConcurrent Maximum number of concurrently running requests.
+   * @throws RangeError if `maxConcurrent` < 1.
+   */
+  constructor(maxConcurrent: number) {
+    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<T>(
+    fn: () => Promise<T>,
+    priority: QueuePriority = "normal",
+  ): Promise<T> {
+    return new Promise<T>((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 ─────────────────────────────────────────────────────────────
+
+  private drain(): void {
+    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(): number {
+    return this.waiting.length;
+  }
+
+  /** Number of requests currently running. */
+  get active(): number {
+    return this._active;
+  }
+
+  /** Configured maximum concurrency. */
+  get concurrency(): number {
+    return this.max;
+  }
+}

package/src/streaming.ts

@@ -0,0 +1,127 @@
+/**
+ * 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
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+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>;
+
+// ---------------------------------------------------------------------------
+// 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: ReadableStreamDefaultReader<Uint8Array>,
+  handler: SSEHandler,
+  signal?: AbortSignal,
+): Promise<void> {
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+
+  function parseAndEmit(block: string): void {
+    // SSE field defaults
+    let eventType = "message";
+    let data = "";
+    let id: string | undefined;
+    let retry: number | undefined;
+
+    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/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2020",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "**/__tests__"]
+}
+