@swoff/cli 0.3.9 → 0.3.11

package/dist/runtime/client-injector.js

@@ -0,0 +1,136 @@
+export function generateClientInjectorCode(ctx, pwaEnabled, mutationQueueEnabled, serverPushEnabled) {
+    const { ext, ts } = ctx;
+    const pwaImport = pwaEnabled
+        ? `import { setupPwaInstall } from "./pwa/injector.${ext}";
+`
+        : "";
+    const pwaCall = pwaEnabled ? `setupPwaInstall();\n` : "";
+    const pushImport = serverPushEnabled
+        ? `import { startPushEvents } from "./realtime/server-push.${ext}";
+`
+        : "";
+    const pushCall = serverPushEnabled ? `startPushEvents();\n` : "";
+    const mutationImport = mutationQueueEnabled
+        ? `import { processMutationQueue } from "./offline/queue.${ext}";
+`
+        : "";
+    const mutationOnlineListener = mutationQueueEnabled
+        ? `
+// --- Mutation Queue Online Listener ---
+window.addEventListener("online", processMutationQueue);
+`
+        : "";
+    const onlineRefetchListener = `
+// --- Online Refetch Listener ---
+// When connectivity returns, the SW checks stale cache entries and refetches them.
+if (typeof window !== "undefined") {
+  window.addEventListener("online", () => {
+    if (navigator.serviceWorker.controller) {
+      navigator.serviceWorker.controller.postMessage({ type: "ONLINE" });
+    }
+  });
+}
+`;
+    const focusListener = `
+// --- Focus Listener for Reactive Strategy ---
+// Notifies the SW when the tab gains focus so it can refresh stale reactive entries.
+// Uses visibilitychange only (covers tab switch, window refocus, alt-tab) — single source avoids duplicate FOCUS messages.
+if (typeof document !== "undefined") {
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "visible" && navigator.serviceWorker.controller) {
+      navigator.serviceWorker.controller.postMessage({ type: "FOCUS" });
+    }
+  });
+}
+`;
+    const invalidationHandler = `
+    if (event.data.type === "TAG_INVALIDATED" && event.data.tag) {
+      window.dispatchEvent(
+        new CustomEvent("cache-invalidated", {
+          detail: { tags: [event.data.tag] },
+        })
+      );
+    }
+`;
+    const swImport = `import { initServiceWorker as swInit } from "./sw/injector.${ext}";
+`;
+    return `/**
+ * Swoff Client Injector
+ * Orchestrates SW registration, PWA install, and cross-tab sync.
+ * Single entry point for all Swoff client-side features.
+ *
+ * Usage:
+ *   import { initServiceWorker } from './swoff/client-injector.${ext}';
+ *   initServiceWorker();
+ *
+ * Window events (dispatched by this module):
+ *   sw-progress              - Download progress (detail: { percent, downloaded, total })
+ *   sw-ready                 - SW active and controlling page
+ *   sw-error                 - SW registration failed
+ *   cache-invalidated        - Cache entries cleared on SW confirmation (detail: { tags })
+ *   swoff:cache-updated      - Background refresh completed (detail: { url })
+ *   mutation-sync-complete   - Queued mutations synced (detail: { succeeded, failed })
+ *   mutation-sync-progress   - Batch progress during sync (detail: { succeeded, failed, total, current })
+ *   mutation-queue-changed   - Queue modified
+ *
+ * Window events (dispatched by feature modules):
+ *   pwa-installable       - PWA can be installed (detail: { isInstallable: true })
+ *   pwa-installed         - User accepted install (detail: { outcome: 'accepted' })
+ *   sw-auth-unauthorized  - 401 response received
+ *   sw-auth-state-change  - Login or logout (detail: { authenticated: boolean })
+ *   sw-update-available   - New version ready (detail: { version })
+ *   sw-version-detected   - Version info available
+ */
+${pwaImport}${mutationImport}${swImport}${pushImport}
+${pwaCall}${mutationOnlineListener}${pushCall}${onlineRefetchListener}${focusListener}
+// --- SW Message Listener ---
+if (typeof window !== "undefined" && "serviceWorker" in navigator) {
+  navigator.serviceWorker.addEventListener("message", (event) => {
+    if (event.data.type === "CACHE_UPDATED") {
+      window.dispatchEvent(
+        new CustomEvent("swoff:cache-updated", {
+          detail: { url: event.data.url },
+        })
+      );
+    }
+    if (event.data.type === "SW_PROGRESS") {
+      const { percent, downloaded, total } = event.data;
+      window.dispatchEvent(
+        new CustomEvent("sw-progress", {
+          detail: { percent, downloaded, total },
+        })
+      );
+    }
+    if (event.data.type === "BACKGROUND_SYNC_PROGRESS") {
+      window.dispatchEvent(
+        new CustomEvent("mutation-sync-progress", {
+          detail: event.data.detail,
+        })
+      );
+    }
+    if (event.data.type === "BACKGROUND_SYNC_COMPLETE") {
+      const { succeeded, failed, tags } = event.data.detail;
+      window.dispatchEvent(
+        new CustomEvent("mutation-sync-complete", {
+          detail: { succeeded, failed },
+        })
+      );
+      if (tags && tags.length > 0) {
+        window.dispatchEvent(
+          new CustomEvent("cache-invalidated", { detail: { tags } })
+        );
+      }
+      window.dispatchEvent(new CustomEvent("mutation-queue-changed"));
+    }
+    if (event.data.type === "MUTATION_STORED") {
+      typeof processMutationQueue !== "undefined" && processMutationQueue();
+    }${invalidationHandler}  });
+}
+
+/** Initialize SW registration and all client-side features (PWA install, mutation queue, cross-tab sync). Call once at app startup. */
+export async function initServiceWorker()${ts ? ": Promise<void>" : " "}{
+  await swInit();
+}
+`;
+}
+//# sourceMappingURL=client-injector.js.map

