@sweidos/eidos 1.0.16 → 1.0.17

package/README.md

@@ -145,6 +145,15 @@ const handle = resource('/api/products', {
   cacheName?: string,      // custom Cache Storage bucket (default: 'eidos-resources-v1')
   maxAge?: number,         // TTL in ms — expired entries are re-fetched from network
 })
+
+// URL patterns — SW intercepts all matching requests automatically
+resource('/api/products/*',   { offline: true })  // single segment: /api/products/123
+resource('/api/products/**',  { offline: true })  // multi-segment:  /api/products/123/reviews
+resource('/api/users/:id',    { offline: true })  // named segment:  /api/users/abc
+
+// Cross-origin resources — pass the full URL (including origin)
+resource('https://api.example.com/products', { offline: true })
+resource('https://cdn.example.com/assets/*', { offline: true })  // patterns work too
 ```
 
 **Auto-selected strategy:**
@@ -287,6 +296,79 @@ const state = useEidos()
 
 ---
 
+### Vue / Svelte / Vanilla JS Stores
+
+Framework-agnostic reactive stores — no React dependency, zero extra peer deps. These implement the [Svelte store contract](https://svelte.dev/docs/svelte-components#script-4-prefix-stores-with-$-to-access-their-values) (`subscribe(run): unsubscribe`) so they work natively with Svelte's `$` prefix. They also wire up cleanly in Vue composables and plain JS.
+
+```ts
+import {
+  eidosQueue, eidosStatus, eidosQueueStats,
+  eidosResource, eidosAction, eidosStore,
+} from '@sweidos/eidos'
+```
+
+**Svelte:**
+
+```svelte
+<script>
+  import { eidosQueue, eidosStatus, eidosQueueStats, eidosResource } from '@sweidos/eidos'
+  // Use $ prefix — Svelte auto-subscribes and unsubscribes
+</script>
+
+<p>Online: {$eidosStatus.isOnline}</p>
+<p>Pending: {$eidosQueueStats.pending}</p>
+<p>Cache hits: {$eidosResource('/api/products')?.cacheHits ?? 0}</p>
+
+{#each $eidosQueue as item}
+  <div>{item.actionName} — {item.status}</div>
+{/each}
+```
+
+**Vue (Composition API):**
+
+```ts
+import { ref, onUnmounted } from 'vue'
+import { eidosStatus, eidosQueue } from '@sweidos/eidos'
+
+export function useEidosStatusVue() {
+  const status = ref(eidosStatus.getState())
+  const unsub  = eidosStatus.subscribe((v) => { status.value = v })
+  onUnmounted(unsub)
+  return status
+}
+
+export function useEidosQueueVue() {
+  const queue = ref(eidosQueue.getState())
+  const unsub = eidosQueue.subscribe((v) => { queue.value = v })
+  onUnmounted(unsub)
+  return queue
+}
+```
+
+**Vanilla JS:**
+
+```ts
+import { eidosStatus, eidosResource } from '@sweidos/eidos'
+
+const unsub = eidosStatus.subscribe(({ isOnline }) => {
+  document.title = isOnline ? 'App' : 'App (offline)'
+})
+
+// Read current value once without subscribing
+const hits = eidosResource('/api/products').getState()?.cacheHits ?? 0
+```
+
+| Store | Type | Emits when |
+|-------|------|-----------|
+| `eidosQueue` | `ActionQueueItem[]` | Any queue mutation |
+| `eidosStatus` | `{ isOnline, swStatus, swError }` | Online or SW status changes |
+| `eidosQueueStats` | `{ pending, failed, replaying, total }` | Any queue mutation |
+| `eidosResource(url)` | `ResourceEntry \| undefined` | Resource registered or updated |
+| `eidosAction(id)` | `ActionQueueItem \| undefined` | Item status changes or removal |
+| `eidosStore` | `EidosStore` | Any state change |
+
+---
+
 ### `setOfflineSimulation(enabled)`
 
 Toggle offline simulation without physically disconnecting the network.
@@ -300,6 +382,21 @@ setOfflineSimulation(false)  // restore normal behaviour
 
 ---
 
+### `isBgSyncSupported()`
+
+Returns `true` when the active SW registration supports the Background Sync API (Chrome 49+, Edge 79+, Safari 16+). Use to conditionally surface sync status in your UI.
+
+```ts
+import { isBgSyncSupported } from '@sweidos/eidos'
+
+if (isBgSyncSupported()) {
+  // browser will fire 'eidos-queue-replay' sync tag when connectivity returns,
+  // even if the user briefly navigated away from the page
+}
+```
+
+---
+
 ## Performance
 
 Performance is a first-class concern in Eidos. Every design decision optimises for low overhead.
@@ -369,6 +466,7 @@ Performance is a first-class concern in Eidos. Every design decision optimises f
 | `EIDOS_CACHE_UPDATED` | Cache entry refreshed from network |
 | `EIDOS_NETWORK_ERROR` | Network request failed |
 | `EIDOS_CACHE_CLEARED` | Cache was cleared |
+| `EIDOS_BACKGROUND_SYNC` | Browser fired `sync` event — runtime calls `replayQueue()` |
 
 ---
 
@@ -428,7 +526,7 @@ function eidosPlugin() {
 | Limitation | Detail |
 |------------|--------|
 | GET-only caching | SW intercepts `GET` only. `POST`/`PUT`/`DELETE` are not cached (but *are* queued via `action()`). |
-| Pathname matching | Resources match by pathname. `/api/products?page=2` and `/api/products` share the same SW rule but are cached separately. |
+| Query string ignored | Resources match by pathname (or full URL for cross-origin). `/api/products?page=2` and `/api/products` share the same SW rule but are cached as separate entries. |
 | Module-scope actions | `action()` must be called at module scope so functions are registered before a page reload triggers queue replay. |
 | Single SW | `EidosProvider` assumes one SW at `/eidos-sw.js`. Multiple registrations are unsupported. |
 
@@ -440,11 +538,11 @@ function eidosPlugin() {
 - [x] Exponential backoff with jitter for queue replay
 - [x] Per-resource `cacheName` override
 - [x] `resource.unregister()` for cleanup
-- [ ] URL pattern matching (wildcards, regex)
-- [ ] Cross-origin resource support
-- [ ] Background Sync API integration
+- [x] URL pattern matching (`*`, `**`, `:param`)
+- [x] Cross-origin resource support
+- [x] Background Sync API integration
 - [ ] Vite plugin (first-class, published separately)
-- [ ] Vue / Svelte bindings
+- [x] Vue / Svelte bindings (framework-agnostic reactive stores)
 - [ ] TanStack Query integration package
 
 ---

package/dist/eidos-sw.js

@@ -1,229 +1,213 @@
-// eidos-sw.js — Eidos Service Worker v0.1.0
-// Two responsibilities:
-//   1. App shell caching — dashboard works offline after first visit
-//   2. API resource caching — strategies declared via resource()
-
-const CACHE_VERSION = 'v1'
-const SHELL_CACHE   = `eidos-shell-${CACHE_VERSION}`
-const API_CACHE     = `eidos-resources-${CACHE_VERSION}`
-
+const CACHE_VERSION = "v1";
+const CACHE_PREFIX = "eidos";
 const runtimeConfig = {
-  resources: new Map(),   // pathname → { strategy, cacheName }
-  simulateOffline: false,
-}
-
-// ── Install ───────────────────────────────────────────────────────────────────
-
-self.addEventListener('install', (event) => {
-  event.waitUntil(self.skipWaiting())
-})
-
-// ── Activate ──────────────────────────────────────────────────────────────────
-
-self.addEventListener('activate', (event) => {
+  resources: /* @__PURE__ */ new Map(),
+  simulateOffline: false
+};
+self.addEventListener("install", (event) => {
+  event.waitUntil(self.skipWaiting());
+});
+self.addEventListener("activate", (event) => {
   event.waitUntil(
     Promise.all([
       self.clients.claim(),
-      caches.keys().then((keys) =>
-        Promise.all(
-          keys
-            .filter((k) => k.startsWith('eidos') && k !== SHELL_CACHE && k !== API_CACHE)
-            .map((k) => caches.delete(k))
+      // Purge stale caches from previous versions
+      caches.keys().then(
+        (keys) => Promise.all(
+          keys.filter((k) => k.startsWith(CACHE_PREFIX) && !k.endsWith(CACHE_VERSION)).map((k) => caches.delete(k))
         )
-      ),
+      )
     ])
-  )
-})
-
-// ── Message channel ───────────────────────────────────────────────────────────
-
-self.addEventListener('message', (event) => {
-  const data = event.data
-  if (!data?.type) return
-
+  );
+});
+self.addEventListener("message", (event) => {
+  const data = event.data;
+  if (!data?.type) return;
   switch (data.type) {
-    case 'EIDOS_REGISTER_RESOURCE':
-      runtimeConfig.resources.set(data.url, {
+    case "EIDOS_REGISTER_RESOURCE": {
+      const url = data.url;
+      const patternSrc = data.pattern;
+      runtimeConfig.resources.set(url, {
         strategy: data.strategy,
-        cacheName: data.cacheName ?? API_CACHE,
-      })
-      event.source?.postMessage({ type: 'EIDOS_RESOURCE_REGISTERED', url: data.url })
-      break
-
-    case 'EIDOS_UNREGISTER_RESOURCE':
-      runtimeConfig.resources.delete(data.url)
-      break
-
-    case 'EIDOS_SIMULATE_OFFLINE':
-      runtimeConfig.simulateOffline = data.enabled
-      break
-
-    case 'EIDOS_CLEAR_CACHE': {
-      caches.open(API_CACHE).then(async (cache) => {
-        if (data.url) {
-          const keys = await cache.keys()
+        cacheName: data.cacheName ?? `${CACHE_PREFIX}-resources-${CACHE_VERSION}`,
+        ...patternSrc !== void 0 && { pattern: new RegExp(patternSrc) }
+      });
+      event.source?.postMessage({ type: "EIDOS_RESOURCE_REGISTERED", url });
+      break;
+    }
+    case "EIDOS_UNREGISTER_RESOURCE": {
+      runtimeConfig.resources.delete(data.url);
+      break;
+    }
+    case "EIDOS_SIMULATE_OFFLINE": {
+      runtimeConfig.simulateOffline = data.enabled;
+      break;
+    }
+    case "EIDOS_CLEAR_CACHE": {
+      const targetUrl = data.url;
+      const reg = targetUrl ? runtimeConfig.resources.get(targetUrl) : void 0;
+      const cacheName = reg?.cacheName ?? `${CACHE_PREFIX}-resources-${CACHE_VERSION}`;
+      caches.open(cacheName).then(async (cache) => {
+        if (targetUrl) {
+          const keys = await cache.keys();
+          const isCrossOrigin = targetUrl.startsWith("http");
           await Promise.all(
-            keys.filter((r) => new URL(r.url).pathname === data.url).map((r) => cache.delete(r))
-          )
+            keys.filter((req) => {
+              const reqUrl = req.url;
+              const p = new URL(reqUrl).pathname;
+              if (reg?.pattern) {
+                return reg.pattern.test(isCrossOrigin ? reqUrl : p);
+              }
+              return isCrossOrigin ? reqUrl === targetUrl : p === targetUrl;
+            }).map((req) => cache.delete(req))
+          );
         } else {
-          const keys = await cache.keys()
-          await Promise.all(keys.map((k) => cache.delete(k)))
+          await cache.keys().then((keys) => Promise.all(keys.map((k) => cache.delete(k))));
         }
-        notifyClients({ type: 'EIDOS_CACHE_CLEARED', url: data.url })
-      })
-      break
+        notifyClients({ type: "EIDOS_CACHE_CLEARED", url: targetUrl });
+      });
+      break;
     }
-
-    case 'EIDOS_PING':
-      event.source?.postMessage({ type: 'EIDOS_PONG' })
-      break
+    case "EIDOS_PING":
+      event.source?.postMessage({ type: "EIDOS_PONG" });
+      break;
   }
-})
-
-// ── Fetch interception ────────────────────────────────────────────────────────
-
-self.addEventListener('fetch', (event) => {
-  if (event.request.method !== 'GET') return
-
-  const url      = new URL(event.request.url)
-  const pathname = url.pathname
-
-  // 1. Registered API resources
-  const reg = runtimeConfig.resources.get(pathname)
-  if (reg) {
-    event.respondWith(handleApiResource(event.request, pathname, reg))
-    return
+});
+self.addEventListener("fetch", (event) => {
+  if (event.request.method !== "GET") return;
+  const requestUrl = event.request.url;
+  const pathname = new URL(requestUrl).pathname;
+  let reg = runtimeConfig.resources.get(requestUrl) ?? runtimeConfig.resources.get(pathname);
+  if (!reg) {
+    for (const [key, registration] of runtimeConfig.resources) {
+      if (!registration.pattern) continue;
+      const target = key.startsWith("http") ? requestUrl : pathname;
+      if (registration.pattern.test(target)) {
+        reg = registration;
+        break;
+      }
+    }
   }
-
-  // 2. App shell — same-origin non-API assets (HTML, JS, CSS, fonts, images)
-  //    Stale-while-revalidate: serve from cache instantly, refresh in background.
-  if (url.origin === self.location.origin && !pathname.startsWith('/api/')) {
-    event.respondWith(appShell(event.request))
+  if (!reg) return;
+  if (reg.strategy === "stale-while-revalidate" && !runtimeConfig.simulateOffline) {
+    event.respondWith(staleWhileRevalidate(event, event.request, pathname, reg.cacheName));
+    return;
   }
-})
-
-// ── App shell strategy ────────────────────────────────────────────────────────
-
-async function appShell(request) {
-  const cache  = await caches.open(SHELL_CACHE)
-  const cached = await cache.match(request)
-
-  const refresh = fetch(request)
-    .then((resp) => {
-      if (resp.ok) cache.put(request, resp.clone())
-      return resp
-    })
-    .catch(() => null)
-
-  if (cached) {
-    refresh // update in background
-    return cached
+  event.respondWith(handleFetch(event.request, pathname, reg));
+});
+async function handleFetch(request, pathname, reg) {
+  if (runtimeConfig.simulateOffline) {
+    return serveOffline(request, pathname, reg.cacheName);
   }
-
-  const fresh = await refresh
-  return fresh ?? new Response(
-    '<html><body><h2>Offline</h2><p>Visit this page while online first.</p></body></html>',
-    { status: 503, headers: { 'Content-Type': 'text/html' } }
-  )
-}
-
-// ── API caching strategies ────────────────────────────────────────────────────
-
-async function handleApiResource(request, pathname, reg) {
-  if (runtimeConfig.simulateOffline) return serveOffline(request, pathname, reg.cacheName)
-
   switch (reg.strategy) {
-    case 'cache-first':            return cacheFirst(request, pathname, reg.cacheName)
-    case 'stale-while-revalidate': return staleWhileRevalidate(request, pathname, reg.cacheName)
-    case 'network-first':          return networkFirst(request, pathname, reg.cacheName)
-    default:                       return fetch(request)
+    case "cache-first":
+      return cacheFirst(request, pathname, reg.cacheName);
+    case "stale-while-revalidate":
+      return staleWhileRevalidate(null, request, pathname, reg.cacheName);
+    case "network-first":
+      return networkFirst(request, pathname, reg.cacheName);
+    default:
+      return fetch(request);
   }
 }
-
 async function cacheFirst(request, pathname, cacheName) {
-  const cache  = await caches.open(cacheName)
-  const cached = await cache.match(request)
+  const cache = await caches.open(cacheName);
+  const cached = await cache.match(request);
   if (cached) {
-    notifyClients({ type: 'EIDOS_CACHE_HIT', url: pathname, strategy: 'cache-first' })
-    return cached
+    notifyClients({ type: "EIDOS_CACHE_HIT", url: pathname, strategy: "cache-first" });
+    return cached;
   }
   try {
-    const response = await fetch(request)
+    const response = await fetch(request);
     if (response.ok) {
-      await cache.put(request, response.clone())
-      notifyClients({ type: 'EIDOS_CACHE_UPDATED', url: pathname, strategy: 'cache-first' })
+      await cache.put(request, response.clone());
+      notifyClients({ type: "EIDOS_CACHE_UPDATED", url: pathname, strategy: "cache-first" });
     }
-    return response
+    return response;
   } catch {
-    notifyClients({ type: 'EIDOS_NETWORK_ERROR', url: pathname })
-    return offlineErrorResponse(pathname)
+    notifyClients({ type: "EIDOS_NETWORK_ERROR", url: pathname });
+    return offlineErrorResponse(pathname);
   }
 }
-
-async function staleWhileRevalidate(request, pathname, cacheName) {
-  const cache  = await caches.open(cacheName)
-  const cached = await cache.match(request)
-
-  const revalidate = fetch(request)
-    .then(async (resp) => {
-      if (resp.ok) {
-        await cache.put(request, resp.clone())
-        notifyClients({ type: 'EIDOS_CACHE_UPDATED', url: pathname, strategy: 'stale-while-revalidate' })
-      }
-      return resp
-    })
-    .catch(() => {
-      notifyClients({ type: 'EIDOS_NETWORK_ERROR', url: pathname })
-      return null
-    })
-
+async function staleWhileRevalidate(event, request, pathname, cacheName) {
+  const cache = await caches.open(cacheName);
+  const cached = await cache.match(request);
+  const revalidatePromise = fetch(request).then(async (response) => {
+    if (response.ok) {
+      await cache.put(request, response.clone());
+      notifyClients({
+        type: "EIDOS_CACHE_UPDATED",
+        url: pathname,
+        strategy: "stale-while-revalidate"
+      });
+    }
+    return response;
+  }).catch(() => {
+    notifyClients({ type: "EIDOS_NETWORK_ERROR", url: pathname, strategy: "stale-while-revalidate" });
+  });
   if (cached) {
-    notifyClients({ type: 'EIDOS_CACHE_HIT', url: pathname, strategy: 'stale-while-revalidate' })
-    return cached
+    event?.waitUntil(revalidatePromise);
+    notifyClients({
+      type: "EIDOS_CACHE_HIT",
+      url: pathname,
+      strategy: "stale-while-revalidate"
+    });
+    return cached;
   }
-
-  const fresh = await revalidate
-  return fresh ?? offlineErrorResponse(pathname)
+  const fresh = await revalidatePromise;
+  return fresh ?? offlineErrorResponse(pathname);
 }
-
 async function networkFirst(request, pathname, cacheName) {
-  const cache = await caches.open(cacheName)
+  const cache = await caches.open(cacheName);
   try {
-    const response = await fetch(request)
+    const response = await fetch(request, { signal: AbortSignal.timeout(3e3) });
     if (response.ok) {
-      await cache.put(request, response.clone())
-      notifyClients({ type: 'EIDOS_CACHE_UPDATED', url: pathname, strategy: 'network-first' })
+      await cache.put(request, response.clone());
+      notifyClients({ type: "EIDOS_CACHE_UPDATED", url: pathname, strategy: "network-first" });
     }
-    return response
+    return response;
   } catch {
-    const cached = await cache.match(request)
+    const cached = await cache.match(request);
     if (cached) {
-      notifyClients({ type: 'EIDOS_CACHE_HIT', url: pathname, strategy: 'network-first' })
-      return cached
+      notifyClients({ type: "EIDOS_CACHE_HIT", url: pathname, strategy: "network-first" });
+      return cached;
     }
-    notifyClients({ type: 'EIDOS_NETWORK_ERROR', url: pathname })
-    return offlineErrorResponse(pathname)
+    notifyClients({ type: "EIDOS_NETWORK_ERROR", url: pathname });
+    return offlineErrorResponse(pathname);
   }
 }
-
 async function serveOffline(request, pathname, cacheName) {
-  const cache  = await caches.open(cacheName)
-  const cached = await cache.match(request)
+  const cache = await caches.open(cacheName);
+  const cached = await cache.match(request);
   if (cached) {
-    notifyClients({ type: 'EIDOS_CACHE_HIT', url: pathname, strategy: 'offline-simulation', simulated: true })
-    return cached
+    notifyClients({ type: "EIDOS_CACHE_HIT", url: pathname, strategy: "offline-simulation", simulated: true });
+    return cached;
   }
-  return offlineErrorResponse(pathname)
+  return offlineErrorResponse(pathname);
 }
-
 function offlineErrorResponse(pathname) {
   return new Response(
-    JSON.stringify({ error: 'offline', message: `No cached response for ${pathname}`, eidos: true }),
-    { status: 503, headers: { 'Content-Type': 'application/json', 'X-Eidos-Offline': 'true' } }
-  )
+    JSON.stringify({
+      error: "offline",
+      message: `No cached response available for ${pathname}`,
+      eidos: true
+    }),
+    {
+      status: 503,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Eidos-Offline": "true"
+      }
+    }
+  );
 }
-
 async function notifyClients(message) {
-  const clients = await self.clients.matchAll({ includeUncontrolled: true })
-  clients.forEach((c) => c.postMessage(message))
+  const clients = await self.clients.matchAll({ includeUncontrolled: true });
+  clients.forEach((client) => client.postMessage(message));
 }
+self.addEventListener("sync", (event) => {
+  const syncEvent = event;
+  if (syncEvent.tag === "eidos-queue-replay") {
+    syncEvent.waitUntil(notifyClients({ type: "EIDOS_BACKGROUND_SYNC" }));
+  }
+});

package/dist/eidos.cjs.js

@@ -58,6 +58,9 @@ const useEidosStore = {
 };
 let _registration = null;
 let _pendingMessages = [];
+function getSwRegistration() {
+  return _registration;
+}
 async function registerServiceWorker(swPath) {
   if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
     useEidosStore.getState().setSwStatus("unsupported");
@@ -106,11 +109,26 @@ function sendToWorker(message) {
     _pendingMessages.push(message);
   }
 }
+let _bgSyncHandler = null;
+function registerBgSyncHandler(fn) {
+  _bgSyncHandler = fn;
+}
+function isBgSyncSupported() {
+  try {
+    return typeof navigator !== "undefined" && "serviceWorker" in navigator && _registration !== null && "sync" in _registration;
+  } catch {
+    return false;
+  }
+}
 function onSwMessage(event) {
   const data = event.data;
   if (!(data == null ? void 0 : data.type)) return;
   const store = useEidosStore.getState();
   const { type, url } = data;
+  if (type === "EIDOS_BACKGROUND_SYNC") {
+    _bgSyncHandler == null ? void 0 : _bgSyncHandler();
+    return;
+  }
   if (!url) return;
   switch (type) {
     case "EIDOS_CACHE_HIT": {
@@ -512,6 +530,13 @@ async function persistAndQueue(actionId, actionName, args, config) {
   };
   await idbAddToQueue(item);
   useEidosStore.getState().addQueueItem(item);
+  try {
+    const reg = getSwRegistration();
+    if (reg && "sync" in reg) {
+      await reg.sync.register("eidos-queue-replay");
+    }
+  } catch {
+  }
   return {
     queued: true,
     id,
@@ -605,6 +630,11 @@ async function initEidos(config = {}) {
     await registerServiceWorker(swPath);
   } catch {
   }
+  registerBgSyncHandler(() => {
+    if (useEidosStore.getState().isOnline) {
+      setTimeout(replayQueue, 200);
+    }
+  });
   if (autoReplay) {
     let prevIsOnline = useEidosStore.getState().isOnline;
     useEidosStore.subscribe(() => {
@@ -711,6 +741,7 @@ exports.eidosResource = eidosResource;
 exports.eidosStatus = eidosStatus;
 exports.eidosStore = eidosStore;
 exports.initEidos = initEidos;
+exports.isBgSyncSupported = isBgSyncSupported;
 exports.replayQueue = replayQueue;
 exports.resource = resource;
 exports.setOfflineSimulation = setOfflineSimulation;