@swoff/cli 0.3.9 → 0.3.10

package/templates/react/useAuth.jsx

@@ -0,0 +1,106 @@
+import { useState, useEffect, useCallback } from "react";
+import { getAuthState } from "../auth/state.js";
+import { setAuth, clearAuth, ensureValidAuth } from "../auth/store.js";
+
+/**
+ * Reactive auth state with actions: setAuth, clearAuth, ensureValid.
+ *
+ * Usage:
+ *   const { authenticated, user, online, isLoading, error, setAuth, clearAuth, ensureValid } = useAuth();
+ *
+ *   // Login — call setAuth with the response from your login endpoint:
+ *   const res = await fetch("/api/login", { method: "POST", body });
+ *   const data = await res.json();
+ *   await setAuth({ token: data.token, user: data.user, expiresAt: data.expiresAt });
+ *
+ *   // Logout:
+ *   await clearAuth();
+ *
+ *   // Silent session restore:
+ *   const auth = await ensureValid();
+ */
+export function useAuth() {
+  const [state, setState] = useState(() => ({
+    authenticated: false,
+    user: null,
+    online: typeof navigator !== "undefined" ? navigator.onLine : true,
+    isLoading: false,
+    error: null,
+  }));
+
+  const refreshState = useCallback(async () => {
+    try {
+      const authState = await getAuthState();
+      setState((s) => ({ ...s, ...authState, error: null }));
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  useEffect(() => {
+    refreshState();
+
+    const onOnline = () => setState((s) => ({ ...s, online: true }));
+    const onOffline = () => setState((s) => ({ ...s, online: false }));
+    const onAuthChange = () => refreshState();
+
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    window.addEventListener("sw-auth-state-change", onAuthChange);
+
+    return () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+      window.removeEventListener("sw-auth-state-change", onAuthChange);
+    };
+  }, [refreshState]);
+
+  const doSetAuth = useCallback(async (authData) => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      await setAuth(authData);
+      await refreshState();
+    } catch (err) {
+      setState((s) => ({ ...s, error: err instanceof Error ? err : new Error(String(err)) }));
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  const doClearAuth = useCallback(async () => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      await clearAuth();
+      await refreshState();
+    } catch (err) {
+      setState((s) => ({ ...s, error: err instanceof Error ? err : new Error(String(err)) }));
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  const doEnsureValid = useCallback(async () => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      const auth = await ensureValidAuth();
+      await refreshState();
+      return auth;
+    } catch (err) {
+      setState((s) => ({ ...s, error: err instanceof Error ? err : new Error(String(err)) }));
+      return null;
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  return {
+    authenticated: state.authenticated,
+    user: state.user,
+    online: state.online,
+    isLoading: state.isLoading,
+    error: state.error,
+    setAuth: doSetAuth,
+    clearAuth: doClearAuth,
+    ensureValid: doEnsureValid,
+  };
+}

package/templates/react/useAuth.tsx

@@ -0,0 +1,118 @@
+import { useState, useEffect, useCallback } from "react";
+import { getAuthState } from "../auth/state.ts";
+import { setAuth, clearAuth, ensureValidAuth } from "../auth/store.ts";
+import type { AuthData } from "../auth/store.ts";
+
+/**
+ * Reactive auth state with actions: setAuth, clearAuth, ensureValid.
+ *
+ * Usage:
+ *   const { authenticated, user, online, isLoading, error, setAuth, clearAuth, ensureValid } = useAuth();
+ *
+ *   // Login — call setAuth with the response from your login endpoint:
+ *   const res = await fetch("/api/login", { method: "POST", body });
+ *   const data = await res.json();
+ *   await setAuth({ token: data.token, user: data.user, expiresAt: data.expiresAt });
+ *
+ *   // Logout — clears tokens from memory and user cache from IndexedDB:
+ *   await clearAuth();
+ *
+ *   // Silently refresh the session (page restore) — wraps ensureValidAuth():
+ *   const auth = await ensureValid();
+ *
+ * Auth behavior by type:
+ *   - Cookie auth: credentials ("include") sent automatically by the browser.
+ *     setAuth still caches user data for offline display.
+ *   - Bearer auth: token lives in memory only. clearAuth wipes it.
+ *     ensureValid tries a silent refresh via refreshSession() in auth/user.ts.
+ *
+ * @returns {{ authenticated, user, online, isLoading, error, setAuth, clearAuth, ensureValid }}
+ */
+export function useAuth() {
+  const [state, setState] = useState(() => ({
+    authenticated: false,
+    user: null as Record<string, unknown> | null,
+    online: typeof navigator !== "undefined" ? navigator.onLine : true,
+    isLoading: false,
+    error: null as Error | null,
+  }));
+
+  const refreshState = useCallback(async () => {
+    try {
+      const authState = await getAuthState();
+      setState((s) => ({ ...s, ...authState, error: null }));
+    } catch {
+      // ignore — auth not initialized
+    }
+  }, []);
+
+  useEffect(() => {
+    refreshState();
+
+    const onOnline = () => setState((s) => ({ ...s, online: true }));
+    const onOffline = () => setState((s) => ({ ...s, online: false }));
+    const onAuthChange = () => refreshState();
+
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    window.addEventListener("sw-auth-state-change", onAuthChange);
+
+    return () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+      window.removeEventListener("sw-auth-state-change", onAuthChange);
+    };
+  }, [refreshState]);
+
+  const doSetAuth = useCallback(async (authData: AuthData) => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      await setAuth(authData);
+      await refreshState();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState((s) => ({ ...s, error }));
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  const doClearAuth = useCallback(async () => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      await clearAuth();
+      await refreshState();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState((s) => ({ ...s, error }));
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  const doEnsureValid = useCallback(async (): Promise<AuthData | null> => {
+    setState((s) => ({ ...s, isLoading: true, error: null }));
+    try {
+      const auth = await ensureValidAuth();
+      await refreshState();
+      return auth;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState((s) => ({ ...s, error }));
+      return null;
+    } finally {
+      setState((s) => ({ ...s, isLoading: false }));
+    }
+  }, [refreshState]);
+
+  return {
+    authenticated: state.authenticated,
+    user: state.user,
+    online: state.online,
+    isLoading: state.isLoading,
+    error: state.error,
+    setAuth: doSetAuth,
+    clearAuth: doClearAuth,
+    ensureValid: doEnsureValid,
+  };
+}

package/templates/{hooks → react}/useBackgroundSync.jsx

@@ -1,12 +1,14 @@
 import { useState, useEffect, useCallback } from "react";
-import { retrySync } from "../background-sync.js";
+import { retrySync } from "../offline/sync.js";
 
 export function useBackgroundSync() {
-  const [state, setState] = useState({
-    supported: "serviceWorker" in navigator && "SyncManager" in window,
+  const [state, setState] = useState(() => ({
+    supported: typeof window !== "undefined" && typeof navigator !== "undefined"
+      ? "serviceWorker" in navigator && "SyncManager" in window
+      : false,
     registered: false,
     lastSync: null,
-  });
+  }));
 
   useEffect(() => {
     const onSyncComplete = (e) => {

package/templates/{hooks → react}/useBackgroundSync.tsx

@@ -1,12 +1,14 @@
 import { useState, useEffect, useCallback } from "react";
-import { retrySync } from "../background-sync.ts";
+import { retrySync } from "../offline/sync.ts";
 
 export function useBackgroundSync() {
-  const [state, setState] = useState({
-    supported: "serviceWorker" in navigator && "SyncManager" in window,
+  const [state, setState] = useState(() => ({
+    supported: typeof window !== "undefined" && typeof navigator !== "undefined"
+      ? "serviceWorker" in navigator && "SyncManager" in window
+      : false,
     registered: false,
     lastSync: null as { succeeded: number; failed: number } | null,
-  });
+  }));
 
   useEffect(() => {
     const onSyncComplete = (e: CustomEvent) => {

package/templates/{hooks → react}/useCacheInvalidation.jsx

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
-import { invalidateByTag, invalidateByTags } from "../cache.js";
-import { invalidateUrl } from "../invalidation-tags.js";
+import { invalidateByTag, invalidateByTags } from "../cache/index.js";
+import { invalidateUrl } from "../cache/tags.js";
 
 export function useCacheInvalidation() {
   const invalidateTag = useCallback(async (tag) => {

package/templates/react/useCacheInvalidation.tsx

@@ -0,0 +1,52 @@
+import { useCallback } from "react";
+import { invalidateByTag, invalidateByTags } from "../cache/index.ts";
+import { invalidateUrl } from "../cache/tags.ts";
+
+/**
+ * Hook exposing cache invalidation functions for manual control.
+ *
+ * Useful when you need to invalidate the cache after a mutation that wasn't
+ * automatically handled (e.g., a third-party API, a non-fetchWithCache call).
+ *
+ * Invalidation triggers:
+ *   - The service worker refetches cached URLs for the invalidated tags
+ *   - Active useCachedFetch hooks for those URLs auto-refetch
+ *   - The "cache-invalidated" CustomEvent is dispatched on window
+ *
+ * Usage:
+ *   const { invalidateByTag, invalidateByTags, invalidateUrl } = useCacheInvalidation();
+ *
+ *   // Invalidate by a single tag
+ *   await invalidateByTag("todos");
+ *
+ *   // Invalidate by multiple tags at once
+ *   await invalidateByTags(["todos", "projects"]);
+ *
+ *   // Invalidate a specific URL
+ *   await invalidateUrl("/api/todos");
+ *
+ * Auth behavior:
+ *   Invalidation is auth-agnostic. If the refetched URL requires auth headers,
+ *   the service worker's refetch (from tag-management.ts) will replay the
+ *   original request's method and body. For GET requests, no auth headers are
+ *   sent during invalidation-based refetch — this is correct for cookie auth
+ *   (browser sends cookies automatically), but for bearer auth the user
+ *   endpoint fetch is handled by refreshSession/fetchCurrentUser in auth/user.ts.
+ *
+ * @returns {{ invalidateByTag, invalidateByTags, invalidateUrl }}
+ */
+export function useCacheInvalidation() {
+  const invalidateTag = useCallback(async (tag: string) => {
+    await invalidateByTag(tag);
+  }, []);
+
+  const invalidateTags = useCallback(async (tags: string[]) => {
+    await invalidateByTags(tags);
+  }, []);
+
+  const invalidateCacheUrl = useCallback(async (url: string) => {
+    await invalidateUrl(url);
+  }, []);
+
+  return { invalidateByTag: invalidateTag, invalidateByTags: invalidateTags, invalidateUrl: invalidateCacheUrl };
+}

package/templates/react/useCachedFetch.jsx

@@ -0,0 +1,140 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch/core.js";
+import { generateTags } from "../cache/tags.js";
+
+/**
+ * Fetch and cache data with automatic invalidation, revalidation, and offline support.
+ *
+ * Usage:
+ *   const { data, error, loading, refetch } = useCachedFetch("/api/todos");
+ *
+ *   // Select/transform data
+ *   const { data: names } = useCachedFetch("/api/users", {
+ *     select: (users) => users.map(u => u.name),
+ *   });
+ *
+ *   // Keep previous data while fetching next page
+ *   const { data } = useCachedFetch(`/api/items?page=${page}`, {
+ *     keepPreviousData: true,
+ *   });
+ *
+ *   // Retry on failure
+ *   const { data } = useCachedFetch("/api/todos", { retry: 3 });
+ *
+ *   // Placeholder data while loading
+ *   const { data } = useCachedFetch("/api/todos", {
+ *     placeholderData: { items: [] },
+ *   });
+ */
+export function useCachedFetch(url, options = {}) {
+  const {
+    select,
+    retry: retryOpt,
+    placeholderData,
+    onSuccess,
+    onError,
+    ...fetchOptions
+  } = options;
+
+  const [data, setData] = useState(placeholderData ?? null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(
+    () => url != null && options.enabled !== false,
+  );
+  const [refetchCount, setRefetchCount] = useState(0);
+
+  const cachedRef = useRef(placeholderData ?? null);
+  const prevSelectedRef = useRef(null);
+  const onSuccessRef = useRef(onSuccess);
+  const onErrorRef = useRef(onError);
+
+  useEffect(() => {
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
+  });
+
+  const refetch = useCallback(() => setRefetchCount((c) => c + 1), []);
+
+  const isEnabled = options.enabled !== false && url != null;
+
+  useEffect(() => {
+    if (!isEnabled) return;
+
+    let cancelled = false;
+    let retriesLeft =
+      retryOpt === true
+        ? Infinity
+        : typeof retryOpt === "number"
+          ? retryOpt
+          : 0;
+    const controller = new AbortController();
+
+    const doFetch = async () => {
+      setLoading(true);
+      try {
+        const { response } = await fetchWithCache(url, {
+          ...fetchOptions,
+          signal: controller.signal,
+        });
+        if (cancelled) return;
+        let selected = null;
+        if (response) {
+          const raw = await response.json();
+          selected = select ? select(raw) : raw;
+          setData(selected);
+          cachedRef.current = selected;
+          prevSelectedRef.current = selected;
+          if (!cancelled) onSuccessRef.current?.(selected);
+        } else {
+          setData(null);
+          cachedRef.current = null;
+          prevSelectedRef.current = null;
+        }
+        if (!cancelled) setError(null);
+      } catch (err) {
+        if (
+          !cancelled &&
+          err instanceof DOMException &&
+          err.name === "AbortError"
+        )
+          return;
+        if (!cancelled && retriesLeft > 0) {
+          retriesLeft--;
+          await new Promise((r) => setTimeout(r, 1000));
+          return doFetch();
+        }
+        if (!cancelled) {
+          const e = err instanceof Error ? err : new Error(String(err));
+          setError(e);
+          onErrorRef.current?.(e);
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+
+    doFetch();
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [url, refetchCount, isEnabled]);
+
+  // Auto-refetch on cache invalidation
+  useEffect(() => {
+    if (!isEnabled) return;
+    const onInvalidated = (e) => {
+      const detail = e.detail;
+      const tags = detail?.tags;
+      if (!tags || !Array.isArray(tags)) return;
+      const urlTags = generateTags(url);
+      if (tags.some((t) => urlTags.includes(t))) {
+        setRefetchCount((c) => c + 1);
+      }
+    };
+    window.addEventListener("cache-invalidated", onInvalidated);
+    return () => window.removeEventListener("cache-invalidated", onInvalidated);
+  }, [url, isEnabled]);
+
+  return { data, error, loading, refetch };
+}

package/templates/react/useCachedFetch.tsx

@@ -0,0 +1,160 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch/core.ts";
+import { generateTags } from "../cache/tags.ts";
+import type { FetchWithCacheOptions } from "../fetch/core.ts";
+
+/**
+ * Fetch and cache data with automatic invalidation, revalidation, and offline support.
+ *
+ * Usage:
+ *   const { data, error, loading, refetch } = useCachedFetch<MyType>("/api/todos");
+ *
+ *   // Select/transform data — skips re-render if selected value hasn't changed
+ *   const { data: names } = useCachedFetch("/api/users", {
+ *     select: (users) => users.map(u => u.name),
+ *   });
+ *
+ *   // Keep previous data while fetching the next page
+ *   const { data } = useCachedFetch(`/api/items?page=${page}`, {
+ *     keepPreviousData: true,
+ *   });
+ *
+ *   // Retry on failure (default 0 retries)
+ *   const { data } = useCachedFetch("/api/todos", { retry: 3 });
+ *
+ *   // Placeholder data while loading for the first time
+ *   const { data } = useCachedFetch("/api/todos", {
+ *     placeholderData: { items: [] },
+ *   });
+ *
+ *   // Callbacks on success/error
+ *   const { data, refetch } = useCachedFetch("/api/todos", {
+ *     onSuccess: (data) => console.log("Loaded", data),
+ *   });
+ *
+ * @param url - URL to fetch. Pass null to skip fetching.
+ * @param options - Fetch options plus: select, keepPreviousData, retry, placeholderData, onSuccess, onError
+ */
+export function useCachedFetch<T = unknown, R = T>(
+  url: string | null,
+  options: FetchWithCacheOptions & {
+    enabled?: boolean;
+    select?: (data: T) => R;
+    keepPreviousData?: boolean;
+    retry?: number | boolean;
+    placeholderData?: R;
+    onSuccess?: (data: R) => void;
+    onError?: (error: Error) => void;
+  } = {},
+) {
+  const {
+    select,
+    retry: retryOpt,
+    placeholderData,
+    onSuccess,
+    onError,
+    ...fetchOptions
+  } = options;
+
+  const [data, setData] = useState<R | null>(placeholderData ?? null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(
+    () => url != null && options.enabled !== false,
+  );
+  const [refetchCount, setRefetchCount] = useState(0);
+
+  const cachedRef = useRef<R | null>(placeholderData ?? null);
+  const prevSelectedRef = useRef<R | null>(null);
+  const onSuccessRef = useRef(onSuccess);
+  const onErrorRef = useRef(onError);
+
+  useEffect(() => {
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
+  });
+
+  const refetch = useCallback(() => setRefetchCount((c) => c + 1), []);
+
+  const isEnabled = options.enabled !== false && url != null;
+
+  useEffect(() => {
+    if (!isEnabled) return;
+
+    let cancelled = false;
+    let retriesLeft: number =
+      retryOpt === true
+        ? Infinity
+        : typeof retryOpt === "number"
+          ? retryOpt
+          : 0;
+    const controller = new AbortController();
+
+    const doFetch = async (): Promise<void> => {
+      setLoading(true);
+      try {
+        const { response } = await fetchWithCache(url, {
+          ...fetchOptions,
+          signal: controller.signal,
+        });
+        if (cancelled) return;
+        let selected: R | null = null;
+        if (response) {
+          const raw: T = await response.json();
+          selected = select ? select(raw) : (raw as unknown as R);
+          setData(selected);
+          cachedRef.current = selected;
+          prevSelectedRef.current = selected;
+          if (!cancelled) onSuccessRef.current?.(selected);
+        } else {
+          setData(null);
+          cachedRef.current = null;
+          prevSelectedRef.current = null;
+        }
+        if (!cancelled) setError(null);
+      } catch (err) {
+        if (
+          !cancelled &&
+          err instanceof DOMException &&
+          err.name === "AbortError"
+        )
+          return;
+        if (!cancelled && retriesLeft > 0) {
+          retriesLeft--;
+          await new Promise((r) => setTimeout(r, 1000));
+          return doFetch();
+        }
+        if (!cancelled) {
+          const e = err instanceof Error ? err : new Error(String(err));
+          setError(e);
+          onErrorRef.current?.(e);
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+
+    doFetch();
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [url, refetchCount, isEnabled]);
+
+  // Auto-refetch on cache invalidation
+  useEffect(() => {
+    if (!isEnabled) return;
+    const onInvalidated = (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      const tags = detail?.tags;
+      if (!tags || !Array.isArray(tags)) return;
+      const urlTags = generateTags(url!);
+      if (tags.some((t: string) => urlTags.includes(t))) {
+        setRefetchCount((c) => c + 1);
+      }
+    };
+    window.addEventListener("cache-invalidated", onInvalidated);
+    return () => window.removeEventListener("cache-invalidated", onInvalidated);
+  }, [url, isEnabled]);
+
+  return { data, error, loading, refetch };
+}

package/templates/react/useIsFetching.jsx

@@ -0,0 +1,32 @@
+import { useState, useEffect } from "react";
+import { getFetchCount } from "../fetch/state";
+
+/**
+ * Hook that returns true when any swoff fetch or mutation is in-flight.
+ * Uses a global counter incremented/decremented by fetchWithCache.
+ *
+ * Usage:
+ *   const isFetching = useIsFetching();
+ *
+ *   return (
+ *     <>
+ *       {isFetching && <Spinner />}
+ *       <MainContent />
+ *     </>
+ *   );
+ */
+export function useIsFetching() {
+  const [isFetching, setIsFetching] = useState(() => getFetchCount() > 0);
+
+  useEffect(() => {
+    const onChange = (e) => {
+      setIsFetching(e.detail.count > 0);
+    };
+    window.addEventListener("fetch-count-changed", onChange);
+    return () => {
+      window.removeEventListener("fetch-count-changed", onChange);
+    };
+  }, []);
+
+  return isFetching;
+}

package/templates/react/useIsFetching.tsx

@@ -0,0 +1,32 @@
+import { useState, useEffect } from "react";
+import { getFetchCount } from "../fetch/state";
+
+/**
+ * Hook that returns true when any swoff fetch or mutation is in-flight.
+ * Uses a global counter incremented/decremented by fetchWithCache.
+ *
+ * Usage:
+ *   const isFetching = useIsFetching();
+ *
+ *   return (
+ *     <>
+ *       {isFetching && <Spinner />}
+ *       <MainContent />
+ *     </>
+ *   );
+ */
+export function useIsFetching(): boolean {
+  const [isFetching, setIsFetching] = useState(() => getFetchCount() > 0);
+
+  useEffect(() => {
+    const onChange = (e: CustomEvent<{ count: number }>) => {
+      setIsFetching(e.detail.count > 0);
+    };
+    window.addEventListener("fetch-count-changed", onChange as EventListener);
+    return () => {
+      window.removeEventListener("fetch-count-changed", onChange as EventListener);
+    };
+  }, []);
+
+  return isFetching;
+}