package/dist/runtime/client-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-injector.js","sourceRoot":"","sources":["../../src/runtime/client-injector.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,0BAA0B,CACxC,GAAmB,EACnB,UAAmB,EACnB,oBAA6B,EAC7B,iBAA0B;IAE1B,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC;IAExB,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC,mDAAmD,GAAG;CAC3D;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzD,MAAM,UAAU,GAAG,iBAAiB;QAClC,CAAC,CAAC,2DAA2D,GAAG;CACnE;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,QAAQ,GAAG,iBAAiB,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjE,MAAM,cAAc,GAAG,oBAAoB;QACzC,CAAC,CAAC,yDAAyD,GAAG;CACjE;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,sBAAsB,GAAG,oBAAoB;QACjD,CAAC,CAAC;;;CAGL;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,qBAAqB,GAAG;;;;;;;;;;CAU/B,CAAC;IAEA,MAAM,aAAa,GAAG;;;;;;;;;;;CAWvB,CAAC;IAEA,MAAM,mBAAmB,GAAG;;;;;;;;CAQ7B,CAAC;IAEA,MAAM,QAAQ,GAAG,8DAA8D,GAAG;CACnF,CAAC;IAEA,OAAO;;;;;;kEAMyD,GAAG;;;;;;;;;;;;;;;;;;;;;EAqBnE,SAAS,GAAG,cAAc,GAAG,QAAQ,GAAG,UAAU;EAClD,OAAO,GAAG,sBAAsB,GAAG,QAAQ,GAAG,qBAAqB,GAAG,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0C9E,mBAAmB;;;;2CAIiB,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG;;;CAGtE,CAAC;AACF,CAAC"}

package/dist/runtime/fetch-state.js

