@swoff/cli 0.3.7 → 0.3.8

package/dist/lib/shared/config-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../../../src/lib/shared/config-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../../../src/lib/shared/config-types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swoff/cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "description": "CLI for Swoff - Offline-first web apps made easy",
   "bin": {

package/templates/hooks/useCachedFetch.jsx

@@ -12,13 +12,23 @@ export function useCachedFetch(url, options = {}) {
 
   const refetch = useCallback(() => setRefetchCount((c) => c + 1), []);
 
+  const isEnabled = options.enabled !== false && url != null;
+
   useEffect(() => {
+    if (!isEnabled) {
+      setLoading(false);
+      return;
+    }
     let cancelled = false;
+    const controller = new AbortController();
     startTransition(() => setLoading(true));
 
     const doFetch = async () => {
       try {
-        const { response } = await fetchWithCache(url, optionsRef.current);
+        const { response } = await fetchWithCache(url, {
+          ...optionsRef.current,
+          signal: controller.signal,
+        });
         if (cancelled) return;
         if (response) {
           setData(await response.json());
@@ -27,6 +37,7 @@ export function useCachedFetch(url, options = {}) {
         }
         if (!cancelled) setError(null);
       } catch (err) {
+        if (!cancelled && err instanceof DOMException && err.name === "AbortError") return;
         if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
       } finally {
         if (!cancelled) setLoading(false);
@@ -34,10 +45,15 @@ export function useCachedFetch(url, options = {}) {
     };
 
     doFetch();
-    return () => { cancelled = true; };
-  }, [url, refetchCount]);
+    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;
@@ -49,7 +65,30 @@ export function useCachedFetch(url, options = {}) {
     };
     window.addEventListener("cache-invalidated", onInvalidated);
     return () => window.removeEventListener("cache-invalidated", onInvalidated);
-  }, [url]);
+  }, [url, isEnabled]);
+
+  // Auto-refetch on window focus
+  useEffect(() => {
+    if (!options.refetchOnWindowFocus || !isEnabled) return;
+    const onFocus = () => refetch();
+    window.addEventListener("focus", onFocus);
+    return () => window.removeEventListener("focus", onFocus);
+  }, [options.refetchOnWindowFocus, refetch, isEnabled]);
+
+  // Auto-refetch on reconnect
+  useEffect(() => {
+    if (!options.refetchOnReconnect || !isEnabled) return;
+    const onOnline = () => refetch();
+    window.addEventListener("online", onOnline);
+    return () => window.removeEventListener("online", onOnline);
+  }, [options.refetchOnReconnect, refetch, isEnabled]);
+
+  // Auto-refetch on interval
+  useEffect(() => {
+    if (!options.refetchInterval || options.refetchInterval <= 0 || !isEnabled) return;
+    const id = setInterval(refetch, options.refetchInterval * 1000);
+    return () => clearInterval(id);
+  }, [options.refetchInterval, refetch, isEnabled]);
 
   return { data, error, loading, refetch };
 }

package/templates/hooks/useCachedFetch.tsx

@@ -7,10 +7,16 @@ import {
 } from "react";
 import { fetchWithCache } from "../fetch-wrapper.ts";
 import { generateTags } from "../invalidation-tags.ts";
