@swoff/cli 0.3.8 → 0.3.10

package/templates/react/useMutation.jsx

@@ -0,0 +1,141 @@
+import { useState, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch/core.js";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../offline/state.js";
+
+/**
+ * Hook for mutations (POST, PUT, PATCH, DELETE) with auto-invalidation, offline queuing,
+ * optimistic updates, and dual-level callbacks.
+ *
+ * Usage:
+ *   const { mutate, isLoading, error, data } = useMutation("/api/todos", {
+ *     method: "POST",
+ *     onSuccess: (data) => navigate(`/item/${data.id}`),
+ *   });
+ *
+ *   // Called multiple times — all share one loading/error state:
+ *   await mutate({ title: "hello" });
+ *   await mutate({ title: "world" }, {
+ *     onSuccess: (data) => console.log(data),
+ *   });
+ *
+ *   // Optimistic update with rollback:
+ *   const { mutate } = useMutation("/api/todos", {
+ *     method: "POST",
+ *     onMutate: () => { /* set optimistic state */ },
+ *     onError: () => { /* rollback */ },
+ *   });
+ */
+export function useMutation(url, options = {}) {
+  const [state, setState] = useState({
+    data: null,
+    error: null,
+    isLoading: false,
+    isError: false,
+    isSuccess: false,
+  });
+
+  const [mutationId, setMutationId] = useState(null);
+  const optionsRef = useRef(options);
+  const urlRef = useRef(url);
+  const inFlightKeys = useRef(new Set());
+
+  urlRef.current = url;
+
+  const mutate = useCallback(async (body, callbacks) => {
+    const key = optionsRef.current.mutationKey;
+    if (key && inFlightKeys.current.has(key)) return null;
+    if (key) inFlightKeys.current.add(key);
+
+    let retriesLeft = optionsRef.current.retry === true
+      ? Infinity
+      : (optionsRef.current.retry ?? 0);
+
+    const mid = "mut-" + crypto.randomUUID();
+    setMutationId(mid);
+    trackMutation(mid, "pending");
+    setState({
+      data: null,
+      error: null,
+      isLoading: true,
+      isError: false,
+      isSuccess: false,
+    });
+
+    optionsRef.current.onMutate?.();
+
+    const attempt = async () => {
+      try {
+        const fetchOptions = { ...optionsRef.current, body };
+        const { response, queued } = await fetchWithCache(urlRef.current, fetchOptions);
+        if (queued) {
+          resolveMutation(mid, null);
+          setState({
+            data: null,
+            error: null,
+            isLoading: false,
+            isError: false,
+            isSuccess: false,
+          });
+          optionsRef.current.onSettled?.();
+          callbacks?.onSettled?.();
+          if (key) inFlightKeys.current.delete(key);
+          return null;
+        }
+        const data = await response.json();
+        resolveMutation(mid, data);
+        setState({
+          data,
+          error: null,
+          isLoading: false,
+          isError: false,
+          isSuccess: true,
+        });
+        optionsRef.current.onSuccess?.(data);
+        callbacks?.onSuccess?.(data);
+        optionsRef.current.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.current.delete(key);
+        return data;
+      } catch (err) {
+        if (retriesLeft > 0) {
+          retriesLeft--;
+          await new Promise((r) => setTimeout(r, 1000));
+          return attempt();
+        }
+        const error = err instanceof Error ? err : new Error(String(err));
+        rejectMutation(mid, error);
+        setState({
+          data: null,
+          error,
+          isLoading: false,
+          isError: true,
+          isSuccess: false,
+        });
+        optionsRef.current.onError?.(error);
+        callbacks?.onError?.(error);
+        optionsRef.current.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.current.delete(key);
+        return null;
+      }
+    };
+
+    return attempt();
+  }, []);
+
+  const reset = useCallback(() => {
+    setState({
+      data: null,
+      error: null,
+      isLoading: false,
+      isError: false,
+      isSuccess: false,
+    });
+  }, []);
+
+  return { ...state, mutate, reset, mutationId };
+}

package/templates/react/useMutation.tsx