@@ -0,0 +1,42 @@
+import { R } from "./utils.js";
+export function generateFetchStateCode(ctx) {
+    const { ext, ts } = ctx;
+    return `/**
+ * Swoff Fetch State
+ * Global in-flight fetch counter. Incremented by fetchWithCache and used by
+ * useIsFetching for a reactive global loading indicator.
+ *
+ * Usage:
+ *   import { incrementFetchCount, decrementFetchCount, getFetchCount } from './swoff/fetch-state.${ext}';
+ *
+ *   // Manual tracking (if you bypass fetchWithCache):
+ *   incrementFetchCount();
+ *   // ... fetch ...
+ *   decrementFetchCount();
+ *
+ * Custom event:
+ *   fetch-count-changed  — dispatched on every increment/decrement
+ *                          detail: { count: number }
+ */
+
+let _fetchCount = 0;
+
+/** Increment the global fetch counter. Dispatches fetch-count-changed. */
+export function incrementFetchCount()${R(ts, "void")}{
+  _fetchCount++;
+  window.dispatchEvent(new CustomEvent("fetch-count-changed", { detail: { count: _fetchCount } }));
+}
+
+/** Decrement the global fetch counter. Dispatches fetch-count-changed. Never goes below 0. */
+export function decrementFetchCount()${R(ts, "void")}{
+  _fetchCount = Math.max(0, _fetchCount - 1);
+  window.dispatchEvent(new CustomEvent("fetch-count-changed", { detail: { count: _fetchCount } }));
+}
+
+/** Synchronously get the current fetch count. */
+export function getFetchCount()${R(ts, "number")}{
+  return _fetchCount;
+}
+`;
+}
+//# sourceMappingURL=fetch-state.js.map

package/dist/runtime/fetch-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-state.js","sourceRoot":"","sources":["../../src/runtime/fetch-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAE/B,MAAM,UAAU,sBAAsB,CAAC,GAAmB;IACxD,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC;IACxB,OAAO;;;;;;oGAM2F,GAAG;;;;;;;;;;;;;;;uCAehE,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC;;;;;;uCAMb,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC;;;;;;iCAMnB,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC;;;CAG/C,CAAC;AACF,CAAC"}

package/dist/runtime/fetch-wrapper.js

