@sweidos/eidos 2.0.0 → 2.2.0

package/README.md

@@ -4,12 +4,12 @@
 [![npm downloads](https://img.shields.io/npm/dm/@sweidos/eidos?color=22C55E)](https://www.npmjs.com/package/@sweidos/eidos)
 [![bundle size](https://deno.bundlejs.com/badge?q=@sweidos/eidos&badge=detailed&color=22C55E)](https://bundlejs.com/?q=@sweidos/eidos)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-22C55E)](https://www.typescriptlang.org/)
-[![CI](https://github.com/iamadi11/eidos/actions/workflows/deploy.yml/badge.svg)](https://github.com/iamadi11/eidos/actions)
+[![CI](https://github.com/sweidos/eidos/actions/workflows/deploy.yml/badge.svg)](https://github.com/sweidos/eidos/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-22C55E.svg)](LICENSE)
 
-> **Describe intent. The runtime figures out how.**
+> **Never lose a write.**
 
-Declare what your app needs offline. Eidos picks the cache strategy, registers the Service Worker, and persists your action queue to IndexedDB — automatically.
+Declare what your app needs offline. Eidos picks the cache strategy, registers the Service Worker, and persists your action queue to IndexedDB — with idempotency keys and cross-tab replay locks built in, so a queued mutation runs exactly once.
 
 ```ts
 import { resource, action } from '@sweidos/eidos';
@@ -135,16 +135,19 @@ if ('queued' in result) {
 
 ## Framework support
 
-| Framework              | Import path                   | Notes                                                          |
-| ---------------------- | ----------------------------- | -------------------------------------------------------------- |
-| **React**              | `@sweidos/eidos`              | Hooks + `EidosProvider`                                        |
-| **Next.js App Router** | `@sweidos/eidos/nextjs`       | Pre-marked `'use client'` — no wrapper needed                  |
-| **SvelteKit**          | `@sweidos/eidos/sveltekit`    | `initEidosSvelteKit()` in `onMount`, framework-agnostic stores |
-| **Vue**                | `@sweidos/eidos`              | Framework-agnostic stores via `eidosStatus.subscribe()`        |
-| **React Native**       | `@sweidos/eidos/react-native` | AsyncStorage-backed queue, same `action()` API                 |
-| **Vanilla JS**         | `@sweidos/eidos`              | `eidosStatus`, `eidosQueue`, `eidosQueueStats` stores          |
-| **Vite**               | `@sweidos/eidos/vite`         | Plugin auto-copies `eidos-sw.js` on every build                |
-| **TanStack Query**     | `@sweidos/eidos/query`        | `useEidosQuery`, `useEidosMutation`, `withEidosQueryClient`    |
+| Framework                  | Import path                   | Notes                                                          |
+| -------------------------- | ----------------------------- | -------------------------------------------------------------- |
+| **React**                  | `@sweidos/eidos`              | Hooks + `EidosProvider`                                        |
+| **Next.js App Router**     | `@sweidos/eidos/nextjs`       | Pre-marked `'use client'` — no wrapper needed                  |
+| **Next.js Server Actions** | `@eidos/next`                 | `serverAction()` neverLose wrapper + idempotency context       |
+| **SvelteKit**              | `@sweidos/eidos/sveltekit`    | `initEidosSvelteKit()` in `onMount`, framework-agnostic stores |
+| **Vue**                    | `@sweidos/eidos`              | Framework-agnostic stores via `eidosStatus.subscribe()`        |
+| **React Native**           | `@sweidos/eidos/react-native` | AsyncStorage-backed queue, same `action()` API                 |
+| **Vanilla JS**             | `@sweidos/eidos`              | `eidosStatus`, `eidosQueue`, `eidosQueueStats` stores          |
+| **Vite**                   | `@sweidos/eidos/vite`         | Plugin auto-copies `eidos-sw.js` on every build                |
+| **CRDT merge (Yjs)**       | `@eidos/crdt-yjs`             | `createYjsMergeResolver()` for `conflict.strategy: 'merge'`    |
+| **TanStack Query**         | `@sweidos/eidos/query`        | `useEidosQuery`, `useEidosMutation`, `withEidosQueryClient`    |
+| **Tauri / Electron**       | `@eidos/sqlite-storage`       | SQLite-backed `QueueStorage`, same `action()` API              |
 
 ---
 
@@ -160,6 +163,9 @@ const products = resource('/api/products', {
   strategy?: 'cache-first' | 'stale-while-revalidate' | 'network-first',
   cacheName?: string, // custom cache bucket
   maxAge?: number,    // TTL in ms — re-fetch after expiry
+  version?: string | number, // bump when the response shape changes —
+                              // appended to cacheName (e.g. 'eidos-resources-v1-v2')
+                              // so old-shaped cache entries aren't served
 })
 
 await products.fetch()          // Promise<Response>
@@ -211,6 +217,13 @@ const createOrder = action(async (payload: OrderPayload, ctx: ActionContext) =>
 
 // ctx.idempotencyKey is stable across retries — forward as e.g. an
 // `Idempotency-Key` header so the server can dedupe replayed writes.
+
+// Module-level helpers (used by the devtools queue inspector, and usable
+// directly): cancel/remove a queue item by idempotency key, or reset a
+// 'failed' item back to 'pending' for the next replayQueue().
+import { cancelByIdempotencyKey, requeueItem } from '@sweidos/eidos'
+await cancelByIdempotencyKey(idempotencyKey) // true if cancelled/removed
+await requeueItem(queueItemId)               // true if it was 'failed'
 ```
 
 ### React hooks
@@ -221,6 +234,9 @@ const { pending, failed } = useEidosQueueStats();
 const entry = useEidosResource('/api/products');
 const item = useEidosAction(queuedResult.id);
 useEidosOnDrain(() => toast('All offline actions synced!'));
+
+// Cumulative neverLose outcome counters (queued/succeeded/failed/retried/conflicted/cancelled)
+const { queued, succeeded, failed: failedCount } = useEidosReliabilityStats();
 ```
 
 ### Framework-agnostic stores
@@ -231,8 +247,25 @@ eidosStatus.subscribe(({ isOnline }) => { ... })
 eidosQueue.subscribe((queue) => { ... })
 eidosQueueStats.getState() // { pending, failed, replaying, total }
 eidosResource('/api/products').getState() // ResourceEntry | undefined
+onQueueDrain(() => toast('All offline actions synced!')) // returns unsubscribe
+eidosReliabilityStats.getState() // { queued, succeeded, failed, retried, conflicted, cancelled }
+```
+
+### Reliability telemetry
+
+Opt in to periodic reporting of cumulative `neverLose` queue outcomes — wire it
+up to your analytics backend:
+
+```ts
+initEidos({
+  onReliabilityReport: (stats) => analytics.track('eidos_reliability', stats),
+  reliabilityReportInterval: 60_000, // default
+});
 ```
 
+The same counters are visible live in `<EidosDevtools />` under the
+"Reliability" tab.
+
 ---
 
 ## TanStack Query
@@ -392,10 +425,16 @@ Panel shows: live queue state · cache entries · SW status · offline simulatio
 
 **Next.js** — import from `@sweidos/eidos/nextjs`. Pre-marked `'use client'`, works in App Router layouts without a wrapper.
 
+**Next.js Server Actions** — `@eidos/next`'s `serverAction()` wraps a `'use server'` function with `action()` (`reliability: 'neverLose'` by default), keyed by `config.name` + `config.namespace`. `getActionContext()` / `idempotencyHeaders()` recover the `idempotencyKey`/`attempt` inside the action body.
+
 **SvelteKit** — `initEidosSvelteKit()` inside `onMount`. Framework-agnostic stores (`$eidosQueue`, `$eidosStatus`) work with Svelte's `$` auto-subscribe.
 
 **React Native** — `@sweidos/eidos/react-native` with AsyncStorage-backed queue. Same `action()` API surface, no Service Worker dependency.
 
+**Tauri / Electron** — `@eidos/sqlite-storage` with a SQLite-backed `QueueStorage`. Pass a `@tauri-apps/plugin-sql` `Database` directly, or wrap `better-sqlite3` with the `SqliteLike` interface. Same `action()` API surface, no Service Worker dependency.
+
+**CRDT merge (Yjs)** — `@eidos/crdt-yjs`'s `createYjsMergeResolver()` builds a `conflict.resolve` for the `'merge'`/`'custom'` strategy that applies the server's Yjs state and the queued local update to a `Y.Doc`, then rewrites the queued args with the merged update — automatic, loss-free reconciliation of concurrent edits instead of a hand-written `resolve()`.
+
 ---
 
 ## Known limitations
@@ -418,7 +457,7 @@ Panel shows: live queue state · cache entries · SW status · offline simulatio
 | 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                     |
+| Bundle size (core)    | ~6.5 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

package/dist/action.js

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