@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/pwa/workbox-strategies.d.ts

@@ -0,0 +1,100 @@
+import type { StxOptions } from '../types';
+/**
+ * Map stx strategy name to Workbox strategy
+ */
+export declare function mapStrategyToWorkbox(strategy: StxCacheStrategy): WorkboxStrategy;
+/**
+ * Get Workbox strategy class name
+ */
+export declare function getWorkboxStrategyName(strategy: StxCacheStrategy): string;
+/**
+ * Generate ExpirationPlugin config
+ */
+export declare function createExpirationPlugin(options: {
+  maxEntries?: number
+  maxAgeSeconds?: number
+  purgeOnQuotaError?: boolean
+}): WorkboxPlugin;
+/**
+ * Generate CacheableResponsePlugin config
+ */
+export declare function createCacheableResponsePlugin(options: {
+  statuses?: number[]
+  headers?: Record<string, string>
+}): WorkboxPlugin;
+/**
+ * Generate BackgroundSyncPlugin config
+ */
+export declare function createBackgroundSyncPlugin(options: {
+  name: string
+  maxRetentionTime?: number
+  forceSyncFallback?: boolean
+}): WorkboxPlugin;
+/**
+ * Convert stx route config to Workbox runtime caching config
+ */
+export declare function convertRouteToWorkbox(route: {
+  pattern: string
+  strategy: StxCacheStrategy
+  cacheName?: string
+  maxAgeSeconds?: number
+  maxEntries?: number
+}): RuntimeCachingConfig;
+/**
+ * Generate runtime caching configuration from stx routes
+ */
+export declare function generateRuntimeCaching(routes: Array<{
+    pattern: string
+    strategy: StxCacheStrategy
+    cacheName?: string
+    maxAgeSeconds?: number
+    maxEntries?: number
+  }>): RuntimeCachingConfig[];
+/**
+ * Generate runtime caching JavaScript code
+ */
+export declare function generateRuntimeCachingCode(options: StxOptions): string;
+/**
+ * Generate pattern matcher for Workbox registerRoute
+ */
+export declare function generatePatternMatcher(pattern: string): string;
+export declare interface WorkboxStrategy {
+  className: string
+  importFrom: 'workbox-strategies'
+  defaultPlugins?: WorkboxPlugin[]
+}
+export declare interface WorkboxPlugin {
+  className: string
+  importFrom: string
+  options?: Record<string, unknown>
+}
+export declare interface WorkboxRoute {
+  pattern: string
+  matchType: 'pathname' | 'destination' | 'custom'
+  strategy: WorkboxStrategy
+  plugins?: WorkboxPlugin[]
+  cacheName?: string
+}
+export declare interface RuntimeCachingConfig {
+  urlPattern: string | RegExp
+  handler: string
+  options?: {
+    cacheName?: string
+    plugins?: WorkboxPlugin[]
+    networkTimeoutSeconds?: number
+    matchOptions?: {
+      ignoreSearch?: boolean
+      ignoreMethod?: boolean
+      ignoreVary?: boolean
+    }
+  }
+  method?: string
+}
+// ============================================================================
+// Types
+// ============================================================================
+export type StxCacheStrategy = | 'cache-first'
+  | 'network-first'
+  | 'stale-while-revalidate'
+  | 'network-only'
+  | 'cache-only';

package/dist/pwa/workbox-strategies.js