@@ -0,0 +1,355 @@
+import { T, R, G } from "./utils.js";
+export function generateFetchWrapperCode(ctx, authEnabled, userEndpoint, mutationQueue, requestBatchWindowMs) {
+    const { ext, ts } = ctx;
+    const importLines = [
+        `import { API_BASE } from "../config.${ext}";`,
+        `import { generateTags, invalidateUrl${mutationQueue ? ", expandCascading" : ""} } from "../cache/tags.${ext}";`,
+        `import { invalidateByTags } from "../cache/index.${ext}";`,
+        authEnabled
+            ? `import { getAuth, clearAuth, withAuthHeaders, isAuthUrl, ensureValidAuth, AUTH_WITH_CREDENTIALS } from "../auth/store.${ext}";`
+            : "",
+        mutationQueue
+            ? `import { queueMutation } from "../offline/queue.${ext}";`
+            : "",
+        `import { incrementFetchCount, decrementFetchCount } from "../fetch/state.${ext}";`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const interfaceBlock = ts
+        ? `
+export interface FetchWithCacheResult${G(ts, "T")} {
+  response${T(ts, "Response & { json(): Promise<T> }")};
+  fromCache${T(ts, "boolean")};
+  queued${T(ts, "boolean")};
+}
+`
+        : "";
+    const optionsInterface = ts
+        ? `
+export interface FetchWithCacheOptions extends RequestInit {
+  tags?: string[];
+  auth?: boolean;
+  queueOffline?: boolean;
+  invalidate?: 'auto' | string[] | false;
+  type?: 'read' | 'mutation';
+  strategy?: 'cache-first' | 'network-first' | 'stale-while-revalidate' | 'cache-only' | 'network-only' | 'reactive';
+  staleTime?: number;
+  refetchInterval?: number;
+  refetchOnFocus?: boolean;
+  refetchOnReconnect?: boolean;
+  /** Custom response validation for mutation success. Default: res.ok. Use this when your API returns 200 with { success: false } for logical failures. */
+  validateSuccess?: (response: Response) => boolean | Promise<boolean>;
+  /** Override the URL used for auto-invalidation. Defaults to the request URL. Useful when the mutation URL differs from the cache tag URL. */
+  invalidateUrl?: string;
+  /** Skip global fetch counter tracking. Used by prefetchCache to avoid triggering loading bars. */
+  skipFetchCount?: boolean;
+}
+`
+        : "";
+    const authBlock = authEnabled
+        ? `
+  if (options.auth) {
+    const auth = await getAuth();
+    withAuthHeaders(headers, auth);
+  }`
+        : "";
+    const authUrlsBlock = authEnabled
+        ? `
+  // Auth endpoints bypass SW cache
+  if (options.auth && isAuthUrl(url) && !headers.has("X-SW-Cache-Strategy")) {
+    headers.set("X-SW-Cache-Strategy", "mutation");
+  }`
+        : "";
+    const authCredentialsBlock = authEnabled
+        ? `
+  if (AUTH_WITH_CREDENTIALS) {
+    fetchOptions.credentials = "include";
+  }`
+        : "";
+    const auth401Block = authEnabled
+        ? `
+  if (options.auth && response.status === 401) {
+    // Check if the token is actually expired by probing the user endpoint
+    try {
+      const authCheck = await fetch(API_BASE + "${userEndpoint}", {
+        headers: { "Authorization": headers.get("Authorization") } as HeadersInit,
+        credentials: AUTH_WITH_CREDENTIALS ? "include" : undefined,
+      });
+      if (authCheck.status === 401) {
+        // Token expired — try silent refresh
+        const refreshed = await ensureValidAuth();
+        if (refreshed?.token) {
+          // Retry original request with fresh token
+          const retryHeaders = new Headers(options.headers);
+          withAuthHeaders(retryHeaders, refreshed);
+          response = await fetch(resolvedInput, { ...fetchOptions, headers: retryHeaders });
+        } else {
+          await clearAuth();
+          window.dispatchEvent(new CustomEvent("sw-auth-unauthorized"));
+        }
+      }
+      // authCheck 200: user IS authenticated but lacks permission — let original 401 propagate
+    } catch {
+      await clearAuth();
+      window.dispatchEvent(new CustomEvent("sw-auth-unauthorized"));
+    }
+  }`
+        : "";
+    const mutationTagsBlock = mutationQueue
+        ? `  // Pre-compute invalidation tags for SW-side IDB storage
+  let mutationTags: string[] = [];
+  if (!isRead) {
+    const invalidateSetting = options.invalidate !== false ? (options.invalidate || 'auto') : false;
+    if (invalidateSetting !== false) {
+      if (Array.isArray(invalidateSetting)) {
+        mutationTags = invalidateSetting;
+      } else {
+        mutationTags = generateTags(url);
+        mutationTags = expandCascading(mutationTags);
+      }
+      headers.set("X-SW-Invalidate-Tags", mutationTags.join(","));
+    }
+  }`
+        : "";
+    const offlineReadCatchBlock = `    if (options.signal?.aborted) throw new DOMException("The operation was aborted", "AbortError");
+      const cached = await caches.match(resolvedInput);
+      if (cached) return { response: cached, fromCache: true, queued: false };
+      throw new Error("Offline: no cached data available", { cause: err });`;
+    const offlineWriteFallbackBlock = mutationQueue
+        ? `    if (options.queueOffline !== false) {
+      const ct = headers.get("Content-Type");
+      await queueMutation({
+        method,
+        url,
+        body: options.body,
+        headers: ct ? { "Content-Type": ct } : {},
+        tags: mutationTags,
+        timestamp: Date.now(),
+      });
+      return {
+        response: new Response(JSON.stringify({ queued: true }), { status: 202, headers: { "Content-Type": "application/json" } }),
+        fromCache: false,
+        queued: true,
+      };
+    }`
+        : ``;
+    const autoInvalidateBlock = `
+  // Auto-invalidate after mutation success (skip if SW queued it)
+  const mutationSuccess = options.validateSuccess ? await options.validateSuccess(response) : response.ok;
+  const mutationQueued = response.headers.get("X-SW-Mutation-Queued") === "true";
+  if (!isRead && mutationSuccess && !mutationQueued) {
+    const invalidateSetting = options.invalidate !== false ? (options.invalidate || 'auto') : false;
+    if (invalidateSetting !== false) {
+      const invalidateTarget = options.invalidateUrl || url;
+      if (Array.isArray(invalidateSetting)) {
+        await invalidateByTags(invalidateSetting);
+      } else {
+        await invalidateUrl(invalidateTarget);
+      }
+    }
+  }`;
+    const autoTagsBlock = `
+  // Auto-generate tags from URL if not provided
+  if (!options.tags && isRead) {
+    const urlTags = generateTags(url);
+    if (urlTags.length > 0) {
+      headers.set("X-SW-Cache-Tags", urlTags.join(","));
+    }
+  }`;
+    return `/**
+ * Swoff Fetch Wrapper
+ * Unified fetch with caching, auth, offline queue, auto-invalidation, staleTime, prefetching, and
+ * per-request strategy override.
+ *
+ * Usage:
+ *   import { fetchWithCache, prefetchCache } from './swoff/fetch/core.${ext}';
+ *
+ *   // GET — cached with auto-generated tags
+ *   const { response } = await fetchWithCache("/api/todos");
+ *   const data = await response.json();
+ *
+ *   // POST — mutation with auto-invalidation
+ *   await fetchWithCache("/api/todos", {
+ *     method: "POST",
+ *     body: JSON.stringify({ title: "New task" }),
+ *   });
+ *
+ *   // Skip auto-invalidation, invalidate manually later
+ *   await fetchWithCache("/api/todos", {
+ *     method: "POST",
+ *     body: JSON.stringify({ title: "New" }),
+ *     invalidate: false,
+ *   });
+ *
+ *   // Validate mutation success with custom logic
+ *   await fetchWithCache("/api/todos", {
+ *     method: "POST",
+ *     body: JSON.stringify({ title: "New" }),
+ *     validateSuccess: (res) => res.status === 200,
+ *   });
+ *
+ *   // Custom tags for caching (read) + explicit invalidate tags (mutation)
+ *   await fetchWithCache("/api/todos", {
+ *     tags: ["custom-tag"],
+ *     invalidate: ["custom-tag"],
+ *   });
+ *
+ *   // Authenticated request (works with bearer, cookie, custom)
+ *   const { response: userRes } = await fetchWithCache("/api/me", { auth: true });
+ *
+ *   // Prefetch (fire-and-forget warm the cache)
+ *   prefetchCache("/api/todos");
+ *
+ *   // Override caching strategy per-request (highest priority)
+ *   await fetchWithCache("/api/checkout", {
+ *     method: "POST",
+ *     type: "read",
+ *     strategy: "network-only",
+ *   });
+ *
+ *   // Support AbortController for cancellation
+ *   const controller = new AbortController();
+ *   setTimeout(() => controller.abort(), 5000);
+ *   const { response } = await fetchWithCache("/api/todos", { signal: controller.signal });
+ *
+ *   // Offline: auto-queues writes (disable with queueOffline: false)
+ *   await fetchWithCache("/api/todos", {
+ *     method: "POST",
+ *     body: JSON.stringify({ title: "Offline task" }),
+ *   });
+ *   // When back online, processMutationQueue() replays them
+ */
+
+${importLines}
+${interfaceBlock}${optionsInterface}
+const inFlightRequests = new Map${G(ts, "string, Promise<Response>")}();
+const pendingBatches = new Map${G(ts, "string, { resolvers: Array<(r: Response) => void>; rejectors: Array<(e: unknown) => void>; timer: ReturnType<typeof setTimeout> }")}();
+const BATCH_WINDOW_MS = ${requestBatchWindowMs};
+
+/** Fetch with caching, auth, offline queue, auto-invalidation, and per-request strategy override. Returns { response, fromCache }. Use { auth: true } for authenticated requests — works with bearer, cookie, and custom auth types. */
+export async function fetchWithCache${G(ts, "T")}(input${T(ts, "RequestInfo")}, options${T(ts, "RequestInit & FetchWithCacheOptions")} = {})${R(ts, "Promise<FetchWithCacheResult<T>>")}{
+  if (!options.skipFetchCount) incrementFetchCount();
+  try {
+  const method = (options.method || "GET").toUpperCase();
+  const isRead = options.type === "read" || (options.type !== "mutation" && (method === "GET" || method === "HEAD" || method === "OPTIONS"));
+  const resolvedInput = typeof input === "string" && !input.startsWith("http") && !input.startsWith("//") ? API_BASE + input : input;
+  const url = typeof resolvedInput === "string" ? resolvedInput : resolvedInput.url;
+
+  const headers = new Headers(options.headers);
+
+  // Set cache strategy
+  if (!headers.has("X-SW-Cache-Strategy")) {
+    headers.set("X-SW-Cache-Strategy", isRead ? "read" : "mutation");
+  }
+${autoTagsBlock}
+  // Custom tags override auto-generated
+  if (options.tags && options.tags.length > 0) {
+    headers.set("X-SW-Cache-Tags", options.tags.join(","));
+  }
+
+  if (options.strategy) {
+    headers.set("X-SW-Strategy", options.strategy);
+  }
+  if (options.staleTime !== undefined) {
+    headers.set("X-SW-Stale-Time", String(options.staleTime));
+  }
+  if (options.refetchInterval !== undefined) {
+    headers.set("X-SW-Refetch-Interval", String(options.refetchInterval));
+  }
+  if (options.refetchOnFocus !== undefined) {
+    headers.set("X-SW-Refetch-On-Focus", String(options.refetchOnFocus));
+  }
+  if (options.refetchOnReconnect !== undefined) {
+    headers.set("X-SW-Refetch-On-Reconnect", String(options.refetchOnReconnect));
+  }
+${authBlock}${authUrlsBlock}
+  // Forward no-queue option to SW
+  if (options.queueOffline === false) {
+    headers.set("X-SW-No-Queue", "true");
+  }
+
+  const fetchOptions${T(ts, "RequestInit")} = { ...options, headers };
+${authCredentialsBlock}
+
+  // Check for abort before proceeding
+  if (options.signal?.aborted) {
+    throw new DOMException("The operation was aborted", "AbortError");
+  }
+${mutationTagsBlock}
+  // Request batching + dedup for concurrent reads
+  let responsePromise${T(ts, "Promise<Response>")};
+  if (isRead && inFlightRequests.has(url)) {
+    responsePromise = inFlightRequests.get(url)!.then((r) => r.clone());
+  } else if (isRead && pendingBatches.has(url)) {
+    responsePromise = new Promise((resolve, reject) => {
+      pendingBatches.get(url)!.resolvers.push(resolve);
+      pendingBatches.get(url)!.rejectors.push(reject);
+    });
+  } else {
+    const abortHandler = () => {
+      inFlightRequests.delete(url);
+    };
+    if (options.signal) {
+      options.signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    if (isRead && BATCH_WINDOW_MS > 0) {
+      const batch${T(ts, "{ resolvers: Array<(r: Response) => void>; rejectors: Array<(e: unknown) => void>; timer: ReturnType<typeof setTimeout> }")} = { resolvers: [], rejectors: [], timer: 0 };
+      pendingBatches.set(url, batch);
+      batch.timer = setTimeout(() => {
+        pendingBatches.delete(url);
+        const promise = fetch(resolvedInput, fetchOptions);
+        const cleanup = () => {
+          inFlightRequests.delete(url);
+          if (options.signal) {
+            options.signal.removeEventListener("abort", abortHandler);
+          }
+        };
+        inFlightRequests.set(url, promise.finally(cleanup));
+        promise.then((r) => {
+          batch.resolvers.forEach((res) => res(r.clone()));
+        }).catch((err) => {
+          batch.rejectors.forEach((rej) => rej(err));
+        });
+      }, BATCH_WINDOW_MS);
+      responsePromise = new Promise((resolve, reject) => {
+        batch.resolvers.push(resolve);
+        batch.rejectors.push(reject);
+      });
+    } else {
+      responsePromise = fetch(resolvedInput, fetchOptions);
+    }
+  }
+
+  let response${T(ts, "Response")};
+  try {
+    response = await responsePromise;
+  } catch (err) {
+    if (err instanceof TypeError) {
+      if (isRead) {
+${offlineReadCatchBlock}
+      }
+      // SW not controlling — fallback to client-side queue
+      if (!navigator.serviceWorker?.controller) {
+${offlineWriteFallbackBlock}
+      }
+    }
+    throw err;
+  }
+${autoInvalidateBlock}${auth401Block}
+  const fromCache = response.headers.get("X-SW-From-Cache") === "true";
+  const queued = response.headers.get("X-SW-Mutation-Queued") === "true";
+  return { response, fromCache, queued };
+  } finally {
+    if (!options.skipFetchCount) decrementFetchCount();
+  }
+}
+
+/** Fire-and-forget prefetch: warms the cache for a URL without blocking. Useful for route prefetching or link hover prefetching. */
+export function prefetchCache(input${T(ts, "RequestInfo")}, options${T(ts, "RequestInit & FetchWithCacheOptions")} = {})${R(ts, "void")}{
+  fetchWithCache(input, { ...options, skipFetchCount: true }).catch(() => {
+    // Prefetch failures are intentionally silent
+  });
+}
+`;
+}
+//# sourceMappingURL=fetch-wrapper.js.map

package/dist/runtime/fetch-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-wrapper.js","sourceRoot":"","sources":["../../src/runtime/fetch-wrapper.ts"],"names":[],"mappings":"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"}

package/dist/runtime/gql-wrapper.js

@@ -0,0 +1,135 @@
+import { T, R, G, AS } from "./utils.js";
+export function generateGqlWrapperCode(ctx, endpoint) {
+    const { ext, ts } = ctx;
+    const optionsInterface = ts
+        ? `
+export interface GqlOptions {
+  variables?: Record<string, unknown>;
+  tags?: string[];
+  auth?: boolean;
+  queueOffline?: boolean;
+  invalidate?: 'auto' | string[] | false;
+}
+`
+        : "";
+    return `/**
+ * Swoff GraphQL Wrapper
+ * Brings Swoff's caching, offline queue, and tag-based invalidation to GraphQL APIs.
+ * Hashes query + variables for deterministic cache keys and auto-generates tags
+ * from operation names. Built on top of fetchWithCache.
+ *
+ * Usage:
+ *   import { fetchWithGql, queryGql, mutateGql } from './swoff/gql-wrapper.${ext}';
+ *
+ *   // Query — cached with body-hash key
+ *   const { data } = await queryGql("{ todos { id title } }");
+ *
+ *   // Query with variables
+ *   const { data: todo } = await queryGql(
+ *     "query GetTodo($id: ID!) { todo(id: $id) { id title } }",
+ *     { id: "42" }
+ *   );
+ *
+ *   // Mutation — auto-invalidates related cache tags
+ *   const { data: created } = await mutateGql(
+ *     "mutation CreateTodo($title: String!) { createTodo(title: $title) { id } }",
+ *     { title: "New task" }
+ *   );
+ *
+ *   // Authenticated
+ *   const { data } = await queryGql("query Me { me { name } }", {}, { auth: true });
+ *
+ *   // Offline: mutations are auto-queued
+ *   const { data } = await mutateGql(
+ *     "mutation CreateTodo($title: String!) { createTodo(title: $title) { id } }",
+ *     { title: "Offline task" },
+ *     { queueOffline: true }
+ *   );
+ */
+
+import { fetchWithCache } from "../fetch/core.${ext}";
+import type { GqlResult } from "../swoff";
+${optionsInterface}
+/** Extract operation name from a GraphQL document. Returns null for anonymous queries (e.g. "{ todos { id } }"). */
+function getOperationName(query${T(ts, "string")})${T(ts, "string | null")}{
+  const match = query.match(/(query|mutation|subscription)\\s+(\\w+)/);
+  return match ? match[2] : null;
+}
+
+/** Determine if a GraphQL document is a query (read) vs mutation/subscription (write). */
+function isReadOperation(query${T(ts, "string")})${T(ts, "boolean")}{
+  const trimmed = query.trim();
+  if (trimmed.startsWith("mutation") || trimmed.startsWith("subscription")) return false;
+  return true;
+}
+
+/** Hash an object into a hex string for deterministic cache keying. Uses SHA-256 via SubtleCrypto. */
+async function bodyHash(obj${T(ts, "unknown")})${T(ts, "Promise<string>")}{
+  const json = JSON.stringify(obj);
+  const bytes = new TextEncoder().encode(json);
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
+}
+
+/** Generate cache-relevant tags from a GQL operation name. e.g. "getTodos" → ["todos"], "createTodo" → ["todos", "todo"]. */
+function tagsFromOpName(name${T(ts, "string | null")})${T(ts, "string[]")}{
+  if (!name) return [];
+  const stripped = name.replace(/^(get|fetch|list|all|query)/i, "").replace(/^(create|set|add|new|update|delete|remove)/i, "");
+  if (!stripped) return [name.toLowerCase()];
+  const tag = stripped.charAt(0).toLowerCase() + stripped.slice(1);
+  const plural = tag.replace(/s$/, "") + "s";
+  return [plural, tag];
+}
+
+/** Fetch a GraphQL endpoint with Swoff's caching, auth, offline queue, and auto-invalidation. Hashes query + variables for deterministic cache keys. */
+export async function fetchWithGql${G(ts, "T")}(
+  query${T(ts, "string")},
+  options${T(ts, "GqlOptions")} = {}
+)${R(ts, "Promise<GqlResult<T>>")}{
+  const isRead = isReadOperation(query);
+  const opName = getOperationName(query);
+  const variables = options.variables;
+  const hash = await bodyHash({ query, variables });
+  const tags = options.tags || tagsFromOpName(opName);
+
+  const { response, fromCache } = await fetchWithCache("${endpoint}", {
+    method: "POST",
+    body: JSON.stringify({ query, variables }),
+    headers: {
+      "Content-Type": "application/json",
+      "X-SW-Cache-Key": "gql:" + hash,
+    },
+    tags,
+    type: isRead ? "read" : "mutation",
+    auth: options.auth,
+    queueOffline: options.queueOffline,
+    invalidate: options.invalidate,
+  });
+
+  if (!response.ok) {
+    throw new Error("GraphQL request failed with status " + response.status);
+  }
+  const result = await response.json();
+  return { data: result.data${AS(ts, "T")}, fromCache };
+}
+
+/** Shorthand for GraphQL queries (type: "read"). Cached by default with body-hash key. */
+export async function queryGql${G(ts, "T")}(
+  query${T(ts, "string")},
+  variables${T(ts, "Record<string, unknown> | undefined")} = undefined,
+  options${T(ts, "GqlOptions")} = {}
+)${R(ts, "Promise<GqlResult<T>>")}{
+  return fetchWithGql${G(ts, "T")}(query, { ...options, variables });
+}
+
+/** Shorthand for GraphQL mutations (type: "mutation"). Auto-invalidates related cache tags. */
+export async function mutateGql${G(ts, "T")}(
+  mutation${T(ts, "string")},
+  variables${T(ts, "Record<string, unknown> | undefined")} = undefined,
+  options${T(ts, "GqlOptions")} = {}
+)${R(ts, "Promise<GqlResult<T>>")}{
+  return fetchWithGql${G(ts, "T")}(mutation, { ...options, variables });
+}
+`;
+}
+//# sourceMappingURL=gql-wrapper.js.map