@swoff/cli 0.4.3 → 0.4.5

package/templates/vue/useSwoffMutation.js

@@ -0,0 +1,124 @@
+import { ref } from "vue";
+import { fetchWithCache } from "../fetch/core.js";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../mutation/state.js";
+
+/**
+ * Composable for mutations (POST, PUT, PATCH, DELETE) with auto-invalidation, offline queuing,
+ * optimistic updates, and dual-level callbacks.
+ *
+ * Usage:
+ *   const { mutate, isLoading, error, data } = useSwoffMutation("/api/todos", {
+ *     method: "POST",
+ *     onSuccess: (data) => navigate(`/item/${data.id}`),
+ *   });
+ *
+ *   // Check result status after mutate:
+ *   const result = await mutate(body);
+ *   if (result.status === "success") navigate(`/item/${result.data.id}`);
+ */
+export function useSwoffMutation(url, options = {}) {
+  const lastResult = ref(null);
+  const isLoading = ref(false);
+  const mutationId = ref(null);
+
+  const inFlightKeys = new Set();
+
+  async function mutate(body, callbacks) {
+    const key = options.mutationKey;
+    if (key && inFlightKeys.has(key)) return { status: "skipped" };
+    if (key) inFlightKeys.add(key);
+
+    let retriesLeft =
+      options.retry === true
+        ? Infinity
+        : typeof options.retry === "number"
+          ? options.retry
+          : 0;
+
+    const mid = "mut-" + crypto.randomUUID();
+    mutationId.value = mid;
+    trackMutation(mid, "pending");
+    isLoading.value = true;
+
+    options.onMutate?.();
+
+    const attempt = async () => {
+      try {
+        const {
+          mutationKey,
+          onMutate,
+          onSuccess,
+          onError,
+          onSettled,
+          retry,
+          ...fetchOnlyOptions
+        } = options;
+        const fetchOptions = { ...fetchOnlyOptions, body };
+        const { response, queued } = await fetchWithCache(url, fetchOptions);
+        if (queued) {
+          resolveMutation(mid, null);
+          isLoading.value = false;
+          const r = { status: "queued" };
+          lastResult.value = r;
+          options.onSettled?.();
+          callbacks?.onSettled?.();
+          if (key) inFlightKeys.delete(key);
+          return r;
+        }
+        const data = await response.json();
+        resolveMutation(mid, data);
+        isLoading.value = false;
+        const r = { status: "success", data };
+        lastResult.value = r;
+        options.onSuccess?.(data);
+        callbacks?.onSuccess?.(data);
+        options.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.delete(key);
+        return r;
+      } 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);
+        isLoading.value = false;
+        const r = { status: "error", error };
+        lastResult.value = r;
+        options.onError?.(error);
+        callbacks?.onError?.(error);
+        options.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.delete(key);
+        return r;
+      }
+    };
+
+    return attempt();
+  }
+
+  function reset() {
+    lastResult.value = null;
+    isLoading.value = false;
+  }
+
+  return {
+    mutate,
+    isLoading,
+    isIdle: lastResult.value === null,
+    isQueued: lastResult.value?.status === "queued",
+    isSuccess: lastResult.value?.status === "success",
+    isError: lastResult.value?.status === "error",
+    data: lastResult.value?.status === "success" ? (lastResult.value.data ?? null) : null,
+    error: lastResult.value?.status === "error" ? (lastResult.value.error ?? null) : null,
+    lastResult,
+    reset,
+    mutationId,
+  };
+}

package/templates/vue/useSwoffMutation.ts