@@ -0,0 +1,167 @@
+export function mapStrategyToWorkbox(strategy) {
+  const strategyMap = {
+    "cache-first": {
+      className: "CacheFirst",
+      importFrom: "workbox-strategies"
+    },
+    "network-first": {
+      className: "NetworkFirst",
+      importFrom: "workbox-strategies"
+    },
+    "stale-while-revalidate": {
+      className: "StaleWhileRevalidate",
+      importFrom: "workbox-strategies"
+    },
+    "network-only": {
+      className: "NetworkOnly",
+      importFrom: "workbox-strategies"
+    },
+    "cache-only": {
+      className: "CacheOnly",
+      importFrom: "workbox-strategies"
+    }
+  };
+  return strategyMap[strategy] || strategyMap["network-first"];
+}
+export function getWorkboxStrategyName(strategy) {
+  return mapStrategyToWorkbox(strategy).className;
+}
+export function createExpirationPlugin(options) {
+  return {
+    className: "ExpirationPlugin",
+    importFrom: "workbox-expiration",
+    options: {
+      ...options.maxEntries && { maxEntries: options.maxEntries },
+      ...options.maxAgeSeconds && { maxAgeSeconds: options.maxAgeSeconds },
+      ...options.purgeOnQuotaError !== void 0 && { purgeOnQuotaError: options.purgeOnQuotaError }
+    }
+  };
+}
+export function createCacheableResponsePlugin(options) {
+  return {
+    className: "CacheableResponsePlugin",
+    importFrom: "workbox-cacheable-response",
+    options: {
+      ...options.statuses && { statuses: options.statuses },
+      ...options.headers && { headers: options.headers }
+    }
+  };
+}
+export function createBackgroundSyncPlugin(options) {
+  return {
+    className: "BackgroundSyncPlugin",
+    importFrom: "workbox-background-sync",
+    options: {
+      name: options.name,
+      ...options.maxRetentionTime && { maxRetentionTime: options.maxRetentionTime },
+      ...options.forceSyncFallback !== void 0 && { forceSyncFallback: options.forceSyncFallback }
+    }
+  };
+}
+export function convertRouteToWorkbox(route) {
+  const workboxStrategy = mapStrategyToWorkbox(route.strategy), plugins = [];
+  if (route.maxAgeSeconds || route.maxEntries)
+    plugins.push(createExpirationPlugin({
+      maxAgeSeconds: route.maxAgeSeconds,
+      maxEntries: route.maxEntries,
+      purgeOnQuotaError: !0
+    }));
+  if (route.strategy === "network-first" || route.strategy === "stale-while-revalidate")
+    plugins.push(createCacheableResponsePlugin({
+      statuses: [0, 200]
+    }));
+  return {
+    urlPattern: route.pattern,
+    handler: workboxStrategy.className,
+    options: {
+      cacheName: route.cacheName,
+      ...plugins.length > 0 && { plugins }
+    }
+  };
+}
+export function generateRuntimeCaching(routes) {
+  return routes.map((route) => convertRouteToWorkbox(route));
+}
+export function generateRuntimeCachingCode(options) {
+  const pwa = options.pwa;
+  if (!pwa?.enabled)
+    return "";
+  const routes = pwa.routes || [], cacheStorage = pwa.cacheStorage, cacheConfigs = [];
+  for (const route of routes) {
+    const strategy = getWorkboxStrategyName(route.strategy), plugins = [];
+    if (route.maxAgeSeconds || route.maxEntries || cacheStorage?.maxEntries) {
+      const maxEntries = route.maxEntries || cacheStorage?.maxEntries || 100, maxAgeSeconds = route.maxAgeSeconds || (cacheStorage?.maxAge ? cacheStorage.maxAge * 24 * 60 * 60 : void 0);
+      plugins.push(`new ExpirationPlugin({
+      maxEntries: ${maxEntries},
+      ${maxAgeSeconds ? `maxAgeSeconds: ${maxAgeSeconds},` : ""}
+      purgeOnQuotaError: true,
+    })`);
+    }
+    if (route.strategy === "network-first" || route.strategy === "stale-while-revalidate")
+      plugins.push(`new CacheableResponsePlugin({
+      statuses: [0, 200],
+    })`);
+    const patternMatcher = generatePatternMatcher(route.pattern);
+    cacheConfigs.push(`
+// ${route.pattern}
+registerRoute(
+  ${patternMatcher},
+  new ${strategy}({
+    cacheName: '${route.cacheName || generateCacheName(route.pattern)}',
+    ${plugins.length > 0 ? `plugins: [
+      ${plugins.join(`,
+      `)}
+    ],` : ""}
+  })
+);`);
+  }
+  return cacheConfigs.join(`
+`);
+}
+export function generatePatternMatcher(pattern) {
+  if (pattern.startsWith("*.")) {
+    const ext = pattern.slice(2);
+    return `({ request }) => request.destination === '${getDestinationForExtension(ext)}'`;
+  }
+  if (pattern.endsWith("/**"))
+    return `({ url }) => url.pathname.startsWith('${pattern.slice(0, -3)}')`;
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -2);
+    return `({ url }) => url.pathname.startsWith('${prefix}') && !url.pathname.slice(${prefix.length + 1}).includes('/')`;
+  }
+  if (pattern.includes("*") && !pattern.startsWith("*")) {
+    const [prefix, suffix] = pattern.split("*");
+    return `({ url }) => url.pathname.startsWith('${prefix}') && url.pathname.endsWith('${suffix}')`;
+  }
+  if (pattern === "/" || !pattern.includes("*"))
+    return `({ url }) => url.pathname === '${pattern}'`;
+  return `new RegExp('${escapeRegex(pattern).replace(/\\\*/g, ".*")}')`;
+}
+function getDestinationForExtension(ext) {
+  return {
+    js: "script",
+    mjs: "script",
+    css: "style",
+    html: "document",
+    htm: "document",
+    png: "image",
+    jpg: "image",
+    jpeg: "image",
+    gif: "image",
+    svg: "image",
+    webp: "image",
+    avif: "image",
+    ico: "image",
+    woff: "font",
+    woff2: "font",
+    ttf: "font",
+    eot: "font",
+    otf: "font"
+  }[ext.toLowerCase()] || "empty";
+}
+function generateCacheName(pattern) {
+  return "stx-" + pattern.replace(/[^\w]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase().slice(0, 30) + "-cache";
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/pwa/workbox.d.ts

@@ -0,0 +1,51 @@
+import type { StxOptions } from '../types';
+/**
+ * Generate Workbox configuration from stx options
+ */
+export declare function generateWorkboxConfig(options: StxOptions, outputDir?: string): WorkboxConfig;
+/**
+ * Generate Workbox service worker JavaScript code
+ */
+export declare function generateWorkboxServiceWorker(options: StxOptions, outputDir?: string): string;
+/**
+ * Check if Workbox mode is enabled in config
+ */
+export declare function isWorkboxEnabled(options: StxOptions): boolean;
+/**
+ * Get the appropriate service worker generator based on config
+ */
+export declare function getServiceWorkerGenerator(options: StxOptions): (options: StxOptions, outputDir?: string) => string;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface WorkboxConfig {
+  mode: 'inject' | 'generate'
+  modules: WorkboxModule[]
+  precacheManifest?: PrecacheEntry[]
+  runtimeCaching?: RuntimeCacheRule[]
+  skipWaiting?: boolean
+  clientsClaim?: boolean
+  offlineFallback?: string
+  navigationPreload?: boolean
+  cacheVersion?: string
+}
+export declare interface WorkboxModule {
+  name: string
+  exports: string[]
+}
+export declare interface PrecacheEntry {
+  url: string
+  revision?: string | null
+}
+export declare interface RuntimeCacheRule {
+  urlPattern: string | RegExp
+  handler: string
+  options?: {
+    cacheName?: string
+    expiration?: {
+      maxEntries?: number
+      maxAgeSeconds?: number
+    }
+    networkTimeoutSeconds?: number
+  }
+}

package/dist/pwa/workbox.js

@@ -0,0 +1,382 @@
+var {require}=import.meta;import {
+  generateRuntimeCachingCode,
+  getWorkboxStrategyName
+} from "./workbox-strategies.js";
+import { generatePrecacheManifest, generatePrecacheManifestJs } from "./precache.js";
+export function generateWorkboxConfig(options, outputDir) {
+  const pwa = options.pwa;
+  if (!pwa?.enabled)
+    return {
+      mode: "generate",
+      modules: [],
+      skipWaiting: !0,
+      clientsClaim: !0
+    };
+  const swConfig = pwa.serviceWorker || {}, routes = pwa.routes || [], modules = [
+    {
+      name: "workbox-precaching",
+      exports: ["precacheAndRoute", "cleanupOutdatedCaches"]
+    },
+    {
+      name: "workbox-routing",
+      exports: ["registerRoute", "NavigationRoute", "setDefaultHandler"]
+    }
+  ], strategies = new Set;
+  for (const route of routes)
+    strategies.add(getWorkboxStrategyName(route.strategy));
+  if (strategies.size > 0)
+    modules.push({
+      name: "workbox-strategies",
+      exports: Array.from(strategies)
+    });
+  if (routes.some((r) => r.maxAgeSeconds || r.maxEntries) || pwa.cacheStorage)
+    modules.push({
+      name: "workbox-expiration",
+      exports: ["ExpirationPlugin"]
+    });
+  if (routes.some((r) => r.strategy === "network-first" || r.strategy === "stale-while-revalidate"))
+    modules.push({
+      name: "workbox-cacheable-response",
+      exports: ["CacheableResponsePlugin"]
+    });
+  if (pwa.backgroundSync?.enabled)
+    modules.push({
+      name: "workbox-background-sync",
+      exports: ["BackgroundSyncPlugin", "Queue"]
+    });
+  if (swConfig.navigationPreload)
+    modules.push({
+      name: "workbox-navigation-preload",
+      exports: ["enable"]
+    });
+  const precacheManifest = outputDir ? generatePrecacheManifest(outputDir, options) : void 0;
+  return {
+    mode: "generate",
+    modules,
+    precacheManifest: precacheManifest?.entries,
+    skipWaiting: swConfig.skipWaiting ?? !0,
+    clientsClaim: swConfig.clientsClaim ?? !0,
+    offlineFallback: pwa.offline?.enabled ? "/offline.html" : void 0,
+    navigationPreload: swConfig.navigationPreload ?? !1,
+    cacheVersion: swConfig.cacheVersion || "1.0.0"
+  };
+}
+export function generateWorkboxServiceWorker(options, outputDir) {
+  const pwa = options.pwa;
+  if (!pwa?.enabled)
+    return "";
+  const config = generateWorkboxConfig(options, outputDir), swConfig = pwa.serviceWorker || {}, pushConfig = pwa.push, syncConfig = pwa.backgroundSync, precacheManifest = outputDir ? generatePrecacheManifest(outputDir, options) : null, precacheManifestJs = precacheManifest ? generatePrecacheManifestJs(precacheManifest) : "[]", imports = generateWorkboxImports(config.modules), runtimeCaching = generateRuntimeCachingCode(options);
+  return `/**
+ * Service Worker - Generated by stx with Workbox
+ * Cache Version: ${config.cacheVersion}
+ *
+ * This service worker uses Google's Workbox library for robust caching.
+ * https://developers.google.com/web/tools/workbox
+ *
+ * Features:
+ * - Precaching with automatic revision management
+ * - Runtime caching with multiple strategies
+ * - Offline fallback support
+ * - Push notifications: ${pushConfig?.enabled ? "enabled" : "disabled"}
+ * - Background sync: ${syncConfig?.enabled ? "enabled" : "disabled"}
+ */
+
+// Import Workbox modules from CDN
+importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.0.0/workbox-sw.js');
+
+// Disable Workbox logging in production
+workbox.setConfig({ debug: true });
+
+// Extract modules from workbox global
+${imports}
+
+const CACHE_VERSION = '${config.cacheVersion}';
+const OFFLINE_PAGE = '${config.offlineFallback || "/offline.html"}';
+
+// ============================================================================
+// Precaching
+// ============================================================================
+
+// Clean up outdated caches from previous versions
+cleanupOutdatedCaches();
+
+// Precache static assets
+// The manifest is injected during build or defined below
+const PRECACHE_MANIFEST = ${precacheManifestJs};
+
+// Add essential assets
+PRECACHE_MANIFEST.push(
+  { url: '/', revision: CACHE_VERSION },
+  { url: '/manifest.json', revision: CACHE_VERSION },
+  ${config.offlineFallback ? `{ url: '${config.offlineFallback}', revision: CACHE_VERSION },` : ""}
+);
+
+// Precache and route all manifest entries
+precacheAndRoute(PRECACHE_MANIFEST);
+
+// ============================================================================
+// Navigation Preload
+// ============================================================================
+
+${config.navigationPreload ? `// Enable navigation preload for faster page loads
+enable();` : "// Navigation preload disabled"}
+
+// ============================================================================
+// Runtime Caching
+// ============================================================================
+
+${runtimeCaching}
+
+// ============================================================================
+// Offline Fallback
+// ============================================================================
+
+${config.offlineFallback ? `
+// Set up offline fallback for navigation requests
+const navigationRoute = new NavigationRoute(
+  new NetworkFirst({
+    cacheName: 'stx-pages-cache',
+    plugins: [
+      new CacheableResponsePlugin({ statuses: [0, 200] }),
+    ],
+  }),
+  {
+    // Return offline page when navigation fails
+    async allowedHandler(request) {
+      try {
+        const response = await this.handle(request);
+        return response;
+      }
+catch (error) {
+        const cache = await caches.open('stx-offline-cache');
+        return cache.match(OFFLINE_PAGE) || new Response('You are offline', {
+          status: 503,
+          statusText: 'Service Unavailable',
+        });
+      }
+    },
+  }
+);
+registerRoute(navigationRoute);
+` : "// No offline fallback configured"}
+
+// Default handler for unmatched requests
+setDefaultHandler(new NetworkFirst({
+  cacheName: 'stx-default-cache',
+  plugins: [
+    new CacheableResponsePlugin({ statuses: [0, 200] }),
+    new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 60 * 60 * 24 }), // 1 day
+  ],
+}));
+
+// ============================================================================
+// Service Worker Lifecycle
+// ============================================================================
+
+${config.skipWaiting ? `// Skip waiting - activate immediately
+self.skipWaiting();` : "// Manual skipWaiting - user must trigger update"}
+
+${config.clientsClaim ? `// Claim clients - take control immediately
+self.addEventListener('activate', () => {
+  self.clients.claim();
+});` : "// Manual clients claim"}
+
+// ============================================================================
+// Message Handling
+// ============================================================================
+
+self.addEventListener('message', (event) => {
+  const { type, payload } = event.data || {};
+
+  switch (type) {
+    case 'SKIP_WAITING':
+      self.skipWaiting();
+      break;
+
+    case 'GET_VERSION':
+      event.source?.postMessage({ type: 'VERSION', payload: CACHE_VERSION });
+      break;
+
+    case 'CACHE_URLS':
+      if (Array.isArray(payload)) {
+        event.waitUntil(
+          caches.open('stx-dynamic-cache').then(cache => cache.addAll(payload))
+        );
+      }
+      break;
+
+    case 'CLEAR_CACHE':
+      event.waitUntil(
+        caches.keys().then(names =>
+          Promise.all(names.map(name => caches.delete(name)))
+        )
+      );
+      break;
+  }
+});
+
+${pushConfig?.enabled ? generateWorkboxPushHandlers(pushConfig) : "// Push notifications disabled"}
+
+${syncConfig?.enabled ? generateWorkboxSyncHandlers(syncConfig) : "// Background sync disabled"}
+
+console.log('[Workbox SW] Service Worker loaded - Version:', CACHE_VERSION);
+`;
+}
+function generateWorkboxImports(modules) {
+  const lines = [];
+  for (const module of modules) {
+    const moduleName = module.name.replace("workbox-", "");
+    lines.push(`const { ${module.exports.join(", ")} } = workbox.${toCamelCase(moduleName)};`);
+  }
+  return lines.join(`
+`);
+}
+function toCamelCase(str) {
+  return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function generateWorkboxPushHandlers(pushConfig) {
+  return `
+// ============================================================================
+// Push Notifications
+// ============================================================================
+
+const PUSH_CONFIG = {
+  defaultIcon: '${pushConfig?.defaultIcon || "/pwa-icons/icon-192x192.png"}',
+  defaultBadge: '${pushConfig?.defaultBadge || "/pwa-icons/icon-72x72.png"}',
+};
+
+self.addEventListener('push', (event) => {
+  console.log('[Workbox SW] Push notification received');
+
+  let data = {
+    title: 'Notification',
+    body: 'You have a new notification',
+    icon: PUSH_CONFIG.defaultIcon,
+    badge: PUSH_CONFIG.defaultBadge,
+  };
+
+  if (event.data) {
+    try {
+      const payload = event.data.json();
+      data = { ...data, ...payload };
+    }
+catch {
+      data.body = event.data.text();
+    }
+  }
+
+  const options = {
+    body: data.body,
+    icon: data.icon || PUSH_CONFIG.defaultIcon,
+    badge: data.badge || PUSH_CONFIG.defaultBadge,
+    vibrate: data.vibrate || [100, 50, 100],
+    data: {
+      url: data.url || '/',
+      ...data.data,
+    },
+    actions: data.actions || [],
+    tag: data.tag,
+    renotify: data.renotify || false,
+    requireInteraction: data.requireInteraction || false,
+  };
+
+  event.waitUntil(
+    self.registration.showNotification(data.title, options)
+  );
+});
+
+self.addEventListener('notificationclick', (event) => {
+  console.log('[Workbox SW] Notification clicked');
+  event.notification.close();
+
+  const url = event.notification.data?.url || '/';
+
+  event.waitUntil(
+    clients.matchAll({ type: 'window', includeUncontrolled: true }).then(windowClients => {
+      for (const client of windowClients) {
+        if (client.url === url && 'focus' in client) {
+          return client.focus();
+        }
+      }
+      if (clients.openWindow) {
+        return clients.openWindow(url);
+      }
+    })
+  );
+});
+`;
+}
+function generateWorkboxSyncHandlers(syncConfig) {
+  return `
+// ============================================================================
+// Background Sync
+// ============================================================================
+
+const syncQueue = new Queue('${syncConfig?.queueName || "stx-sync-queue"}', {
+  maxRetentionTime: ${syncConfig?.maxRetentionMinutes || 1440}, // minutes
+  onSync: async ({ queue }) => {
+    let entry;
+    while ((entry = await queue.shiftRequest())) {
+      try {
+        await fetch(entry.request.clone());
+        console.log('[Workbox SW] Sync succeeded:', entry.request.url);
+
+        // Notify clients
+        const allClients = await self.clients.matchAll();
+        allClients.forEach(client => {
+          client.postMessage({
+            type: 'SYNC_COMPLETE',
+            url: entry.request.url,
+            success: true,
+          });
+        });
+      }
+catch (error) {
+        console.log('[Workbox SW] Sync failed, re-queuing:', entry.request.url);
+        await queue.unshiftRequest(entry);
+        throw error;
+      }
+    }
+  },
+});
+
+// Register routes that should use background sync
+${syncConfig?.endpoints?.map((endpoint) => `
+registerRoute(
+  ({ url }) => url.pathname.startsWith('${endpoint}'),
+  new NetworkOnly({
+    plugins: [
+      new BackgroundSyncPlugin('${syncConfig?.queueName || "stx-sync-queue"}', {
+        maxRetentionTime: ${syncConfig?.maxRetentionMinutes || 1440},
+      }),
+    ],
+  }),
+  'POST'
+);`).join(`
+`) || "// No background sync endpoints configured"}
+
+// Handle form sync messages
+self.addEventListener('message', (event) => {
+  if (event.data?.type === 'REGISTER_FORM_SYNC') {
+    const { action, method, data } = event.data.payload;
+
+    const request = new Request(action, {
+      method: method || 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(data).toString(),
+    });
+
+    event.waitUntil(syncQueue.pushRequest({ request }));
+  }
+});
+`;
+}
+export function isWorkboxEnabled(options) {
+  return options.pwa?.enabled === !0 && options.pwa?.serviceWorker?.useWorkbox === !0;
+}
+export function getServiceWorkerGenerator(options) {
+  if (isWorkboxEnabled(options))
+    return generateWorkboxServiceWorker;
+  const { generateServiceWorker } = require("./service-worker");
+  return generateServiceWorker;
+}