@swoff/cli 0.3.5 → 0.3.6

package/dist/lib/generators/file-generators/guide-generator.js

@@ -0,0 +1,333 @@
+/**
+ * Generates GUIDE.md — full integration guide for enabled features.
+ */
+import { writeFile } from "./context.js";
+export function generateGuide(ctx) {
+    const { config } = ctx;
+    const ext = ctx.ext;
+    const lines = [];
+    const w = (s) => lines.push(s);
+    const wb = (s) => lines.push("", s);
+    w("# Swoff Integration Guide");
+    w("");
+    w("This guide explains every file and feature Swoff generated for your project.");
+    w("Each section answers: **What is it?**, **What files were created?**, **How to use it?**, **Where to edit?**");
+    w("");
+    // ── SW Registration ──
+    wb("## 📦 Service Worker Registration");
+    w("The service worker handles caching, offline support, background sync, and PWA installability.");
+    w("");
+    const hasSW = config.features.clientRegistration || config.features.pwa.enabled || config.features.crossTabSync;
+    if (hasSW) {
+        w("### `client-injector.ts` — Single entry point");
+        w("This is the **only file you need to import** at app startup to enable all Swoff features.");
+        w("```ts");
+        w(`import { initServiceWorker } from "./swoff/client-injector.${ext}";`);
+        w("initServiceWorker();");
+        w("```");
+        w("It wires together: SW registration, PWA install prompt, mutation queue online listener, and cross-tab sync.");
+        w("");
+        if (config.features.clientRegistration) {
+            w("### `sw/injector.ts` — SW registration logic");
+            w("Handles registering the service worker, checking for updates via version.json, and dispatching");
+            w("update-available / ready / error events on the window.");
+            w("");
+            w("**Functions:**");
+            w("- `initServiceWorker()` — registers the SW and checks for updates");
+            w("- `handleUpdateApproved(version)` — accepts a pending update and reloads on activation");
+            w("- `skipWaiting()` — activates a waiting SW without reloading");
+            w("");
+        }
+    }
+    // ── Fetch Wrapper ──
+    wb("## 🌐 fetchWithCache — API calls with caching");
+    w("A drop-in replacement for `fetch()` that communicates with the service worker about caching strategy.");
+    w("GET requests are cached by the SW for offline access; POST/PUT/DELETE pass through.");
+    w("");
+    w("### `fetch-wrapper.ts`");
+    w("```ts");
+    w(`import { fetchWithCache } from "./swoff/fetch-wrapper.${ext}";`);
+    w("");
+    w("// GET — cached for offline");
+    w('const todos = await fetchWithCache("/api/todos").then(r => r.json());');
+    w("");
+    w("// POST — passes through to server");
+    w("await fetchWithCache(\"/api/todos\", {");
+    w('  method: "POST",');
+    w('  body: JSON.stringify({ title: "New task" }),');
+    w("});");
+    w("```");
+    w("");
+    w("**Functions:**");
+    w("- `fetchWithCache(input, options?)` — main fetch wrapper. Use for all API calls.");
+    w("- `fetchWithCache(input, options?)` — unified fetch wrapper. Auto-queues writes when offline (disable with `queueOffline: false`).");
+    w("");
+    w("**Returns** `{ response: Response, fromCache: boolean }` — `fromCache` lets the UI show stale indicators when a stale-while-revalidate fallback is served.");
+    w("");
+    w("**Note:** There is no separate `authenticatedMutation` wrapper. For authenticated writes, just use `authenticatedFetch` (see Auth section below).");
+    w("");
+    if (ctx.frameworkName === "react") {
+        w("### React Hook: `useCachedFetch`");
+        w("Re-fetches automatically when the SW invalidates related cache tags.");
+        w("```tsx");
+        w(`import { useCachedFetch } from "./swoff/hooks/useCachedFetch.${ext}x";`);
+        w("");
+        w('const { data, error, loading, refetch } = useCachedFetch("/api/todos");');
+        w("```");
+        w("");
+        w("**Returns** `{ data: Response | null, error, loading, refetch }`");
+        w("");
+        w("The hook listens for `cache-invalidated` events (when tag invalidation is enabled) and automatically");
+        w("re-fetches if the event's tags match the URL. Call `refetch()` to manually refresh.");
+        w("");
+    }
+    // ── Mutation Queue ──
+    if (config.features.mutationQueue) {
+        wb("## 📝 Mutation Queue — offline writes that sync when back online");
+        w("When the user is offline and performs a write (POST/PUT/PATCH/DELETE), `queueMutation` stores it");
+        w("in IndexedDB. When the connection returns, `processMutationQueue` replays them in order.");
+        w("");
+        w("### `mutation-queue.ts`");
+        w("```ts");
+        w(`import { queueMutation, processMutationQueue, flushMutations, getPendingCount } from "./swoff/mutation-queue.${ext}";`);
+        w("");
+        w("// Queue an offline write");
+        w("await queueMutation({");
+        w('  method: "POST",');
+        w('  url: "/api/todos",');
+        w('  body: { title: "Grocery" },');
+        w('  tags: ["todos"],');
+        w("});");
+        w("");
+        w("// Flush after re-login (mutations queued while offline may fail with 401)");
+        w("await flushMutations();");
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `queueMutation(mutation)` — store a write for later sync");
+        w("- `processMutationQueue()` — replay all queued writes. Runs automatically on `online` event.");
+        w("- `flushMutations()` — same as processMutationQueue. Call after re-login.");
+        w("- `getPendingCount()` — number of mutations waiting to sync.");
+        w("");
+        if (config.features.backgroundSync) {
+            w("### `background-sync.ts` — Sync even after tab close");
+            w("Uses the Background Sync API to register a sync event so mutations are processed even if the user");
+            w("closes the tab. Falls back to the `online` event listener in unsupported browsers (Firefox, Safari).");
+            w("```ts");
+            w(`import { syncWhenPossible } from "./swoff/background-sync.${ext}";`);
+            w("await syncWhenPossible({ method: \"POST\", url: \"/api/todos\", body: { ... } });");
+            w("```");
+            w("");
+            w("**Functions:**");
+            w("- `syncWhenPossible(mutation)` — queue and register background sync");
+            w("- `retrySync()` — re-register sync if mutations are still pending (called automatically)");
+            w("");
+            w("> ⚠️ Background Sync is Chrome/Edge only. Not supported in Firefox or Safari.");
+            w("");
+        }
+    }
+    // ── Auth ──
+    if (config.features.auth.enabled) {
+        wb("## 🔐 Auth — token management and authenticated requests");
+        w("Swoff's auth module manages authentication state with a **memory-only token** (never persisted to");
+        w("IndexedDB) and optional offline user info caching.");
+        w("");
+        const authType = config.features.auth.type;
+        w(`Auth type: **${authType}**`);
+        w("");
+        if (authType === "bearer") {
+            w("> ⚠️ The Bearer token lives **in memory only** and is cleared on page refresh.");
+            w("> Only `{ user, expiresAt }` is persisted to IndexedDB for offline user display.");
+            w("> After a page refresh, re-login is required. Use the `refreshPath` for token refresh.");
+            w("");
+        }
+        w("### `auth/store.ts` — Token and user persistence");
+        w("```ts");
+        w(`import { setAuth, getAuth, clearAuth, isAuthValid, createAuthFromResponse } from "./swoff/auth/store.${ext}";`);
+        w("");
+        w("// After successful login, store auth data");
+        w("await setAuth({ token, user, expiresAt });");
+        w("");
+        w("// Check if still authenticated");
+        w("const auth = await getAuth();");
+        w("if (!isAuthValid(auth)) { /* redirect to login */ }");
+        w("```");
+        w("");
+        w("**Where to edit:**");
+        w("- `createAuthFromResponse(response)` — **edit this** to match your backend's login response shape.");
+        w("");
+        w("**Functions:**");
+        w("- `setAuth(authData)` — store in memory + persist user to IndexedDB");
+        w("- `getAuth()` — get from memory (or IndexedDB after refresh)");
+        w("- `clearAuth()` — clear everything (call on logout/401)");
+        w("- `isAuthValid(auth)` — check expiry");
+        w("- `createAuthFromResponse(response)` — extract AuthData from login response. **Edit this.**");
+        w("");
+        w("### `auth/fetch.ts` — Authenticated API calls");
+        w("Wraps `fetchWithCache` with automatic auth headers and 401 handling.");
+        w("No separate `authenticatedMutation` needed — just use `authenticatedFetch` for both reads and writes.");
+        w("```ts");
+        w(`import { authenticatedFetch, ensureValidAuth } from "./swoff/auth/fetch.${ext}";`);
+        w("");
+        w("// Authenticated GET");
+        w('const user = await authenticatedFetch("/api/me").then(r => r.json());');
+        w("");
+        w("// Authenticated POST (mutation)");
+        w("await authenticatedFetch(\"/api/todos\", {");
+        w('  method: "POST",');
+        w('  body: JSON.stringify({ title: "New" }),');
+        w("});");
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `authenticatedFetch(input, options)` — auth-aware fetch. Attaches token, bypasses cache for auth endpoints, dispatches `sw-auth-unauthorized` on 401.");
+        w("- `ensureValidAuth()` — check expiry and refresh token if needed (uses refreshPath from config).");
+        w("");
+        w("**Where to edit:**");
+        w("- The `isAuthUrl` function in `auth/fetch.ts` lists auth endpoints that bypass the SW cache. Edit this list if your backend uses different paths.");
+        w("- If your auth type is `custom`, edit the `withAuthHeaders` function.");
+        w("");
+        w("### `auth/user.ts` — User data caching");
+        w("```ts");
+        w(`import { fetchCurrentUser, getCachedUser, cacheUser, clearCachedUser } from "./swoff/auth/user.${ext}";`);
+        w("");
+        w("// Fetch and cache the current user");
+        w("const user = await fetchCurrentUser();");
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `fetchCurrentUser()` — fetch from user endpoint and cache in IndexedDB");
+        w("- `getCachedUser()` — load user from IndexedDB (available offline)");
+        w("- `cacheUser(user)` — persist user object manually");
+        w("- `clearCachedUser()` — remove user from cache (call on logout)");
+        w("");
+        w("### `auth/state.ts` — Auth state detection");
+        w("Detects which of the 4 states the app is in: online+authenticated, online+unauthenticated, offline+authenticated, offline+unauthenticated.");
+        w("```ts");
+        w(`import { getAuthState } from "./swoff/auth/state.${ext}";`);
+        w('const { authenticated, user, online } = await getAuthState();');
+        w("```");
+        w("");
+        if (ctx.frameworkName === "react") {
+            w("### React Hooks");
+            w("- `useAuth()` — returns `{ authenticated, user, online }`, listens to online/offline/auth changes");
+            w("- `useCachedFetch(url, options?)` — fetches with auto-refetch on tag invalidation, see Fetch Wrapper section");
+            w("");
+        }
+    }
+    // ── Tag Invalidation ──
+    if (config.features.tagInvalidation) {
+        wb("## 🏷️ Tag Invalidation — keep cached data fresh");
+        w("When data changes on the server, cached responses in the SW become stale. Tag invalidation");
+        w("lets you mark related cache entries as stale so they're re-fetched on next request.");
+        w("");
+        w("### How it works");
+        w("1. When fetching, attach tags: `fetchWithCache(url, { tags: generateTags(url) })`");
+        w("2. After a mutation, invalidate: `await invalidateUrl(url)`");
+        w("3. The SW removes all cached responses that were tagged with the related tags");
+        w("");
+        w("### `invalidation-tags.ts` — Tag generation helpers");
+        w("```ts");
+        w(`import { generateTags, invalidateUrl } from "./swoff/invalidation-tags.${ext}";`);
+        w("");
+        w('// Tag reads');
+        w('const data = await fetchWithCache("/api/todos", { tags: generateTags("/api/todos") });');
+        w("");
+        w('// Invalidate after writing');
+        w('await invalidateUrl("/api/todos/42");');
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `generateTags(url)` — extract tags from a URL path. e.g. `/api/todos/42` → `[\"todos\", \"todo:42\"]`");
+        w("- `generateTagsFromMethod(method, url)` — method-prefixed tags. e.g. `post-todos`");
+        w("- `invalidateUrl(url)` — extract tags and invalidate all matching cache entries");
+        w("- `invalidateByMethod(method, url)` — invalidate using method-prefixed tags");
+        w("");
+        w("### `cache.ts` — Low-level invalidation");
+        w("```ts");
+        w(`import { invalidateByTag, invalidateByTags } from "./swoff/cache.${ext}";`);
+        w("");
+        w('await invalidateByTag("todos");');
+        w('await invalidateByTags(["todos", "categories"]);');
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `invalidateByTag(tag)` — invalidate a single tag. Dispatches `cache-invalidated` event.");
+        w("- `invalidateByTags(tags)` — invalidate multiple tags.");
+        w("");
+    }
+    // ── Cross-tab Sync ──
+    if (config.features.crossTabSync) {
+        wb("## 🔄 Cross-tab Sync — keep tabs in sync");
+        w("When the user opens your app in multiple browser tabs, changes in one tab (logout, mutation sync)");
+        w("are broadcast to all other tabs via the service worker.");
+        w("");
+        w("No separate imports needed — this is handled automatically by `client-injector.ts`.");
+        w("The service worker listens for invalidation events and forwards them to all clients.");
+        w("");
+        if (!config.features.tagInvalidation) {
+            w("> ⚠️ Cross-tab sync requires tag invalidation to be enabled for full functionality.");
+            w("");
+        }
+    }
+    // ── PWA ──
+    if (config.features.pwa.enabled) {
+        wb("## 📱 PWA — installable web app");
+        w("Swoff adds a beforeinstallprompt handler and install flow so users can install your app");
+        w("on their home screen.");
+        w("");
+        w("### `pwa/install.ts`");
+        w("```ts");
+        w(`import { setupPwaInstall, isInstallable, promptInstall } from "./swoff/pwa/install.${ext}";`);
+        w("");
+        w("setupPwaInstall(); // called automatically by client-injector.ts");
+        w("");
+        w("// Show install button when available");
+        w("if (isInstallable()) {");
+        w('  const { outcome } = await promptInstall();');
+        w("}");
+        w("```");
+        w("");
+        w("**Functions:**");
+        w("- `setupPwaInstall()` — listen for beforeinstallprompt/appinstalled events (called by client-injector)");
+        w("- `isInstallable()` — check if install prompt is available");
+        w("- `promptInstall()` — show the native install prompt");
+        w("");
+        w("### `manifest.json`");
+        w("Generated in `swoff/manifest.json`. If you want it exposed at the root, copy it to your `public/` directory.");
+        w("");
+        if (ctx.frameworkName === "react") {
+            w("### React Hooks");
+            w("- `usePWAUpdate()` — returns `{ updateStatus, progress, forceUpdate, acceptUpdate, dismissUpdate }`");
+            w("- `useSWProgress()` — returns `{ status, progress }` for download progress during SW update");
+            w("- `useCachedFetch(url, options?)` — fetches with auto-refetch on tag invalidation, see Fetch Wrapper section");
+            w("");
+        }
+    }
+    // ── Build Script ──
+    wb("## 🏗️ Build script");
+    w("The SW generator must run after every build to produce the final service worker file.");
+    w("Swoff has already added this to your `package.json` build script for you:");
+    w("```");
+    w('"build": "<your-build> && node swoff/sw/generator.js"');
+    w("```");
+    w("If you run `swoff clean`, this script suffix will be removed automatically.");
+    w("");
+    // ── Config file ──
+    wb("## ⚙️ swoff.config.json");
+    w("This is the configuration file that controls which features are enabled and how they behave.");
+    w("Re-run `npx @swoff/cli generate` after changing it.");
+    w("");
+    w("### Features you can toggle:");
+    w("- `mutationQueue` — offline write queue with IndexedDB");
+    w("- `backgroundSync` — Background Sync API (Chrome/Edge only)");
+    w("- `auth.enabled` — auth module (bearer/cookie/custom)");
+    w("- `crossTabSync` — broadcast changes across tabs");
+    w("- `tagInvalidation` — cache invalidation by tags");
+    w("- `clientRegistration` — SW registration with version management");
+    w("- `pwa.enabled` — PWA install prompt and manifest");
+    w("");
+    w("---");
+    writeFile(ctx, "GUIDE.md", lines.join("\n"));
+}
+//# sourceMappingURL=guide-generator.js.map