+import type { FetchWithCacheOptions } from "../fetch-wrapper.ts";
 
 export function useCachedFetch<T>(
-  url: string,
-  options: Parameters<typeof fetchWithCache>[1] = {},
+  url: string | null,
+  options: FetchWithCacheOptions & {
+    refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    refetchInterval?: number;
+    enabled?: boolean;
+  } = {},
 ) {
   const [data, setData] = useState<T | null>(null);
   const [error, setError] = useState<Error | null>(null);
@@ -23,13 +29,23 @@ export function useCachedFetch<T>(
 
   const refetch = useCallback(() => setRefetchCount((c) => c + 1), []);
 
+  const isEnabled = options.enabled !== false && url != null;
+
   useEffect(() => {
+    if (!isEnabled) {
+      setLoading(false);
+      return;
+    }
     let cancelled = false;
+    const controller = new AbortController();
     startTransition(() => setLoading(true));
 
     const doFetch = async () => {
       try {
-        const { response } = await fetchWithCache(url, optionsRef.current);
+        const { response } = await fetchWithCache(url, {
+          ...optionsRef.current,
+          signal: controller.signal,
+        });
         if (cancelled) return;
         if (response) {
           setData(await response.json());
@@ -38,6 +54,7 @@ export function useCachedFetch<T>(
         }
         if (!cancelled) setError(null);
       } catch (err) {
+        if (!cancelled && err instanceof DOMException && err.name === "AbortError") return;
         if (!cancelled)
           setError(err instanceof Error ? err : new Error(String(err)));
       } finally {
@@ -48,22 +65,48 @@ export function useCachedFetch<T>(
     doFetch();
     return () => {
       cancelled = true;
+      controller.abort();
     };
-  }, [url, refetchCount]);
+  }, [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);
+      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]);
+  }, [url, isEnabled]);
+
+  // Auto-refetch on window focus
+  useEffect(() => {
+    if (!options.refetchOnWindowFocus || !isEnabled) return;
+    const onFocus = () => refetch();
+    window.addEventListener("focus", onFocus);
+    return () => window.removeEventListener("focus", onFocus);
+  }, [options.refetchOnWindowFocus, refetch, isEnabled]);
+
+  // Auto-refetch on reconnect
+  useEffect(() => {
+    if (!options.refetchOnReconnect || !isEnabled) return;
+    const onOnline = () => refetch();
+    window.addEventListener("online", onOnline);
+    return () => window.removeEventListener("online", onOnline);
+  }, [options.refetchOnReconnect, refetch, isEnabled]);
+
+  // Auto-refetch on interval
+  useEffect(() => {
+    if (!options.refetchInterval || options.refetchInterval <= 0 || !isEnabled) return;
+    const id = setInterval(refetch, options.refetchInterval * 1000);
+    return () => clearInterval(id);
+  }, [options.refetchInterval, refetch, isEnabled]);
 
   return { data, error, loading, refetch };
 }

package/templates/hooks/useMutation.jsx