@@ -0,0 +1,180 @@
+import { useState, useCallback, useRef } from "react";
+import { fetchWithCache } from "../fetch/core.ts";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../offline/state.ts";
+import type { FetchWithCacheOptions } from "../fetch/core.ts";
+
+export interface MutateCallbacks<TData> {
+  onSuccess?: (data: TData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: () => void;
+}
+
+export interface UseMutationOptions<TData> extends FetchWithCacheOptions {
+  /** Called before the mutation fires. Use for optimistic UI — set local state here, then rollback from onError. */
+  onMutate?: () => void;
+  onSuccess?: (data: TData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: () => void;
+  /** Deduplication key — if a mutation with the same key is already in-flight, this one is skipped. */
+  mutationKey?: string;
+  /** Retry count on failure (default 0). true = Infinity. */
+  retry?: number | boolean;
+}
+
+/**
+ * Hook for mutations (POST, PUT, PATCH, DELETE) with auto-invalidation, offline queuing,
+ * optimistic updates, and dual-level callbacks.
+ *
+ * Usage:
+ *   const { mutate, isLoading, error, data } = useMutation<CreateTodoResponse>(
+ *     "/api/todos",
+ *     { method: "POST", onSuccess: (data) => navigate(`/item/${data.id}`) },
+ *   );
+ *
+ *   // Called multiple times — all share one loading/error state:
+ *   await mutate({ title: "hello" });
+ *   await mutate({ title: "world" }, {
+ *     onSuccess: (data) => console.log(data),
+ *   });
+ *
+ *   // Optimistic update with rollback:
+ *   const { mutate } = useMutation("/api/todos", {
+ *     method: "POST",
+ *     onMutate: () => { /* set optimistic state *\/ },
+ *     onError: () => { /* rollback *\/ },
+ *   });
+ */
+export function useMutation<TData = unknown>(
+  url: string,
+  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 [mutationId, setMutationId] = useState<string | null>(null);
+  const optionsRef = useRef(options);
+  const urlRef = useRef(url);
+  const inFlightKeys = useRef(new Set<string>());
+
+  urlRef.current = url;
+
+  const mutate = useCallback(
+    async (
+      body?: unknown,
+      callbacks?: MutateCallbacks<TData>,
+    ): Promise<TData | null> => {
+      const key = optionsRef.current.mutationKey;
+      if (key && inFlightKeys.current.has(key)) return null;
+      if (key) inFlightKeys.current.add(key);
+
+      let retriesLeft = optionsRef.current.retry === true
+        ? Infinity
+        : (optionsRef.current.retry ?? 0);
+
+      const mid = "mut-" + crypto.randomUUID();
+      setMutationId(mid);
+      trackMutation(mid, "pending");
+      setState({
+        data: null,
+        error: null,
+        isLoading: true,
+        isError: false,
+        isSuccess: false,
+      });
+
+      optionsRef.current.onMutate?.();
+
+      const attempt = async (): Promise<TData | null> => {
+        try {
+          const fetchOptions = { ...optionsRef.current, body };
+          const { response, queued } = await fetchWithCache<TData>(urlRef.current, fetchOptions);
+          if (queued) {
+            resolveMutation(mid, null);
+            setState({
+              data: null,
+              error: null,
+              isLoading: false,
+              isError: false,
+              isSuccess: false,
+            });
+            optionsRef.current.onSettled?.();
+            callbacks?.onSettled?.();
+            if (key) inFlightKeys.current.delete(key);
+            return null;
+          }
+          const data: TData = await response.json();
+          resolveMutation(mid, data);
+          setState({
+            data,
+            error: null,
+            isLoading: false,
+            isError: false,
+            isSuccess: true,
+          });
+          optionsRef.current.onSuccess?.(data);
+          callbacks?.onSuccess?.(data);
+          optionsRef.current.onSettled?.();
+          callbacks?.onSettled?.();
+          if (key) inFlightKeys.current.delete(key);
+          return data;
+        } catch (err) {
+          if (retriesLeft > 0) {
+            retriesLeft--;
+            await new Promise((r) => setTimeout(r, 1000));
+            return attempt();
+          }
+          const error = err instanceof Error ? err : new Error(String(err));
+          rejectMutation(mid, error);
+          setState({
+            data: null,
+            error,
+            isLoading: false,
+            isError: true,
+            isSuccess: false,
+          });
+          optionsRef.current.onError?.(error);
+          callbacks?.onError?.(error);
+          optionsRef.current.onSettled?.();
+          callbacks?.onSettled?.();
+          if (key) inFlightKeys.current.delete(key);
+          return null;
+        }
+      };
+
+      return attempt();
+    },
+    [],
+  );
+
+  const reset = useCallback(() => {
+    setState({
+      data: null,
+      error: null,
+      isLoading: false,
+      isError: false,
+      isSuccess: false,
+    });
+  }, []);
+
+  return {
+    ...state,
+    mutate,
+    reset,
+    mutationId,
+  };
+}

package/templates/react/useMutationQueue.jsx

@@ -0,0 +1,69 @@
+import { useState, useEffect, useCallback } from "react";
+import { getPendingCount, getQueueItems, processMutationQueue } from "../offline/queue.js";
+
+/**
+ * Reactive mutation queue state: pending count, items, last sync info, and processing flag.
+ *
+ * Usage:
+ *   const { pending, items, lastSync, isProcessing, retryAll } = useMutationQueue();
+ *
+ *   // Show pending badge:
+ *   {pending > 0 && <Badge>{pending}</Badge>}
+ *
+ *   // Retry all queued mutations:
+ *   <button onClick={retryAll} disabled={isProcessing}>
+ *     {isProcessing ? "Syncing..." : "Retry All"}
+ *   </button>
+ */
+export function useMutationQueue() {
+  const [state, setState] = useState({
+    pending: 0,
+    items: [],
+    lastSync: null,
+    isProcessing: false,
+  });
+
+  const refresh = useCallback(async () => {
+    const [count, items] = await Promise.all([
+      getPendingCount(),
+      getQueueItems(),
+    ]);
+    setState((s) => ({ ...s, pending: count, items }));
+  }, []);
+
+  useEffect(() => {
+    queueMicrotask(() => refresh());
+
+    const onSync = (e) => {
+      setState((s) => ({
+        ...s,
+        isProcessing: false,
+        lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
+      }));
+      refresh();
+    };
+    const onChange = () => refresh();
+    const onProgress = () => setState((s) => ({ ...s, isProcessing: true }));
+
+    window.addEventListener("mutation-sync-complete", onSync);
+    window.addEventListener("mutation-queue-changed", onChange);
+    window.addEventListener("mutation-sync-progress", onProgress);
+    return () => {
+      window.removeEventListener("mutation-sync-complete", onSync);
+      window.removeEventListener("mutation-queue-changed", onChange);
+      window.removeEventListener("mutation-sync-progress", onProgress);
+    };
+  }, [refresh]);
+
+  const retryAll = useCallback(async () => {
+    setState((s) => ({ ...s, isProcessing: true }));
+    try {
+      await processMutationQueue();
+    } finally {
+      await refresh();
+      setState((s) => ({ ...s, isProcessing: false }));
+    }
+  }, [refresh]);
+
+  return { ...state, retryAll };
+}

package/templates/react/useMutationQueue.tsx

@@ -0,0 +1,83 @@
+import { useState, useEffect, useCallback } from "react";
+import { getPendingCount, getQueueItems, processMutationQueue } from "../offline/queue.ts";
+import type { MutationQueueItem } from "../swoff.d.ts";
+
+export interface MutationQueueState {
+  pending: number;
+  items: MutationQueueItem[];
+  lastSync: { succeeded: number; failed: number } | null;
+  isProcessing: boolean;
+}
+
+/**
+ * Reactive mutation queue state: pending count, items, last sync info, and processing flag.
+ *
+ * Usage:
+ *   const { pending, items, lastSync, isProcessing, retryAll } = useMutationQueue();
+ *
+ *   // Show pending badge:
+ *   {pending > 0 && <Badge>{pending}</Badge>}
+ *
+ *   // Retry all queued mutations:
+ *   <button onClick={retryAll} disabled={isProcessing}>
+ *     {isProcessing ? "Syncing..." : "Retry All"}
+ *   </button>
+ *
+ * @returns {{ pending, items, lastSync, isProcessing, retryAll }}
+ */
+export function useMutationQueue(): MutationQueueState & { retryAll: () => Promise<void> } {
+  const [state, setState] = useState<MutationQueueState>({
+    pending: 0,
+    items: [],
+    lastSync: null,
+    isProcessing: false,
+  });
+
+  const refresh = useCallback(async () => {
+    const [count, items] = await Promise.all([
+      getPendingCount(),
+      getQueueItems(),
+    ]);
+    setState((s) => ({ ...s, pending: count, items }));
+  }, []);
+
+  useEffect(() => {
+    queueMicrotask(() => refresh());
+
+    const onSync = (e: CustomEvent) => {
+      setState((s) => ({
+        ...s,
+        isProcessing: false,
+        lastSync: { succeeded: e.detail.succeeded, failed: e.detail.failed },
+      }));
+      refresh();
+    };
+    const onChange = () => {
+      refresh();
+    };
+    const onProgress = () => {
+      setState((s) => ({ ...s, isProcessing: true }));
+    };
+
+    window.addEventListener("mutation-sync-complete", onSync);
+    window.addEventListener("mutation-queue-changed", onChange);
+    window.addEventListener("mutation-sync-progress", onProgress);
+    return () => {
+      window.removeEventListener("mutation-sync-complete", onSync);
+      window.removeEventListener("mutation-queue-changed", onChange);
+      window.removeEventListener("mutation-sync-progress", onProgress);
+    };
+  }, [refresh]);
+
+  const retryAll = useCallback(async () => {
+    setState((s) => ({ ...s, isProcessing: true }));
+    try {
+      await processMutationQueue();
+    } finally {
+      await refresh();
+      setState((s) => ({ ...s, isProcessing: false }));
+    }
+  }, [refresh]);
+
+  return { ...state, retryAll };
+}

package/templates/react/useMutationState.jsx

@@ -0,0 +1,13 @@
+import { useSyncExternalStore } from "react";
+import { getMutationState, onMutationStateChange } from "../mutation-state.js";
+
+function subscribeToMutations(cb) {
+  return onMutationStateChange(() => cb());
+}
+
+export function useMutationState(id) {
+  return useSyncExternalStore(
+    subscribeToMutations,
+    () => (id ? getMutationState(id) ?? null : null),
+  );
+}

package/templates/react/useMutationState.tsx

@@ -0,0 +1,25 @@
+import { useSyncExternalStore } from "react";
+import {
+  getMutationState,
+  onMutationStateChange,
+} from "../mutation-state.ts";
+import type { MutationState } from "../mutation-state.ts";
+
+function subscribeToMutations(cb: () => void) {
+  return onMutationStateChange(() => cb());
+}
+
+/**
+ * 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 {
+  return useSyncExternalStore(
+    subscribeToMutations,
+    () => (id ? getMutationState(id) ?? null : null),
+  );
+}

package/templates/react/useNetworkStatus.jsx

@@ -0,0 +1,61 @@
+import { useState, useEffect, useRef } from "react";
+
+/**
+ * Reactive network information: online status, connection type, and bandwidth.
+ *
+ * Usage:
+ *   const { online, wasOffline, lastChangedAt, effectiveType, downlink } = useNetworkStatus();
+ *
+ *   // Show offline indicator:
+ *   if (!online) return <OfflineBanner />;
+ *
+ *   // Warn on slow connection:
+ *   if (online && effectiveType === "2g") return <SlowConnectionWarning />;
+ */
+export function useNetworkStatus() {
+  const wasOfflineRef = useRef(false);
+
+  const [state, setState] = useState(() => {
+    const online = typeof navigator !== "undefined" ? navigator.onLine : true;
+    const connection = navigator?.connection;
+    return {
+      online,
+      wasOffline: false,
+      lastChangedAt: null,
+      effectiveType: connection?.effectiveType ?? null,
+      downlink: connection?.downlink ?? null,
+    };
+  });
+
+  useEffect(() => {
+    const onOnline = () => {
+      setState((s) => ({ ...s, online: true, lastChangedAt: Date.now() }));
+    };
+    const onOffline = () => {
+      wasOfflineRef.current = true;
+      setState((s) => ({ ...s, online: false, lastChangedAt: Date.now(), wasOffline: true }));
+    };
+
+    const connection = navigator?.connection;
+    const onTypeChange = () => {
+      if (!connection) return;
+      setState((s) => ({ ...s, effectiveType: connection.effectiveType, downlink: connection.downlink }));
+    };
+
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    if (connection) {
+      connection.addEventListener("change", onTypeChange);
+    }
+
+    return () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+      if (connection) {
+        connection.removeEventListener("change", onTypeChange);
+      }
+    };
+  }, []);
+
+  return state;
+}

package/templates/react/useNetworkStatus.tsx

@@ -0,0 +1,76 @@
+import { useState, useEffect, useRef } from "react";
+
+/**
+ * Reactive network information: online status, connection type, and bandwidth.
+ *
+ * Usage:
+ *   const { online, wasOffline, lastChangedAt, effectiveType, downlink } = useNetworkStatus();
+ *
+ *   // Show offline indicator:
+ *   if (!online) return <OfflineBanner />;
+ *
+ *   // Warn on slow connection:
+ *   if (online && effectiveType === "2g") return <SlowConnectionWarning />;
+ *
+ * @returns {{ online: boolean, wasOffline: boolean, lastChangedAt: number | null, effectiveType: string | null, downlink: number | null }}
+ */
+export function useNetworkStatus() {
+  const wasOfflineRef = useRef(false);
+
+  const [state, setState] = useState(() => {
+    const online = typeof navigator !== "undefined" ? navigator.onLine : true;
+    const connection = navigator?.connection;
+    return {
+      online,
+      wasOffline: false,
+      lastChangedAt: null as number | null,
+      effectiveType: connection?.effectiveType ?? null,
+      downlink: connection?.downlink ?? null,
+    };
+  });
+
+  useEffect(() => {
+    const onOnline = () => {
+      setState((s) => ({
+        ...s,
+        online: true,
+        lastChangedAt: Date.now(),
+      }));
+    };
+    const onOffline = () => {
+      wasOfflineRef.current = true;
+      setState((s) => ({
+        ...s,
+        online: false,
+        lastChangedAt: Date.now(),
+        wasOffline: true,
+      }));
+    };
+
+    const connection = navigator?.connection;
+    const onTypeChange = () => {
+      if (!connection) return;
+      setState((s) => ({
+        ...s,
+        effectiveType: connection.effectiveType,
+        downlink: connection.downlink,
+      }));
+    };
+
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    if (connection) {
+      connection.addEventListener("change", onTypeChange);
+    }
+
+    return () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+      if (connection) {
+        connection.removeEventListener("change", onTypeChange);
+      }
+    };
+  }, []);
+
+  return state;
+}

package/templates/react/usePrefetch.jsx

@@ -0,0 +1,32 @@
+import { useCallback, useState } from "react";
+import { prefetchCache } from "../fetch/core.js";
+
+/**
+ * Hook that returns a stable prefetch callback, observable prefetch list, and clear function.
+ *
+ * Usage:
+ *   const { prefetch, prefetchList, clear } = usePrefetch();
+ *
+ *   // Prefetch when user hovers a link:
+ *   <Link onMouseEnter={() => prefetch("/api/todos")} to="/todos" />
+ *
+ *   // Show how many URLs are prefetched:
+ *   <span>{prefetchList.length} routes cached</span>
+ *
+ *   // Clear prefetched data:
+ *   <button onClick={clear}>Clear prefetch</button>
+ */
+export function usePrefetch() {
+  const [prefetchList, setPrefetchList] = useState([]);
+
+  const prefetch = useCallback((url, options) => {
+    prefetchCache(url, options);
+    setPrefetchList((list) => list.includes(url) ? list : [...list, url]);
+  }, []);
+
+  const clear = useCallback(() => {
+    setPrefetchList([]);
+  }, []);
+
+  return { prefetch, prefetchList, clear };
+}