package/dist/lib/generators/file-generators/guide-generator.js.map

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

package/dist/lib/generators/file-generators/invalidation-tags.js

@@ -4,6 +4,9 @@
 import { writeFile } from "./context.js";
 export function generateInvalidationTags(ctx) {
     const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type} ` : " ");
     const code = `/**
  * Swoff Invalidation Tags Helper
  * URL-based tag generation from REST endpoints for automatic cache invalidation.
@@ -25,15 +28,15 @@ export function generateInvalidationTags(ctx) {
  *   await invalidateUrl("/api/todos/42");
  */
 
-import { invalidateByTag, invalidateByTags } from "./cache.${ext}";
+import { invalidateByTags } from "./cache.${ext}";
 
-export function generateTags(url) {
+/** Generate cache invalidation tags from a URL path. e.g. /api/todos/42 → ["todos", "todo:42"]. Used with fetchWithCache's tags option. */
+export function generateTags(url${T("string | URL")})${R("string[]")}{
   const parsed = typeof url === "string" ? new URL(url, window.location.origin) : url;
   const segments = parsed.pathname.split("/").filter(Boolean);
 
   if (segments.length === 0) return ["root"];
 
-  // Skip common API prefixes
   const skipPrefixes = ["api", "v1", "v2", "v3", "rest", "graphql", "gql"];
   let startIdx = 0;
   while (startIdx < segments.length && skipPrefixes.includes(segments[startIdx])) {
@@ -45,10 +48,8 @@ export function generateTags(url) {
 
   const tags = [];
 
-  // Collection tag: /api/todos -> "todos"
   tags.push(resourceSegments[0]);
 
-  // Resource tag: /api/todos/42 -> "todo:42"
   if (resourceSegments.length >= 2 && !isNaN(Number(resourceSegments[1]))) {
     const collection = resourceSegments[0];
     const id = resourceSegments[1];
@@ -56,7 +57,6 @@ export function generateTags(url) {
     tags.push(\`\${singular}:\${id}\`);
   }
 
-  // Sub-resource tags: /api/todos/42/comments -> "comments"
   for (let i = 2; i < resourceSegments.length; i++) {
     if (isNaN(Number(resourceSegments[i]))) {
       tags.push(resourceSegments[i]);
@@ -66,23 +66,25 @@ export function generateTags(url) {
   return tags;
 }
 
-export function generateTagsFromMethod(method, url) {
+/** Generate tags prefixed by HTTP method. e.g. POST /api/todos → ["post-todos"]. Useful for invalidating only mutation-tagged caches. */
+export function generateTagsFromMethod(method${T("string")}, url${T("string | URL")})${R("string[]")}{
   const tags = generateTags(url);
 
   if (method === "GET" || method === "HEAD") {
     return tags;
   }
 
-  // For mutations, add method prefix
   return tags.map((tag) => \`\${method.toLowerCase()}-\${tag}\`);
 }
 
-export async function invalidateUrl(url) {
+/** Invalidate cached responses related to a URL (extracts tags from the URL then calls invalidateByTags). */
+export async function invalidateUrl(url${T("string | URL")})${R("Promise<void>")}{
   const tags = generateTags(url);
   await invalidateByTags(tags);
 }
 
-export async function invalidateByMethod(method, url) {
+/** Invalidate cached responses tagged with method-prefixed tags from a URL. */
+export async function invalidateByMethod(method${T("string")}, url${T("string | URL")})${R("Promise<void>")}{
   const tags = generateTagsFromMethod(method, url);
   await invalidateByTags(tags);
 }

package/dist/lib/generators/file-generators/invalidation-tags.js.map

@@ -1 +1 @@
-{"version":3,"file":"invalidation-tags.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/invalidation-tags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,wBAAwB,CAAC,GAAqB;IAC5D,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,IAAI,GAAG;;;;;8EAK+D,GAAG;;;;;;;;;;;;;;;;6DAgBpB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D/D,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,qBAAqB,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"invalidation-tags.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/invalidation-tags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,wBAAwB,CAAC,GAAqB;IAC5D,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEtD,MAAM,IAAI,GAAG;;;;;8EAK+D,GAAG;;;;;;;;;;;;;;;;4CAgBrC,GAAG;;;kCAGb,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CAoCrB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;;;;;;;;;;;yCAW3D,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;;;iDAM/B,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;CAI1G,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,qBAAqB,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC"}