@sweidos/eidos 2.1.0 → 2.3.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** | `@sweidos/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)**       | `@sweidos/crdt-yjs`           | `createYjsMergeResolver()` for `conflict.strategy: 'merge'`    |
+| **TanStack Query**         | `@sweidos/eidos/query`        | `useEidosQuery`, `useEidosMutation`, `withEidosQueryClient`    |
+| **Tauri / Electron**       | `@sweidos/sqlite-storage`     | SQLite-backed `QueueStorage`, same `action()` API              |
 
 ---
 
@@ -159,10 +162,14 @@ const products = resource('/api/products', {
   offline: true,      // enable SW interception + caching
   strategy?: 'cache-first' | 'stale-while-revalidate' | 'network-first',
   cacheName?: string, // custom cache bucket
-  maxAge?: number,    // TTL in ms — re-fetch after expiry
+  maxAge?: number,    // TTL in ms — enforced by the SW on all requests (not just handle.fetch())
+  maxEntries?: number, // max cache entries; oldest evicted (FIFO) when exceeded
   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
+                              // so old-shaped cache entries aren't served.
+                              // NOTE: this is separate from the SW-internal CACHE_VERSION
+                              // (bumped only on Eidos releases to purge old cache buckets).
+                              // Bump `version` for your data shape; Eidos bumps CACHE_VERSION.
 })
 
 await products.fetch()          // Promise<Response>
@@ -194,6 +201,19 @@ await productPattern.invalidate(); // clear all cached entries matching the patt
 productPattern.unregister();
 ```
 