@@ -0,0 +1,155 @@
+import { ref } from "vue";
+import { fetchWithCache } from "../fetch/core";
+import {
+  trackMutation,
+  resolveMutation,
+  rejectMutation,
+} from "../mutation/state";
+import type { FetchWithCacheOptions } from "../fetch/core";
+
+export interface MutateCallbacks<TData> {
+  onSuccess?: (data: TData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: () => void;
+}
+
+export interface UseMutationOptions<TData> extends FetchWithCacheOptions {
+  onMutate?: () => void;
+  onSuccess?: (data: TData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: () => void;
+  mutationKey?: string;
+  retry?: number | boolean;
+}
+
+export type MutateResult<T> =
+  | { status: "skipped" }
+  | { status: "queued" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+
+/**
+ * Composable for mutations (POST, PUT, PATCH, DELETE) with auto-invalidation, offline queuing,
+ * optimistic updates, and dual-level callbacks.
+ *
+ * Usage:
+ *   const { mutate, isLoading, error, data } = useSwoffMutation("/api/todos", {
+ *     method: "POST",
+ *     onSuccess: (data) => navigate(`/item/${data.id}`),
+ *   });
+ *
+ *   // Check result status after mutate:
+ *   const result = await mutate(body);
+ *   if (result.status === "success") navigate(`/item/${result.data.id}`);
+ */
+export function useSwoffMutation<TData = unknown>(
+  url: string,
+  options: UseMutationOptions<TData> = {},
+) {
+  const lastResult = ref<MutateResult<TData> | null>(null);
+  const isLoading = ref(false);
+  const mutationId = ref<string | null>(null);
+
+  const inFlightKeys = new Set<string>();
+
+  async function mutate(
+    body?: unknown,
+    callbacks?: MutateCallbacks<TData>,
+  ): Promise<MutateResult<TData>> {
+    const key = options.mutationKey;
+    if (key && inFlightKeys.has(key)) return { status: "skipped" };
+    if (key) inFlightKeys.add(key);
+
+    let retriesLeft: number =
+      options.retry === true
+        ? Infinity
+        : typeof options.retry === "number"
+          ? options.retry
+          : 0;
+
+    const mid = "mut-" + crypto.randomUUID();
+    mutationId.value = mid;
+    trackMutation(mid, "pending");
+    isLoading.value = true;
+
+    options.onMutate?.();
+
+    const attempt = async (): Promise<MutateResult<TData>> => {
+      try {
+        const {
+          mutationKey,
+          onMutate,
+          onSuccess,
+          onError,
+          onSettled,
+          retry,
+          ...fetchOnlyOptions
+        } = options;
+        const fetchOptions = { ...fetchOnlyOptions, body };
+        const { response, queued } = await fetchWithCache<TData>(
+          url,
+          fetchOptions as FetchWithCacheOptions,
+        );
+        if (queued) {
+          resolveMutation(mid, null);
+          isLoading.value = false;
+          const r: MutateResult<TData> = { status: "queued" };
+          lastResult.value = r;
+          options.onSettled?.();
+          callbacks?.onSettled?.();
+          if (key) inFlightKeys.delete(key);
+          return r;
+        }
+        const data: TData = await response.json();
+        resolveMutation(mid, data);
+        isLoading.value = false;
+        const r: MutateResult<TData> = { status: "success", data };
+        lastResult.value = r;
+        options.onSuccess?.(data);
+        callbacks?.onSuccess?.(data);
+        options.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.delete(key);
+        return r;
+      } 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);
+        isLoading.value = false;
+        const r: MutateResult<TData> = { status: "error", error };
+        lastResult.value = r;
+        options.onError?.(error);
+        callbacks?.onError?.(error);
+        options.onSettled?.();
+        callbacks?.onSettled?.();
+        if (key) inFlightKeys.delete(key);
+        return r;
+      }
+    };
+
+    return attempt();
+  }
+
+  function reset() {
+    lastResult.value = null;
+    isLoading.value = false;
+  }
+
+  return {
+    mutate,
+    isLoading,
+    isIdle: lastResult.value === null,
+    isQueued: lastResult.value?.status === "queued",
+    isSuccess: lastResult.value?.status === "success",
+    isError: lastResult.value?.status === "error",
+    data: lastResult.value?.status === "success" ? (lastResult.value.data ?? null) : null,
+    error: lastResult.value?.status === "error" ? (lastResult.value.error ?? null) : null,
+    lastResult,
+    reset,
+    mutationId,
+  };
+}

package/templates/vue/useSwoffMutationState.js

@@ -0,0 +1,35 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import { getMutationState, onMutationStateChange } from "../mutation/state.js";
+
+/**
+ * Composable that subscribes to a specific mutation's state changes.
+ * Useful for showing per-mutation loading spinners, error states, etc.
+ *
+ * Usage:
+ *   const mutation = useSwoffMutationState(mutationId);
+ *   <div v-if="mutation?.status === 'error'">{{ mutation?.error?.message }}</div>
+ */
+export function useSwoffMutationState(id) {
+  const state = ref(null);
+
+  function update() {
+    state.value = id ? (getMutationState(id) ?? null) : null;
+  }
+
+  onMounted(update);
+
+  let cleanup;
+
+  onMounted(() => {
+    const unsub = onMutationStateChange(update);
+    if (typeof unsub === "function") {
+      cleanup = unsub;
+    }
+
+    onUnmounted(() => {
+      cleanup?.();
+    });
+  });
+
+  return state;
+}

package/templates/vue/useSwoffMutationState.ts

@@ -0,0 +1,36 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import { getMutationState, onMutationStateChange } from "../mutation/state";
+import type { MutationState } from "../mutation/state";
+
+/**
+ * Composable that subscribes to a specific mutation's state changes.
+ * Useful for showing per-mutation loading spinners, error states, etc.
+ *
+ * Usage:
+ *   const mutation = useSwoffMutationState(mutationId);
+ *   <div v-if="mutation?.status === 'error'">{{ mutation?.error?.message }}</div>
+ */
+export function useSwoffMutationState(id: string | null) {
+  const state = ref<MutationState | null>(null);
+
+  function update() {
+    state.value = id ? (getMutationState(id) ?? null) : null;
+  }
+
+  onMounted(update);
+
+  let cleanup: (() => void) | undefined;
+
+  onMounted(() => {
+    const unsub = onMutationStateChange(update);
+    if (typeof unsub === "function") {
+      cleanup = unsub;
+    }
+
+    onUnmounted(() => {
+      cleanup?.();
+    });
+  });
+
+  return state;
+}

package/templates/vue/useSwoffNetwork.js

@@ -0,0 +1,86 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import {
+  CONNECTIVITY_EVENT,
+  forceRetry,
+  getCurrentOnlineStatus,
+} from "../connectivity.js";
+
+/**
+ * Reactive network information: online status, connection type, and bandwidth.
+ *
+ * Usage:
+ *   const { online, wasOffline, lastChangedAt, effectiveType, downlink } = useSwoffNetwork();
+ *
+ *   // Show offline indicator:
+ *   <div v-if="!online">You are offline</div>
+ *
+ *   // Warn on slow connection:
+ *   <div v-if="online && effectiveType === '2g'">Slow connection detected</div>
+ */
+export function useSwoffNetwork() {
+  const online = ref(true);
+  const wasOffline = ref(false);
+  const lastChangedAt = ref(null);
+  const effectiveType = ref(null);
+  const downlink = ref(null);
+  const isRetrying = ref(false);
+
+  let wasOfflineFlag = false;
+
+  onMounted(() => {
+    if (!getCurrentOnlineStatus()) {
+      wasOfflineFlag = true;
+      online.value = false;
+      wasOffline.value = true;
+      lastChangedAt.value = Date.now();
+    }
+
+    const connection = navigator.connection;
+
+    function handleConnectivityChange(e) {
+      const isTrulyOnline = e.detail.online;
+      if (!isTrulyOnline) {
+        wasOfflineFlag = true;
+      } else {
+        wasOfflineFlag = false;
+      }
+      online.value = isTrulyOnline;
+      wasOffline.value = wasOfflineFlag;
+      lastChangedAt.value = Date.now();
+    }
+
+    function onTypeChange() {
+      if (!connection) return;
+      effectiveType.value = connection.effectiveType;
+      downlink.value = connection.downlink;
+    }
+
+    window.addEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
+    if (connection) {
+      connection.addEventListener("change", onTypeChange);
+    }
+
+    onUnmounted(() => {
+      window.removeEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
+      if (connection) {
+        connection.removeEventListener("change", onTypeChange);
+      }
+    });
+  });
+
+  async function retry() {
+    isRetrying.value = true;
+    await forceRetry();
+    isRetrying.value = false;
+  }
+
+  return {
+    online,
+    wasOffline,
+    lastChangedAt,
+    effectiveType,
+    downlink,
+    isRetrying,
+    retry,
+  };
+}

package/templates/vue/useSwoffNetwork.ts

@@ -0,0 +1,89 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import {
+  CONNECTIVITY_EVENT,
+  forceRetry,
+  getCurrentOnlineStatus,
+} from "../connectivity";
+
+/**
+ * Reactive network information: online status, connection type, and bandwidth.
+ *
+ * Usage:
+ *   const { online, wasOffline, lastChangedAt, effectiveType, downlink } = useSwoffNetwork();
+ *
+ *   // Show offline indicator:
+ *   <div v-if="!online">You are offline</div>
+ *
+ *   // Warn on slow connection:
+ *   <div v-if="online && effectiveType === '2g'">Slow connection detected</div>
+ *
+ * @returns {{ online: Ref<boolean>, wasOffline: Ref<boolean>, lastChangedAt: Ref<number | null>, effectiveType: Ref<string | null>, downlink: Ref<number | null>, isRetrying: Ref<boolean>, retry: () => Promise<void> }}
+ */
+export function useSwoffNetwork() {
+  const online = ref(true);
+  const wasOffline = ref(false);
+  const lastChangedAt = ref<number | null>(null);
+  const effectiveType = ref<string | null>(null);
+  const downlink = ref<number | null>(null);
+  const isRetrying = ref(false);
+
+  let wasOfflineFlag = false;
+
+  onMounted(() => {
+    // Sync with actual status after mount — prevents SSR hydration mismatch
+    if (!getCurrentOnlineStatus()) {
+      wasOfflineFlag = true;
+      online.value = false;
+      wasOffline.value = true;
+      lastChangedAt.value = Date.now();
+    }
+
+    const connection = navigator.connection;
+
+    function handleConnectivityChange(e: Event) {
+      const isTrulyOnline = (e as CustomEvent).detail.online;
+      if (!isTrulyOnline) {
+        wasOfflineFlag = true;
+      } else {
+        wasOfflineFlag = false;
+      }
+      online.value = isTrulyOnline;
+      wasOffline.value = wasOfflineFlag;
+      lastChangedAt.value = Date.now();
+    }
+
+    function onTypeChange() {
+      if (!connection) return;
+      effectiveType.value = connection.effectiveType;
+      downlink.value = connection.downlink;
+    }
+
+    window.addEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
+    if (connection) {
+      connection.addEventListener("change", onTypeChange);
+    }
+
+    onUnmounted(() => {
+      window.removeEventListener(CONNECTIVITY_EVENT, handleConnectivityChange);
+      if (connection) {
+        connection.removeEventListener("change", onTypeChange);
+      }
+    });
+  });
+
+  async function retry() {
+    isRetrying.value = true;
+    await forceRetry();
+    isRetrying.value = false;
+  }
+
+  return {
+    online,
+    wasOffline,
+    lastChangedAt,
+    effectiveType,
+    downlink,
+    isRetrying,
+    retry,
+  };
+}

package/templates/vue/useSwoffPrecache.js

@@ -0,0 +1,19 @@
+import { ref, onMounted, onUnmounted } from "vue";
+
+export function useSwoffPrecache() {
+  const progress = ref(0);
+
+  function onProgress(e) {
+    progress.value = e.detail.percent;
+  }
+
+  onMounted(() => {
+    window.addEventListener("sw-progress", onProgress);
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener("sw-progress", onProgress);
+  });
+
+  return { progress };
+}

package/templates/vue/useSwoffPrecache.ts

@@ -0,0 +1,19 @@
+import { ref, onMounted, onUnmounted } from "vue";
+
+export function useSwoffPrecache() {
+  const progress = ref(0);
+
+  function onProgress(e: WindowEventMap["sw-progress"]) {
+    progress.value = e.detail.percent;
+  }
+
+  onMounted(() => {
+    window.addEventListener("sw-progress", onProgress);
+  });
+
+  onUnmounted(() => {
+    window.removeEventListener("sw-progress", onProgress);
+  });
+
+  return { progress };
+}

package/templates/vue/useSwoffPrefetch.js

@@ -0,0 +1,33 @@
+import { ref } from "vue";
+import { prefetchCache } from "../fetch/core.js";
+/**
+ * Composable that returns a stable prefetch callback, observable prefetch list, and clear function.
+ *
+ * Usage:
+ *   const { prefetch, prefetchList, clear } = useSwoffPrefetch();
+ *
+ *   // Prefetch when user hovers a link:
+ *   <button @mouseenter="prefetch('/api/todos')">Load</button>
+ *
+ *   // Show how many URLs are prefetched:
+ *   <span>{{ prefetchList.length }} routes cached</span>
+ *
+ *   // Clear prefetched data:
+ *   <button @click="clear">Clear prefetch</button>
+ */
+export function useSwoffPrefetch() {
+  const prefetchList = ref([]);
+
+  function prefetch(url, options) {
+    prefetchCache(url, options);
+    if (!prefetchList.value.includes(url)) {
+      prefetchList.value = [...prefetchList.value, url];
+    }
+  }
+
+  function clear() {
+    prefetchList.value = [];
+  }
+
+  return { prefetch, prefetchList: prefetchList.value, clear };
+}

package/templates/vue/useSwoffPrefetch.ts

@@ -0,0 +1,41 @@
+import { ref } from "vue";
+import { prefetchCache } from "../fetch/core";
+import type { FetchWithCacheOptions } from "../fetch/core";
+
+/**
+ * Composable that returns a stable prefetch callback, observable prefetch list, and clear function.
+ *
+ * Usage:
+ *   const { prefetch, prefetchList, clear } = useSwoffPrefetch();
+ *
+ *   // Prefetch when user hovers a link:
+ *   <button @mouseenter="prefetch('/api/todos')">Load</button>
+ *
+ *   // Show how many URLs are prefetched:
+ *   <span>{{ prefetchList.length }} routes cached</span>
+ *
+ *   // Clear prefetched data:
+ *   <button @click="clear">Clear prefetch</button>
+ *
+ * @returns {{ prefetch: (url: string, options?: FetchWithCacheOptions) => void, prefetchList: string[], clear: () => void }}
+ */
+export function useSwoffPrefetch(): {
+  prefetch: (url: string, options?: FetchWithCacheOptions) => void;
+  prefetchList: string[];
+  clear: () => void;
+} {
+  const prefetchList = ref<string[]>([]);
+
+  function prefetch(url: string, options?: FetchWithCacheOptions) {
+    prefetchCache(url, options);
+    if (!prefetchList.value.includes(url)) {
+      prefetchList.value = [...prefetchList.value, url];
+    }
+  }
+
+  function clear() {
+    prefetchList.value = [];
+  }
+
+  return { prefetch, prefetchList: prefetchList.value, clear };
+}