@@ -0,0 +1,76 @@
+import { useEffect, useState, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch-wrapper.js";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../mutation-state.js";
+
+export function useMutation(options = {}) {
+  const [state, setState] = useState({
+    data: null,
+    error: null,
+    isLoading: false,
+    isError: false,
+    isSuccess: false,
+  });
+
+  const optionsRef = useRef(options);
+
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  const mutate = useCallback(async (url, fetchOptions = {}) => {
+    const mutationId = "mut-" + crypto.randomUUID();
+    trackMutation(mutationId, "pending");
+    setState({
+      data: null,
+      error: null,
+      isLoading: true,
+      isError: false,
+      isSuccess: false,
+    });
+
+    try {
+      const { response } = await fetchWithCache(url, fetchOptions);
+      const data = await response.json();
+      resolveMutation(mutationId, data);
+      setState({
+        data,
+        error: null,
+        isLoading: false,
+        isError: false,
+        isSuccess: true,
+      });
+      optionsRef.current.onSuccess?.(data);
+      optionsRef.current.onSettled?.();
+      return data;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      rejectMutation(mutationId, error);
+      setState({
+        data: null,
+        error,
+        isLoading: false,
+        isError: true,
+        isSuccess: false,
+      });
+      optionsRef.current.onError?.(error);
+      optionsRef.current.onSettled?.();
+      return null;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    setState({
+      data: null,
+      error: null,
+      isLoading: false,
+      isError: false,
+      isSuccess: false,
+    });
+  }, []);
+
+  return { ...state, mutate, reset };
+}

package/templates/hooks/useMutation.tsx

@@ -0,0 +1,97 @@
+import { useEffect, useState, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch-wrapper.ts";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../mutation-state.ts";
+import type { FetchWithCacheOptions } from "../fetch-wrapper.ts";
+
+export interface UseMutationOptions<TData> {
+  onSuccess?: (data: TData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: () => void;
+}
+
+export function useMutation<TData = unknown>(
+  options: UseMutationOptions<TData> = {},
+) {
+  const [state, setState] = useState<{
+    data: TData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+  }>({
+    data: null,
+    error: null,
+    isLoading: false,
+    isError: false,
+    isSuccess: false,
+  });
+
+  const optionsRef = useRef(options);
+
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  const mutate = useCallback(
+    async (
+      url: string,
+      fetchOptions: FetchWithCacheOptions = {},
+    ): Promise<TData | null> => {
+      const mutationId = "mut-" + crypto.randomUUID();
+      trackMutation(mutationId, "pending");
+      setState({
+        data: null,
+        error: null,
+        isLoading: true,
+        isError: false,
+        isSuccess: false,
+      });
+
+      try {
+        const { response } = await fetchWithCache<TData>(url, fetchOptions);
+        const data: TData = await response.json();
+        resolveMutation(mutationId, data);
+        setState({
+          data,
+          error: null,
+          isLoading: false,
+          isError: false,
+          isSuccess: true,
+        });
+        optionsRef.current.onSuccess?.(data);
+        optionsRef.current.onSettled?.();
+        return data;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        rejectMutation(mutationId, error);
+        setState({
+          data: null,
+          error,
+          isLoading: false,
+          isError: true,
+          isSuccess: false,
+        });
+        optionsRef.current.onError?.(error);
+        optionsRef.current.onSettled?.();
+        return null;
+      }
+    },
+    [],
+  );
+
+  const reset = useCallback(() => {
+    setState({
+      data: null,
+      error: null,
+      isLoading: false,
+      isError: false,
+      isSuccess: false,
+    });
+  }, []);
+
+  return { ...state, mutate, reset };
+}

package/templates/hooks/useMutationQueue.jsx

@@ -1,25 +1,33 @@
-import { useState, useEffect } from "react";
-import { getPendingCount } from "../mutation-queue.js";
+import { useState, useEffect, useCallback } from "react";
+import { getPendingCount, getQueueItems } from "../mutation-queue.js";
 
 export function useMutationQueue() {
   const [state, setState] = useState({
     pending: 0,
+    items: [],
     lastSync: null,
   });
 
+  const refresh = useCallback(async () => {
+    const [count, items] = await Promise.all([
+      getPendingCount(),
+      getQueueItems(),
+    ]);
+    setState((s) => ({ ...s, pending: count, items }));
+  }, []);
+
   useEffect(() => {
-    getPendingCount().then((count) => setState((s) => ({ ...s, pending: count })));
+    refresh();
 
     const onSync = (e) => {
-      getPendingCount().then((count) => {
-        setState({
-          pending: count,
-          lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
-        });
-      });
+      refresh();
+      setState((s) => ({
+        ...s,
+        lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
+      }));
     };
     const onChange = () => {
-      getPendingCount().then((count) => setState((s) => ({ ...s, pending: count })));
+      refresh();
     };
 
     window.addEventListener("mutation-sync-complete", onSync);
@@ -28,7 +36,7 @@ export function useMutationQueue() {
       window.removeEventListener("mutation-sync-complete", onSync);
       window.removeEventListener("mutation-queue-changed", onChange);
     };
-  }, []);
+  }, [refresh]);
 
   return state;
 }

package/templates/hooks/useMutationQueue.tsx

@@ -1,25 +1,40 @@
-import { useState, useEffect } from "react";
-import { getPendingCount } from "../mutation-queue.ts";
+import { useState, useEffect, useCallback } from "react";
+import { getPendingCount, getQueueItems } from "../mutation-queue.ts";
+import type { MutationQueueItem } from "../swoff.d.ts";
+
+export interface MutationQueueState {
+  pending: number;
+  items: MutationQueueItem[];
+  lastSync: { succeeded: number; failed: number } | null;
+}
 
 export function useMutationQueue() {
-  const [state, setState] = useState<{
-    pending: number;
-    lastSync: { succeeded: number; failed: number } | null;
-  }>({ pending: 0, lastSync: null });
+  const [state, setState] = useState<MutationQueueState>({
+    pending: 0,
+    items: [],
+    lastSync: null,
+  });
+
+  const refresh = useCallback(async () => {
+    const [count, items] = await Promise.all([
+      getPendingCount(),
+      getQueueItems(),
+    ]);
+    setState((s) => ({ ...s, pending: count, items }));
+  }, []);
 
   useEffect(() => {
-    getPendingCount().then((count: number) => setState((s) => ({ ...s, pending: count })));
+    refresh();
 
     const onSync = (e: CustomEvent) => {
-      getPendingCount().then((count: number) => {
-        setState({
-          pending: count,
-          lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
-        });
-      });
+      refresh();
+      setState((s) => ({
+        ...s,
+        lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
+      }));
     };
     const onChange = () => {
-      getPendingCount().then((count: number) => setState((s) => ({ ...s, pending: count })));
+      refresh();
     };
 
     window.addEventListener("mutation-sync-complete", onSync);
@@ -28,7 +43,7 @@ export function useMutationQueue() {
       window.removeEventListener("mutation-sync-complete", onSync);
       window.removeEventListener("mutation-queue-changed", onChange);
     };
-  }, []);
+  }, [refresh]);
 
   return state;
 }

