@sweidos/eidos 1.1.0 → 2.0.0

package/README.md

@@ -114,20 +114,22 @@ if ('queued' in result) {
 
 ## What you get
 
-| Feature                     | Description                                                                          |
-| --------------------------- | ------------------------------------------------------------------------------------ |
-| **Auto strategy selection** | `offline: true` → StaleWhileRevalidate. No config needed. Override when you want.    |
-| **Persistent action queue** | Failed writes go to IndexedDB and replay with exponential backoff on reconnect.      |
-| **Request deduplication**   | Concurrent `resource.fetch()` calls share one in-flight request.                     |
-| **Optimistic updates**      | `onOptimistic` / `onRollback` callbacks for instant UI feedback.                     |
-| **Conflict resolution**     | `onConflict` decides per 4xx whether to retry or drop a queued action.               |
-| **Queue prioritization**    | `priority: 'high' \| 'normal' \| 'low'` — high items replay before normal.           |
-| **Cache warming**           | `warmCache(handles[])` bulk-prefetches resources on login/init.                      |
-| **URL patterns**            | `/api/products/*`, `/api/users/:id`, `**` wildcards — SW intercepts all matches.     |
-| **Background Sync**         | Registers a `sync` tag so queued actions replay even after tab close.                |
-| **Devtools panel**          | `<EidosDevtools />` — live queue, cache state, offline toggle, no CSS import.        |
-| **Testing helpers**         | `mockOffline`, `drainQueue`, `resetEidos`, `getCachedEntry` for Vitest/Jest.         |
-| **OpenAPI codegen**         | `npx eidos-gen openapi.json` generates typed `resource()` + `action()` declarations. |
+| Feature                     | Description                                                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Auto strategy selection** | `offline: true` → StaleWhileRevalidate. No config needed. Override when you want.                                           |
+| **Persistent action queue** | Failed writes go to IndexedDB and replay with exponential backoff on reconnect.                                             |
+| **Request deduplication**   | Concurrent `resource.fetch()` calls share one in-flight request.                                                            |
+| **Optimistic updates**      | `onOptimistic` / `onRollback` callbacks for instant UI feedback.                                                            |
+| **Conflict resolution**     | `conflict: { strategy: 'serverWins' \| 'clientWins' \| 'merge' \| 'custom' }` on 4xx replay responses.                      |
+| **Idempotent replay**       | Stable `idempotencyKey` per invocation, forwarded to `fn` via `ActionContext` — safe retries even after a dropped response. |
+| **Cancellable actions**     | `cancellable: true` → `AbortSignal` per call, plus `handle.cancel(idempotencyKey)`.                                         |
+| **Queue prioritization**    | `priority: 'high' \| 'normal' \| 'low'` — high items replay before normal.                                                  |
+| **Cache warming**           | `warmCache(handles[])` bulk-prefetches resources on login/init.                                                             |
+| **URL patterns**            | `/api/products/*`, `/api/users/:id`, `**` wildcards — SW intercepts all matches.                                            |
+| **Background Sync**         | Registers a `sync` tag so queued actions replay even after tab close.                                                       |
+| **Devtools panel**          | `<EidosDevtools />` — live queue, cache state, offline toggle, no CSS import.                                               |
+| **Testing helpers**         | `mockOffline`, `drainQueue`, `resetEidos`, `getCachedEntry` for Vitest/Jest.                                                |
+| **OpenAPI codegen**         | `npx eidos-gen openapi.json` generates typed `resource()` + `action()` declarations.                                        |
 
 ---
 
@@ -175,20 +177,40 @@ products.query()                 // { queryKey, queryFn } for useQuery
 | `offline: true, strategy: 'cache-first'`   | CacheFirst           | Static assets, config data          |
 | `offline: true, strategy: 'network-first'` | NetworkFirst         | Always-fresh with offline fallback  |
 
-URL patterns work on any handle: `/api/products/*`, `/api/users/:id`, `**`
+### `resourcePattern(pattern, config)`
+
+For URL patterns — `/api/products/*`, `/api/users/:id`, `**` — the SW intercepts
+all matching requests automatically, so there's no single URL to fetch. Use
+`resourcePattern()` instead of `resource()`; it returns a handle with only
+`invalidate()` and `unregister()`:
+
+```ts
+const productPattern = resourcePattern('/api/products/*', { offline: true });
+
+await productPattern.invalidate(); // clear all cached entries matching the pattern
+productPattern.unregister();
+```
 
 ### `action(fn, config)`
 
 ```ts
-const createOrder = action(async (payload: OrderPayload) => { ... }, {
+const createOrder = action(async (payload: OrderPayload, ctx: ActionContext) => { ... }, {
   reliability: 'neverLose', // persist to IDB + replay on reconnect
   name: 'createOrder',      // stable name for post-reload replay
+  namespace?: string,       // prefix actionId — avoids collisions across modules
   maxRetries?: number,      // default: 3
   priority?: 'high' | 'normal' | 'low',
+  cancellable?: boolean,    // adds AbortSignal to ctx, enables handle.cancel(key)
   onOptimistic?: (...args) => void, // instant UI update
   onRollback?: (...args) => void,   // revert on permanent failure
-  onConflict?: (error, args) => 'retry' | 'skip', // 4xx handler
+  conflict?: {               // 4xx replay handling
+    strategy: 'serverWins' | 'clientWins' | 'merge' | 'custom',
+    resolve?: (ctx) => 'retry' | 'skip' | { resolved: args },
+  },
 })
+
+// ctx.idempotencyKey is stable across retries — forward as e.g. an
+// `Idempotency-Key` header so the server can dedupe replayed writes.
 ```
 
 ### React hooks
@@ -233,6 +255,81 @@ const mutation = useEidosMutation(createOrder, {
 
 ---
 
+## Push Notifications
+
+Headless, framework-agnostic Web Push. Tree-shaken via a separate subpath — adds zero bytes unless imported.
+
+**1. Generate VAPID keys (one-time):**
+
+```sh
+npx @sweidos/eidos generate-vapid-keys
+```
+
+Detects your framework (Vite/Next/SvelteKit/Nuxt) and writes a correctly-prefixed
+public key + an unprefixed private key to `.env.local`:
+
+```
+VITE_EIDOS_VAPID_PUBLIC_KEY=...
+EIDOS_VAPID_PRIVATE_KEY=...
+```
+
+Give `EIDOS_VAPID_PRIVATE_KEY` (and the public key) to your backend. What the
+backend does with them — language, storage, send timing — is entirely its own
+concern; Eidos never talks to it directly.
+
+**2. Register handlers once at app init (any tab, no permission prompt):**
+
+```ts
+import { registerPushHandlers } from '@sweidos/eidos/push';
+
+registerPushHandlers({
+  onNotificationClick: (data) => router.push(data.url),
+  onSubscriptionExpired: (sub) =>
+    fetch('/api/push-subscribe', { method: 'POST', body: JSON.stringify(sub) }),
+});
+```
+
+**3. Subscribe from a user gesture (e.g. an "Enable notifications" button):**
+
+```ts
+import { subscribeToPush, isPushSupported, getPushPermissionState } from '@sweidos/eidos/push';
+
+async function onEnableClick() {
+  const result = await subscribeToPush({
+    vapidPublicKey: import.meta.env.VITE_EIDOS_VAPID_PUBLIC_KEY,
+    onSubscribe: (sub) =>
+      fetch('/api/push-subscribe', { method: 'POST', body: JSON.stringify(sub) }),
+  });
+
+  if (result.status === 'subscribed') toast('Notifications enabled');
+  else if (result.status === 'denied') toast('Permission denied');
+}
+```
+
+`isPushSupported()` / `getPushPermissionState()` / `getPushUnsupportedReason()`
+let you hide the button when push is unavailable (e.g. iOS Safari outside an
+installed PWA returns `'ios-not-installed'`).
+
+### Server payload schema
+
+The service worker shows whatever your server sends — Eidos never renders UI:
+
+```json
+{
+  "title": "Order shipped",
+  "body": "Your order #1234 is on its way",
+  "icon": "/icon.png",
+  "badge": "/badge.png",
+  "tag": "order-1234",
+  "data": { "url": "/orders/1234" }
+}
+```
+
+Click behavior: if the app is open, `data` is delivered to `onNotificationClick`
+for client-side routing; otherwise the SW opens `data.url` directly.
+
+---
+
 ## Testing
 
 ```ts
@@ -314,21 +411,19 @@ Panel shows: live queue state · cache entries · SW status · offline simulatio
 
 ## How it compares
 
-|                            | **Eidos**                                                                                   | Workbox                                    | RTK Query / TanStack Query                                      |
-| -------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
-| Service worker setup       | Generated for you — `resource()`/`action()` declarations drive the SW                       | Hand-write `routing` + `strategies` config | None — no SW                                                    |
-| Caching strategy           | Auto-derived from intent (`offline: true` → SWR, etc.), inspectable via devtools            | Manually chosen per route                  | Configurable `staleTime`/`gcTime`, no Cache Storage integration |
-| Offline writes             | `action()` + `reliability: 'neverLose'` → IndexedDB queue, auto-replay, exponential backoff | Background Sync plugin, you wire the queue | No built-in offline mutation queue                              |
-| Framework support          | React, Svelte, Vue, Next.js, React Native, vanilla JS                                       | Framework-agnostic (SW only)               | Per-library (RTK Query = Redux, TanStack = many)                |
-| TanStack Query bridge      | `@sweidos/eidos/query` — drop-in `useEidosQuery`/`useEidosMutation`                         | —                                          | Native                                                          |
-| Bundle size (core, brotli) | ~5.4 kB                                                                                     | ~3-6 kB (modular)                          | ~13 kB (TanStack Query core)                                    |
-
-Eidos isn't a replacement for TanStack Query — `@sweidos/eidos/query` is a thin
-adapter so you keep TQ's cache/devtools while Eidos owns the offline layer
-(SW caching + IndexedDB write queue). Workbox is a lower-level toolkit Eidos
-generates strategies _for_; Eidos picks and configures the strategy from your
-`resource()`/`action()` declarations instead of you writing `workbox-*` config
-by hand.
+|                       | **Eidos**                                             | Workbox                      | RTK Query / TanStack Query |
+| --------------------- | ----------------------------------------------------- | ---------------------------- | -------------------------- |
+| Service worker setup  | Generated from `resource()`/`action()` declarations   | Hand-written routing config  | None — no SW               |
+| Caching strategy      | Auto-derived from intent, inspectable via devtools    | Manually chosen per route    | `staleTime`/`gcTime` only  |
+| Offline writes        | IndexedDB queue, auto-replay + backoff via `action()` | Background Sync, you wire it | No built-in mutation queue |
+| Framework support     | React, Svelte, Vue, Next.js, React Native, vanilla JS | Framework-agnostic (SW only) | Per-library                |
+| TanStack Query bridge | `@sweidos/eidos/query` adapter                        | —                            | Native                     |
+| Bundle size (core)    | ~6 kB brotli                                          | ~3-6 kB (modular)            | ~13 kB                     |
+
+Not a TanStack Query replacement — `@sweidos/eidos/query` is a thin adapter so
+you keep TQ's cache/devtools while Eidos owns the offline layer. Workbox is a
+lower-level toolkit; Eidos picks and configures strategies for you instead of
+hand-written `workbox-*` config.
 
 ---
 

package/dist/action.js

@@ -1,57 +1,92 @@
-import { useEidosStore as s } from "./store.js";
-import { getSwRegistration as w } from "./sw-bridge.js";
-import { idbQueueStorage as g } from "./idb.js";
-import { _getQueueStorage as m } from "./queue-storage.js";
-var d = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Map();
-function u() {
-  return m() ?? g;
-}
-function y() {
+import { useEidosStore as f } from "./store.js";
+import { getSwRegistration as _ } from "./sw-bridge.js";
+import { idbQueueStorage as A } from "./idb.js";
+import { _getQueueStorage as S } from "./queue-storage.js";
+import { broadcastQueueSync as d } from "./queue-sync.js";
+var m = /* @__PURE__ */ new Map(), k = /* @__PURE__ */ new Map(), Q = /* @__PURE__ */ new Map(), x = /* @__PURE__ */ new Map(), y = /* @__PURE__ */ new Map();
+function c() {
+  return S() ?? A;
+}
+function b() {
   return crypto.randomUUID();
 }
-function C(e, t) {
-  const r = t.name || e.name || y();
-  d.set(r, e), t.onRollback && p.set(r, t.onRollback), t.onConflict && f.set(r, t.onConflict);
-  const a = async (...i) => {
-    const { isOnline: n } = s.getState();
-    if (t.onOptimistic?.(...i), t.reliability === "neverLose") {
-      if (!n) return l(r, r, i, t);
-      try {
-        return await e(...i);
-      } catch {
-        return l(r, r, i, t);
-      }
+function h(e, t, o) {
+  return e(...t, o);
+}
+function F(e, t) {
+  const o = t.name || e.name || b(), a = t.namespace ? `${t.namespace}::${o}` : o;
+  if (m.has(a)) throw new Error(`[eidos] duplicate action id "${a}" — an action with this id is already registered. Pass a unique config.name or config.namespace.`);
+  m.set(a, e), x.set(a, t), t.onRollback && k.set(a, t.onRollback), t.conflict && Q.set(a, t.conflict);
+  const r = async (...n) => {
+    const { isOnline: s } = f.getState(), u = b();
+    let p;
+    if (t.cancellable) {
+      const l = new AbortController();
+      y.set(u, l), p = l.signal;
     }
+    const w = {
+      idempotencyKey: u,
+      attempt: 0,
+      signal: p
+    };
+    t.onOptimistic?.(...n, w);
     try {
-      return await e(...i);
-    } catch (o) {
-      throw t.onRollback?.(...i), o;
+      if (t.reliability === "neverLose") {
+        if (!s) return R(a, a, n, t, u);
+        try {
+          return await h(e, n, w);
+        } catch (l) {
+          if (C(l)) throw l;
+          return R(a, a, n, t, u);
+        }
+      }
+      try {
+        return await h(e, n, w);
+      } catch (l) {
+        throw t.onRollback?.(...n, w), l;
+      }
+    } finally {
+      t.cancellable && y.delete(u);
     }
+  }, i = async (n) => {
+    const s = y.get(n);
+    if (s)
+      return s.abort(), !0;
+    const u = (await c().getAll()).find((p) => p.idempotencyKey === n && p.status === "pending");
+    return u ? (f.getState().removeQueueItem(u.id), d({
+      type: "remove",
+      id: u.id
+    }), await c().remove(u.id), !0) : !1;
   };
-  return Object.defineProperty(a, "id", {
-    value: r,
+  return Object.defineProperty(r, "id", {
+    value: a,
     writable: !1
-  }), Object.defineProperty(a, "config", {
+  }), Object.defineProperty(r, "config", {
     value: t,
     writable: !1
-  }), a;
+  }), Object.defineProperty(r, "cancel", {
+    value: i,
+    writable: !1
+  }), r;
 }
-async function l(e, t, r, a) {
-  const i = y(), n = {
+async function R(e, t, o, a, r) {
+  const i = b(), n = {
+    schemaVersion: 2,
     id: i,
     actionId: e,
     actionName: t,
-    args: r,
+    idempotencyKey: r,
+    args: o,
     queuedAt: Date.now(),
     retryCount: 0,
     maxRetries: a.maxRetries ?? 3,
     status: "pending",
     priority: a.priority ?? "normal"
   };
-  await u().add(n), s.getState().addQueueItem(n);
+  await c().add(n), f.getState().addQueueItem(n);
   try {
-    const o = w();
-    o && "sync" in o && await o.sync.register("eidos-queue-replay");
+    const s = _();
+    s && "sync" in s && await s.sync.register("eidos-queue-replay");
   } catch {
   }
   return {
@@ -60,7 +95,10 @@ async function l(e, t, r, a) {
     message: `"${t}" queued — will execute when online`
   };
 }
-function h(e) {
+function C(e) {
+  return e instanceof DOMException && e.name === "AbortError";
+}
+function K(e) {
   if (e instanceof Response) return e.status >= 400 && e.status < 500;
   if (typeof e == "object" && e !== null) {
     const t = e.status;
@@ -68,112 +106,185 @@ function h(e) {
   }
   return !1;
 }
-function R(e) {
+function M(e) {
   return Math.min(2e3 * 2 ** e, 3e5) * (0.8 + Math.random() * 0.4);
 }
-var c = !1;
-async function _() {
-  const e = s.getState();
-  if (!e.isOnline || c) return {
+function g() {
+  return {
     attempted: 0,
     succeeded: 0,
     failed: 0,
     retrying: 0,
     skipped: 0,
-    conflicted: 0
+    conflicted: 0,
+    cancelled: 0
   };
-  c = !0;
+}
+var v = !1, O = "eidos-queue-replay";
+async function V() {
+  const e = f.getState();
+  if (!e.isOnline) return g();
+  if (typeof navigator < "u" && navigator.locks) return navigator.locks.request(O, { ifAvailable: !0 }, async (t) => t ? I(e) : g());
+  if (v) return g();
+  v = !0;
   try {
-    return await Q(e);
+    return await I(e);
   } finally {
-    c = !1;
+    v = !1;
   }
 }
-async function b(e, t) {
-  const r = d.get(e.actionId);
-  if (!r) return "skipped";
-  try {
-    await r(...e.args);
-    const a = Date.now();
-    return t.updateQueueItem(e.id, {
+async function q(e, t) {
+  const o = Date.now();
+  t.updateQueueItem(e.id, {
+    status: "succeeded",
+    completedAt: o
+  }), d({
+    type: "update",
+    id: e.id,
+    update: {
       status: "succeeded",
-      completedAt: a
-    }), await u().update(e.id, {
-      status: "succeeded",
-      completedAt: a
-    }), setTimeout(() => {
-      t.removeQueueItem(e.id), u().remove(e.id);
-    }, 3e3), "succeeded";
-  } catch (a) {
-    if (h(a)) {
-      const n = f.get(e.actionId);
-      if (n && n(a, e.args) === "skip")
-        return t.removeQueueItem(e.id), await u().remove(e.id), "conflicted";
+      completedAt: o
     }
-    const i = e.retryCount + 1;
-    if (i >= e.maxRetries)
-      return t.updateQueueItem(e.id, {
-        status: "failed",
-        error: String(a),
-        retryCount: i
-      }), await u().update(e.id, {
-        status: "failed",
-        error: String(a),
-        retryCount: i
-      }), p.get(e.actionId)?.(...e.args), "failed";
-    {
-      const n = Date.now() + R(i);
-      return t.updateQueueItem(e.id, {
-        status: "pending",
-        retryCount: i,
-        nextRetryAt: n
-      }), await u().update(e.id, {
-        status: "pending",
-        retryCount: i,
-        nextRetryAt: n
-      }), "retrying";
+  }), await c().update(e.id, {
+    status: "succeeded",
+    completedAt: o
+  }), setTimeout(() => {
+    t.removeQueueItem(e.id), d({
+      type: "remove",
+      id: e.id
+    }), c().remove(e.id);
+  }, 3e3);
+}
+async function E(e, t, o) {
+  const a = Q.get(e.actionId);
+  let r;
+  if (a) switch (a.strategy) {
+    case "serverWins":
+      r = "skip";
+      break;
+    case "clientWins":
+      r = "retry";
+      break;
+    case "merge":
+    case "custom": {
+      const i = {
+        error: o,
+        args: e.args,
+        attempt: e.retryCount,
+        idempotencyKey: e.idempotencyKey
+      };
+      r = a.resolve?.(i) ?? "retry";
+      break;
     }
   }
+  if (r === "skip")
+    return t.removeQueueItem(e.id), d({
+      type: "remove",
+      id: e.id
+    }), await c().remove(e.id), "conflicted";
+  r && typeof r == "object" && (e.args = r.resolved, t.updateQueueItem(e.id, { args: r.resolved }), d({
+    type: "update",
+    id: e.id,
+    update: { args: r.resolved }
+  }), await c().update(e.id, { args: r.resolved }));
 }
-async function I(e, t, r) {
+async function P(e, t, o) {
+  const a = e.retryCount + 1;
+  if (a >= e.maxRetries) {
+    const i = {
+      status: "failed",
+      error: String(o),
+      retryCount: a
+    };
+    t.updateQueueItem(e.id, i), d({
+      type: "update",
+      id: e.id,
+      update: i
+    }), await c().update(e.id, i);
+    const n = {
+      idempotencyKey: e.idempotencyKey,
+      attempt: a
+    };
+    return k.get(e.actionId)?.(...e.args, n), "failed";
+  }
+  const r = {
+    status: "pending",
+    retryCount: a,
+    nextRetryAt: Date.now() + M(a)
+  };
+  return t.updateQueueItem(e.id, r), d({
+    type: "update",
+    id: e.id,
+    update: r
+  }), await c().update(e.id, r), "retrying";
+}
+async function D(e, t) {
+  const o = m.get(e.actionId);
+  if (!o) return "skipped";
+  const a = x.get(e.actionId)?.cancellable;
+  let r;
+  if (a) {
+    const n = new AbortController();
+    y.set(e.idempotencyKey, n), r = n.signal;
+  }
+  const i = {
+    idempotencyKey: e.idempotencyKey,
+    attempt: e.retryCount,
+    signal: r
+  };
+  try {
+    return await h(o, e.args, i), await q(e, t), "succeeded";
+  } catch (n) {
+    if (C(n))
+      return t.removeQueueItem(e.id), d({
+        type: "remove",
+        id: e.id
+      }), await c().remove(e.id), "cancelled";
+    if (K(n)) {
+      const s = await E(e, t, n);
+      if (s) return s;
+    }
+    return P(e, t, n);
+  } finally {
+    a && y.delete(e.idempotencyKey);
+  }
+}
+async function j(e, t, o) {
   if (e.length === 0) return;
-  const a = e.filter((n) => d.has(n.actionId));
-  if (r.skipped += e.length - a.length, a.length > 0) {
-    t.batchUpdateQueueItems(a.map((n) => ({
+  const a = e.filter((i) => m.has(i.actionId));
+  if (o.skipped += e.length - a.length, a.length > 0) {
+    const i = a.map((n) => ({
       id: n.id,
       update: { status: "replaying" }
-    })));
-    for (const n of a) u().update(n.id, { status: "replaying" });
+    }));
+    t.batchUpdateQueueItems(i), d({
+      type: "batchUpdate",
+      updates: i
+    });
+    for (const n of a) c().update(n.id, { status: "replaying" });
   }
-  const i = await Promise.allSettled(a.map((n) => b(n, t)));
-  for (const n of i) {
-    const o = n.status === "fulfilled" ? n.value : "failed";
-    o === "skipped" ? r.skipped++ : o === "conflicted" ? r.conflicted++ : (r.attempted++, r[o]++);
+  const r = await Promise.allSettled(a.map((i) => D(i, t)));
+  for (const i of r) {
+    const n = i.status === "fulfilled" ? i.value : "failed";
+    n === "skipped" ? o.skipped++ : n === "conflicted" ? o.conflicted++ : n === "cancelled" ? o.cancelled++ : (o.attempted++, o[n]++);
   }
 }
-async function Q(e) {
-  const t = await u().getPending(), r = Date.now(), a = t.filter((n) => n.retryCount < n.maxRetries && (!n.nextRetryAt || n.nextRetryAt <= r)), i = {
-    attempted: 0,
-    succeeded: 0,
-    failed: 0,
-    retrying: 0,
-    skipped: 0,
-    conflicted: 0
-  };
-  for (const n of [
+async function I(e) {
+  const t = await c().getPending(), o = Date.now(), a = t.filter((i) => i.retryCount < i.maxRetries && (!i.nextRetryAt || i.nextRetryAt <= o)), r = g();
+  for (const i of [
     "high",
     "normal",
     "low"
-  ]) await I(a.filter((o) => (o.priority ?? "normal") === n), e, i);
-  return i;
+  ]) await j(a.filter((n) => (n.priority ?? "normal") === i), e, r);
+  return r;
 }
-async function A() {
-  await u().clear(), s.getState().hydrateQueue([]);
+async function Y() {
+  await c().clear(), f.getState().hydrateQueue([]);
 }
 export {
-  C as action,
-  A as clearQueue,
-  _ as replayQueue
+  F as action,
+  Y as clearQueue,
+  V as replayQueue
 };
 
 //# sourceMappingURL=action.js.map