+| Token    | Matches                                                      |
+| -------- | ------------------------------------------------------------ |
+| `*`      | One path segment — `/api/products/*` ↔ `/api/products/4`     |
+| `**`     | Any number of segments — `https://cdn.example.com/assets/**` |
+| `:param` | A named segment — `/api/users/:id/orders`                    |
+
+Pass the full URL (including origin) for cross-origin resources, e.g.
+`resourcePattern('https://cdn.example.com/assets/**', { offline: true })`.
+
+See it live in the [playground docs → Examples → URL patterns, one
+registration per
+family](https://sweidos.vercel.app/docs/examples#url-patterns-one-registration-per-family).
+
 ### `action(fn, config)`
 
 ```ts
@@ -223,6 +243,62 @@ await cancelByIdempotencyKey(idempotencyKey) // true if cancelled/removed
 await requeueItem(queueItemId)               // true if it was 'failed'
 ```
 
+### Conflict resolution
+
+A `neverLose` action can sit in the queue for a while — by the time it
+replays, the world may have moved on (the requested stock sold out, the
+record was deleted, etc.). `conflict` decides what happens when a replay gets
+a 4xx response, instead of retrying forever or silently dropping the write:
+
+```ts
+class StockConflictError extends Error {
+  status = 409;
+  constructor(public available: number) {
+    super('insufficient stock');
+  }
+}
+
+export const reserveStock = action(
+  async (payload: { productId: number; quantity: number }) => {
+    const res = await fetch('/api/inventory', {
+      method: 'POST',
+      body: JSON.stringify(payload),
+    });
+    if (res.status === 409) {
+      const { available } = await res.json();
+      throw new StockConflictError(available);
+    }
+    if (!res.ok) throw new Error('Reservation failed');
+    return res.json();
+  },
+  {
+    reliability: 'neverLose',
+    name: 'reserveStock',
+    conflict: {
+      strategy: 'custom',
+      resolve: ({ error, args, attempt }) => {
+        if (error instanceof StockConflictError && error.available > 0) {
+          const [payload] = args;
+          // Rewrite the queued args and retry with what's actually available
+          return { resolved: [{ ...payload, quantity: error.available }] };
+        }
+        return 'skip'; // nothing left to reserve — drop the write
+      },
+    },
+  },
+);
+```
+
+| Strategy     | Behavior on 4xx replay                                                |
+| ------------ | --------------------------------------------------------------------- |
+| `serverWins` | Drop the queued item — the server's current state is authoritative.   |
+| `clientWins` | Keep retrying — the write should eventually succeed.                  |
+| `merge`      | Call `resolve(ctx)`; typically used to combine client + server state. |
+| `custom`     | Call `resolve(ctx)`; return `'retry'`, `'skip'`, or `{ resolved }`.   |
+
+See it live in the [playground docs → Examples → Conflict resolution on
+replay](https://sweidos.vercel.app/docs/examples#conflict-resolution-on-replay).
+
 ### React hooks
 
 ```ts
@@ -231,6 +307,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
@@ -241,8 +320,105 @@ 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.
+
+### Handling SW updates
+
+By default, when a new service worker is available it activates immediately
+(`skipWaiting: true`). This matches standard PWA behaviour but can interrupt
+in-flight requests on pages that are mid-navigation.
+
+Opt into the **toast-then-reload** pattern with `skipWaiting: false`:
+
+```ts
+import { initEidos, triggerSwUpdate } from '@sweidos/eidos';
+
+initEidos({
+  skipWaiting: false,
+  onUpdateAvailable: (_registration) => {
+    // Show a toast, banner, or dialog — then call triggerSwUpdate() when the
+    // user confirms they're ready to reload.
+    showToast({
+      message: 'App update ready',
+      action: { label: 'Reload', onClick: triggerSwUpdate },
+    });
+  },
+});
+```
+
+`triggerSwUpdate()` tells the waiting service worker to activate, then the
+browser reloads the page. With `skipWaiting: true` (default) `onUpdateAvailable`
+is never called and `triggerSwUpdate()` is not needed.
+
+> **Tip**: avoid calling `triggerSwUpdate()` while `neverLose` actions are
+> mid-replay. The replay coordination (BroadcastChannel + Web Locks) survives
+> SW activation, but triggering an update during an active replay pass adds
+> unnecessary churn. Wait until the queue drains or use `waitForQueueDrain()`
+> from `@sweidos/eidos/testing` in tests.
+
+### Queue management
+
+Inspect and manage the offline action queue directly — handy for "pending
+changes" panels, manual retry buttons, or a "discard my offline edits" action:
+
+```ts
+import {
+  useEidosQueue,
+  cancelByIdempotencyKey,
+  requeueItem,
+  clearQueue,
+  replayQueue,
+} from '@sweidos/eidos';
+
+function QueuePanel() {
+  const queue = useEidosQueue(); // live list of pending/replaying/failed items
+
+  return queue.map((item) => (
+    <li key={item.id}>
+      {item.actionName} — {item.status}
+
+      {/* Drop a write before it ever reaches the server */}
+      {item.status === 'pending' && (
+        <button onClick={() => cancelByIdempotencyKey(item.idempotencyKey)}>
+          Cancel
+        </button>
+      )}
+
+      {/* Reset a failed item to 'pending' and replay it */}
+      {item.status === 'failed' && (
+        <button onClick={() => requeueItem(item.id)}>Retry</button>
+      )}
+    </li>
+  ));
+}
+
+// Drop every queued write — e.g. on "discard offline changes"
+await clearQueue();
+
+// Force a replay pass — normally triggered automatically on reconnect
+await replayQueue();
 ```
 
+See it live in the [playground docs → Examples → Queue management &
+reliability stats](https://sweidos.vercel.app/docs/examples#queue-management-reliability-stats).
+
 ---
 
 ## TanStack Query
@@ -342,6 +518,10 @@ for client-side routing; otherwise the SW opens `data.url` directly.
 
 ## Testing
 
+`@sweidos/eidos/testing` runs entirely at the JS layer — no real Service
+Worker needed — and gives Vitest/Jest/Playwright direct control over online
+state, the action queue, and the resource cache.
+
 ```ts
 import {
   mockOffline,
@@ -357,29 +537,82 @@ import {
 beforeEach(() => resetEidos());
 
 it('queues action while offline', async () => {
-  mockOffline();
-  await createOrder({ productId: 1, qty: 2 });
+  mockOffline({ stubFetch: true });
+  await createOrder({ productId: 1, quantity: 2 });
   expect(getEidosState().queue).toHaveLength(1);
+  expect(getEidosState().queue[0].actionName).toBe('createOrder');
 });
 
 it('replays on reconnect', async () => {
   mockOffline();
-  await createOrder({ productId: 1, qty: 2 });
+  await createOrder({ productId: 1, quantity: 2 });
+
+  // Forces isOnline = true and replays immediately
   const result = await drainQueue();
   expect(result.succeeded).toBe(1);
+
+  // ...or for code that replays itself on the 'online' event:
+  await waitForQueueDrain({ timeout: 2000 });
+  expect(getEidosState().queue).toHaveLength(0);
+});
+
+it('caches GET responses for offline use', async () => {
+  await products.json();
+  const cached = await getCachedEntry('/api/products');
+  expect(cached).toBeDefined();
 });
+
+afterEach(() => clearEidosCache());
 ```
 
 ---
 
 ## OpenAPI codegen
 
+`eidos-gen` reads an OpenAPI 3.x spec (JSON or YAML) and writes typed
+`resource()` + `action()` declarations — request/response interfaces from
+`$ref` schemas, `{id}` → `:id` path-param conversion, and DELETE body
+omission.
+
 ```bash
-npx eidos-gen openapi.json
-# → writes eidos.generated.ts with typed resource() + action() declarations
+npx eidos-gen openapi.json --out src/lib/eidos.generated.ts
+
+eidos-gen: reading openapi.json
+eidos-gen: wrote src/lib/eidos.generated.ts
+           2 resource(s), 2 action(s)
+           2 type(s)
+```
+
+```ts
+// eidos.generated.ts
+import { resource, action } from '@sweidos/eidos';
+
+export interface Product {
+  id: number;
+  name: string;
+  tags?: string[];
+}
+
+export const listProducts = resource('/products', { offline: true });
+
+export const createProduct = action(
+  async (payload: Product): Promise<Product> => {
+    const res = await fetch('/products', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return res.json();
+  },
+  { reliability: 'neverLose', name: 'createProduct' },
+);
 ```
 
-Handles path params, `$ref` resolution, request/response types, DELETE body omission.
+| Flag           | Effect                                                       |
+| -------------- | ------------------------------------------------------------ |
+| `--out, -o`    | Output file path (default: `eidos.generated.ts`)             |
+| `--no-offline` | Set `offline: false` on every generated `resource()`         |
+| `--eidos`      | Import path for `@sweidos/eidos` (default: `@sweidos/eidos`) |
 
 ---
 
@@ -396,16 +629,51 @@ import { EidosDevtools } from '@sweidos/eidos/devtools';
 
 Panel shows: live queue state · cache entries · SW status · offline simulation toggle.
 
+### `eidosDebug()`
+
+Returns a plain-object snapshot of the full Eidos runtime state — safe to `JSON.stringify`, useful for bug reports or attaching to error-tracking breadcrumbs:
+
+```ts
+import { eidosDebug } from '@sweidos/eidos';
+
+// Print for a bug report
+console.log(JSON.stringify(eidosDebug(), null, 2));
+
+// Attach to a Sentry breadcrumb
+Sentry.addBreadcrumb({ data: eidosDebug() });
+```
+
+Snapshot includes: `version`, `swStatus`, `isOnline`, `resourceCount`, `resources` (per-URL status/hits/cachedAt), `queue` (item list with idempotencyKey/retryCount), `reliability` counters, and `swRegistration` state.
+
+---
+
+## Troubleshooting
+
+Eidos emits plain-English `console.warn` messages in development (`import.meta.env.DEV`) for common setup problems:
+
+| Warning                                             | Cause                                        | Fix                                                                                                                             |
+| --------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `Service workers require a secure context`          | `initEidos()` called on HTTP (non-localhost) | Use `localhost` for dev or deploy to HTTPS                                                                                      |
+| `Service worker file not found at "/eidos-sw.js"`   | SW file missing from `public/`               | Add `eidos()` to `vite.config.ts` plugins, or copy `node_modules/@sweidos/eidos/dist/eidos-sw.js → public/eidos-sw.js` manually |
+| `Service worker registration failed: …`             | Unexpected registration error                | Check `eidosDebug().swError` for the full browser error message                                                                 |
+| `Service workers are not supported in this context` | Old browser, or SW API absent                | No fix needed — Eidos degrades gracefully; only SW-side caching is disabled                                                     |
+
 ---
 
 ## SSR adapters
 
 **Next.js** — import from `@sweidos/eidos/nextjs`. Pre-marked `'use client'`, works in App Router layouts without a wrapper.
 
+**Next.js Server Actions** — `@sweidos/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** — `@sweidos/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)** — `@sweidos/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
@@ -428,7 +696,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.3 kB brotli                                        | ~3-6 kB (modular)            | ~13 kB                     |
+| Bundle size (core)    | ~6.7 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.d.ts

@@ -0,0 +1,22 @@
+import { ActionConfig, ActionHandle, ActionFn, ReplayResult } from './types';
+export declare function action<TArgs extends any[], TReturn>(fn: ActionFn<TArgs, TReturn>, config: ActionConfig<TArgs>): ActionHandle<TArgs, TReturn>;
+/**
+ * Cancel an invocation by its `idempotencyKey` (from `ActionContext` /
+ * `onOptimistic`). Aborts the in-flight call if `cancellable: true` and
+ * still running, otherwise removes a not-yet-replayed queued item.
+ * Returns `true` if something was cancelled/removed.
+ *
+ * Shared by every `ActionHandle.cancel()` and by devtools, which can't
+ * address a specific handle from a queue item alone.
+ */
+export declare function cancelByIdempotencyKey(idempotencyKey: string): Promise<boolean>;
+/**
+ * Reset a `'failed'` queue item back to `'pending'` so the next
+ * `replayQueue()` retries it — clears `error`/`nextRetryAt` and resets
+ * `retryCount` to 0. Returns `true` if the item existed and was failed.
+ * Used by devtools' per-item "Retry" action.
+ */
+export declare function requeueItem(id: string): Promise<boolean>;
+export declare function replayQueue(): Promise<ReplayResult>;
+/** Remove all items from the action queue (storage + in-memory store). */
+export declare function clearQueue(): Promise<void>;