feat: implement offline request buffering

Author: softsideof

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;
+  }
+}