package/templates/hooks/useMutationState.jsx

@@ -0,0 +1,27 @@
+import { useState, useEffect } from "react";
+import { getMutationState, onMutationStateChange } from "../mutation-state.js";
+
+export function useMutationState(id) {
+  const [state, setState] = useState(() =>
+    id ? getMutationState(id) ?? null : null,
+  );
+
+  useEffect(() => {
+    if (!id) {
+      setState(null);
+      return;
+    }
+
+    setState(getMutationState(id) ?? null);
+
+    const unsub = onMutationStateChange((updated) => {
+      if (updated.id === id) {
+        setState(updated);
+      }
+    });
+
+    return unsub;
+  }, [id]);
+
+  return state;
+}

package/templates/hooks/useMutationState.tsx

@@ -0,0 +1,41 @@
+import { useState, useEffect } from "react";
+import {
+  getMutationState,
+  onMutationStateChange,
+} from "../mutation-state.ts";
+import type { MutationState } from "../mutation-state.ts";
+
+/**
+ * Hook that subscribes to a specific mutation's state changes.
+ * Useful for showing per-mutation loading spinners, error states, etc.
+ *
+ * Usage:
+ *   const mutation = useMutationState(mutationId);
+ *   if (mutation?.status === "error") { ... }
+ */
+export function useMutationState(id: string | null): MutationState | null {
+  const [state, setState] = useState<MutationState | null>(() =>
+    id ? getMutationState(id) ?? null : null,
+  );
+
+  useEffect(() => {
+    if (!id) {
+      setState(null);
+      return;
+    }
+
+    // Initial state
+    setState(getMutationState(id) ?? null);
+
+    // Subscribe to changes
+    const unsub = onMutationStateChange((updated) => {
+      if (updated.id === id) {
+        setState(updated);
+      }
+    });
+
+    return unsub;
+  }, [id]);
+
+  return state;
+}

package/templates/hooks/usePrefetch.jsx

@@ -0,0 +1,10 @@
+import { useCallback } from "react";
+import { prefetchCache } from "../fetch-wrapper.js";
+
+export function usePrefetch() {
+  const prefetch = useCallback((url, options) => {
+    prefetchCache(url, options);
+  }, []);
+
+  return prefetch;
+}

package/templates/hooks/usePrefetch.tsx

@@ -0,0 +1,25 @@
+import { useCallback } from "react";
+import { prefetchCache } from "../fetch-wrapper.ts";
+import type { FetchWithCacheOptions } from "../fetch-wrapper.ts";
+
+/**
+ * Hook that returns a stable prefetch callback for warming the SW cache.
+ * Useful for route-level prefetching, link hover prefetching, etc.
+ *
+ * Usage:
+ *   const prefetch = usePrefetch();
+ *   <Link onMouseEnter={() => prefetch("/api/todos")} to="/todos" />
+ */
+export function usePrefetch(): (
+  url: string,
+  options?: FetchWithCacheOptions,
+) => void {
+  const prefetch = useCallback(
+    (url: string, options?: FetchWithCacheOptions) => {
+      prefetchCache(url, options);
+    },
+    [],
+  );
+
+  return prefetch;
+}