@sweidos/eidos 0.2.0 → 1.0.1

package/README.md

@@ -1,63 +1,55 @@
 # Eidos
 
+[![npm](https://img.shields.io/npm/v/@sweidos/eidos)](https://www.npmjs.com/package/@sweidos/eidos)
+[![CI](https://github.com/iamadi11/eidos/actions/workflows/deploy.yml/badge.svg)](https://github.com/iamadi11/eidos/actions/workflows/deploy.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
 > Describe intent. The runtime figures out how.
 
-Eidos is a small, opinionated abstraction layer for building offline-first web applications. Instead of configuring Service Workers, Cache API strategies, and IndexedDB queues directly, you declare **what you want** and the runtime generates the required behaviour.
+Eidos is a small, opinionated abstraction layer for building offline-first web apps. Instead of configuring Service Workers, Cache API strategies, and IndexedDB queues by hand, you declare **what you want** and the runtime handles the rest.
 
 ```ts
 import { resource, action } from '@sweidos/eidos'
 
-// "I want this resource to work offline."
-const products = resource('/api/products', {
-  offline: true,
-})
+// "I want this resource available offline."
+const products = resource('/api/products', { offline: true })
 
 // "I never want to lose this action."
-const createOrder = action(orderApi.create, {
-  reliability: 'neverLose',
-})
+const createOrder = action(orderApi.create, { reliability: 'neverLose' })
 ```
 
-That's it. No service worker file to write. No cache strategy to configure. No retry logic to implement.
+No service worker file to write. No cache strategy to configure. No retry logic to implement.
+
+**[→ Live playground](https://playground-iamadi11s-projects.vercel.app)**
 
 ---
 
 ## The Problem
 
-Building offline-capable web apps today requires a working knowledge of:
+Building offline-capable apps today requires deep knowledge of:
 
 - Service Worker registration and lifecycle management
-- Cache API and caching strategies (cache-first, network-first, SWR)
+- Cache API strategies (cache-first, network-first, stale-while-revalidate)
 - Fetch event interception and URL routing
-- IndexedDB schema design for persistent action queues
-- Background Sync API and exponential retry logic
+- IndexedDB schema design for persistent queues
+- Exponential backoff and retry logic
 - Cache versioning and stale entry cleanup
 
-This is a large surface area, separate from your application logic, that every team re-implements from scratch.
-
-## The Vision
+Every team re-implements this surface area from scratch.
 
-Developers should describe **what they want**, not **how the browser should implement it**.
+## The Solution
 
 ```ts
-// Before Eidos
-// workbox-config.js
+// Before — workbox-config.js + service-worker.js (40+ lines)
 registerRoute(
   ({ url }) => url.pathname === '/api/products',
-  new StaleWhileRevalidate({
-    cacheName: 'api-cache',
-    plugins: [new ExpirationPlugin({ maxEntries: 60 })],
-  }),
+  new StaleWhileRevalidate({ cacheName: 'api-cache', plugins: [...] }),
 )
-
-// service-worker.js
-self.addEventListener('sync', (event) => {
-  if (event.tag === 'create-order') {
-    event.waitUntil(replayOrders())
-  }
+self.addEventListener('sync', event => {
+  if (event.tag === 'create-order') event.waitUntil(replayOrders())
 })
 
-// After Eidos
+// After — eidos (2 lines)
 resource('/api/products', { offline: true })
 action(createOrder, { reliability: 'neverLose' })
 ```
@@ -66,28 +58,27 @@ action(createOrder, { reliability: 'neverLose' })
 
 ## Quick Start
 
-### Install
+### 1. Install
 
 ```bash
-npm install eidos
+npm install @sweidos/eidos
 # or
-pnpm add eidos
+pnpm add @sweidos/eidos
 ```
 
-### Add the service worker
-
-Copy `eidos-sw.js` to your project's `public/` directory:
+### 2. Add the service worker
 
 ```bash
-cp node_modules/eidos/dist/eidos-sw.js public/eidos-sw.js
+cp node_modules/@sweidos/eidos/dist/eidos-sw.js public/eidos-sw.js
 ```
 
-> **Vite users** — you can also add a plugin to do this automatically. See [setup guide](#vite-plugin).
+> **Vite users** — automate this with the [Vite plugin snippet](#vite-plugin).
 
-### Wrap your app
+### 3. Wrap your app
 
 ```tsx
 import { EidosProvider } from '@sweidos/eidos'
+import { createRoot } from 'react-dom/client'
 
 createRoot(document.getElementById('root')!).render(
   <EidosProvider swPath="/eidos-sw.js">
@@ -96,14 +87,17 @@ createRoot(document.getElementById('root')!).render(
 )
 ```
 
-### Declare resources and actions
+### 4. Declare resources and actions at module scope
 
 ```ts
-// src/lib/eidos.ts — module scope, so replay survives page reload
+// src/lib/eidos.ts
+// Module scope is required — actions must be registered before page reload
+// for queue replay to work.
 import { resource, action } from '@sweidos/eidos'
 
 export const products = resource('/api/products', {
-  offline: true,
+  offline: true,           // → StaleWhileRevalidate auto-selected
+  maxAge: 5 * 60 * 1000,  // optional: treat cache as stale after 5 min
 })
 
 export const createOrder = action(
@@ -114,24 +108,25 @@ export const createOrder = action(
     })
     return res.json()
   },
-  { reliability: 'neverLose' },
+  { reliability: 'neverLose', name: 'createOrder' },
 )
 ```
 
-### Use in components
+### 5. Use in components
 
 ```tsx
-// With TanStack Query
-const { data } = useQuery(products.query())
+// TanStack Query
+const { data } = useQuery(products.query<Product[]>())
 
-// Or plain
-const data = await products.json()
+// Or plain async
+const data = await products.json<Product[]>()
 
 // Actions work identically online and offline
 const result = await createOrder({ productId: 1, qty: 2 })
 
 if ('queued' in result) {
-  console.log(result.message) // "createOrder queued — will execute when online"
+  // Persisted to IndexedDB — will replay automatically on reconnect
+  console.log(result.message)
 }
 ```
 
@@ -141,114 +136,134 @@ if ('queued' in result) {
 
 ### `resource(url, config)`
 
-Registers a URL as an offline-capable resource. Returns a handle for fetching and cache management.
+Registers a URL as an offline-capable resource. Returns a `ResourceHandle`.
 
 ```ts
-const products = resource('/api/products', {
-  offline: true,           // required: enables SW interception
+const handle = resource('/api/products', {
+  offline: true,           // required — enables SW interception
   strategy?: 'cache-first' | 'stale-while-revalidate' | 'network-first',
-  cacheName?: string,      // custom cache bucket
+  cacheName?: string,      // custom Cache Storage bucket (default: 'eidos-resources-v1')
+  maxAge?: number,         // TTL in ms — expired entries are re-fetched from network
 })
+```
+
+**Auto-selected strategy:**
+
+| Config | Strategy | When to use |
+|--------|----------|-------------|
+| `offline: true` | `StaleWhileRevalidate` | Default — instant response + background refresh |
+| `offline: true, strategy: 'cache-first'` | `CacheFirst` | Static assets, rarely-changing data |
+| `offline: true, strategy: 'network-first'` | `NetworkFirst` | Always-fresh data with offline fallback |
 
-// Handle methods
-products.fetch()           // → Promise<Response>
-products.json<T>()         // → Promise<T>
-products.query()           // → { queryKey, queryFn } for TanStack Query
-products.prefetch()        // → Promise<void>
-products.invalidate()      // → Promise<void> — clears SW cache entry
-
-// Handle properties
-products.url               // '/api/products'
-products.strategy          // generated GeneratedStrategy object
-products.config            // the config you passed in
+**Handle methods:**
+
+```ts
+handle.fetch()       // Promise<Response> — fetches, respects maxAge
+handle.json<T>()     // Promise<T> — fetch() + response.json()
+handle.query<T>()    // { queryKey, queryFn } — TanStack Query compatible
+handle.prefetch()    // Promise<void> — warm the cache
+handle.invalidate()  // Promise<void> — evict cached entries
+handle.unregister()  // void — remove from SW registry (required to re-register with different config)
 ```
 
-**Strategy selection:**
+**Handle properties:**
+
+```ts
+handle.url           // '/api/products'
+handle.config        // the config you passed in
+handle.strategy      // { name, swStrategy, cacheName, reasoning, behavior, equivalentCode }
+```
 
-| Intent | Generated Strategy | Reasoning |
-|---|---|---|
-| `offline: true` | `StaleWhileRevalidate` | Best balance of speed and freshness for resilient resources |
-| `offline: true, strategy: 'cache-first'` | `CacheFirst` | Maximum speed, data rarely changes |
-| `offline: true, strategy: 'network-first'` | `NetworkFirst` | Freshness critical, cache as fallback only |
+---
 
 ### `action(fn, config)`
 
-Wraps an async function with reliability guarantees. The wrapped function is a drop-in replacement — calling it is identical whether you're online or offline.
+Wraps any async function with reliability guarantees. The wrapped function is a drop-in replacement.
 
 ```ts
 const createOrder = action(
-  async (payload: OrderPayload): Promise<Order> => {
-    // your existing async function, unchanged
-  },
+  async (payload: OrderPayload): Promise<Order> => { /* your fn */ },
   {
-    reliability: 'neverLose', // persist to IndexedDB if call fails or offline
-    maxRetries?: number,       // default: 3
-    name?: string,             // label shown in devtools
+    reliability: 'neverLose',  // persist to IndexedDB + replay on reconnect
+    maxRetries?: number,        // default: 3
+    name?: string,              // label in devtools
   }
 )
 
-// Returns TReturn when successful, QueuedResult when queued
 const result = await createOrder(payload)
+// → Order when successful
+// → { queued: true, id, message } when offline or network fails
 ```
 
 **Reliability modes:**
 
 | Mode | Behaviour |
-|---|---|
-| `best-effort` | Call directly. No persistence, no retry. |
-| `neverLose` | Persist args to IndexedDB before executing. Replay on reconnect. |
+|------|-----------|
+| `best-effort` | Execute directly. No persistence, no retry. |
+| `neverLose` | Persist args to IndexedDB before executing. Replay on reconnect with exponential backoff. |
+
+**Exponential backoff:** `neverLose` actions that fail are retried with `2s × 2^retryCount` delay (capped at 5 min, ±20% jitter). Items not yet due are skipped on each replay pass.
+
+---
 
 ### `replayQueue()`
 
-Manually trigger queue replay. Called automatically on the `online` event when `autoReplay: true` (the default).
+Manually trigger queue replay. Called automatically on reconnect when `autoReplay: true`.
 
 ```ts
 import { replayQueue } from '@sweidos/eidos'
 
-window.addEventListener('online', replayQueue)
+// Manual trigger — e.g. after a user clicks "Retry"
+await replayQueue()
 ```
 
+---
+
 ### `EidosProvider`
 
-Root provider that registers the SW and initialises the runtime.
+React root component. Registers the SW and initialises the runtime.
 
 ```tsx
 <EidosProvider
-  swPath="/eidos-sw.js"   // default
-  autoReplay={true}       // replay queue on reconnect, default: true
+  swPath="/eidos-sw.js"  // default
+  autoReplay={true}      // replay queue on reconnect, default: true
 >
   <App />
 </EidosProvider>
 ```
 
+---
+
 ### React Hooks
 
 ```ts
 import { useEidosStatus, useEidosResource, useEidosQueue } from '@sweidos/eidos'
 
-// Online + SW status — cheap, safe in headers
-const { isOnline, swStatus } = useEidosStatus()
+// Online status + SW lifecycle — cheap subscription, safe in headers
+const { isOnline, swStatus, swError } = useEidosStatus()
 
-// Live state for a single resource
+// Live cache state for a single resource URL
 const entry = useEidosResource('/api/products')
-// → { status, cacheHits, cachedAt, strategy, ... }
+// entry → { status, cacheHits, cacheMisses, cachedAt, strategy, config, ... }
 
-// The full action queue
+// The full action queue, reactive
 const queue = useEidosQueue()
 
-// Full store (use sparingly)
+// Full Zustand store — use sparingly
 const state = useEidos()
 ```
 
+---
+
 ### `setOfflineSimulation(enabled)`
 
-Toggle offline simulation from devtools or tests. Sends a message to the SW to serve only cached responses.
+Toggle offline simulation without physically disconnecting the network.
 
 ```ts
 import { setOfflineSimulation } from '@sweidos/eidos'
 
-setOfflineSimulation(true)   // force offline
-setOfflineSimulation(false)  // restore normal
+setOfflineSimulation(true)   // SW serves only cached responses
+setOfflineSimulation(false)  // restore normal behaviour
 ```
 
 ---
@@ -260,43 +275,43 @@ setOfflineSimulation(false)  // restore normal
 │  Application Layer                           │
 │  resource() · action() · EidosProvider       │  ← you write this
 └────────────────┬────────────────────────────┘
-                 │ postMessage(EIDOS_REGISTER_RESOURCE)
+                 │ EIDOS_REGISTER_RESOURCE (postMessage)
 ┌────────────────▼────────────────────────────┐
-│  Runtime Layer (packages/core)               │
-│  Strategy derivation · Zustand store         │  ← eidos npm package
-│  SW bridge · IDB queue                       │
+│  Runtime Layer  (@sweidos/eidos)             │
+│  Strategy derivation · Zustand store         │
+│  SW bridge · IDB queue · exponential backoff │
 └────────────────┬────────────────────────────┘
                  │ fetch intercept
 ┌────────────────▼────────────────────────────┐
-│  Worker Layer (eidos-sw.js)                  │
-│  CacheFirst · StaleWhileRevalidate           │  ← generated SW
+│  Worker Layer   (eidos-sw.js)                │
+│  CacheFirst · StaleWhileRevalidate           │
 │  NetworkFirst · Offline simulation           │
 └────────────────┬────────────────────────────┘
                  │ Cache API · IndexedDB
 ┌────────────────▼────────────────────────────┐
 │  Storage Layer                               │
-│  Cache Storage · IndexedDB (action queue)    │  ← browser APIs
+│  Cache Storage · IndexedDB (action queue)    │
 └─────────────────────────────────────────────┘
 ```
 
-### Service Worker protocol
+### SW message protocol
 
-The runtime communicates with `eidos-sw.js` via `postMessage`. Messages sent from the app:
+**App → SW:**
 
 | Message | Purpose |
-|---|---|
-| `EIDOS_REGISTER_RESOURCE` | Add a fetch-intercept rule |
+|---------|---------|
+| `EIDOS_REGISTER_RESOURCE` | Register a fetch-intercept rule |
 | `EIDOS_UNREGISTER_RESOURCE` | Remove a rule |
-| `EIDOS_CLEAR_CACHE` | Evict cache entries |
-| `EIDOS_SIMULATE_OFFLINE` | Toggle offline simulation |
+| `EIDOS_CLEAR_CACHE` | Evict cache entries for a URL |
+| `EIDOS_SIMULATE_OFFLINE` | Toggle offline simulation mode |
 | `EIDOS_PING` | Health check |
 
-Messages received from the SW:
+**SW → App:**
 
 | Message | Purpose |
-|---|---|
-| `EIDOS_CACHE_HIT` | A cached response was served |
-| `EIDOS_CACHE_UPDATED` | Cache entry was refreshed from network |
+|---------|---------|
+| `EIDOS_CACHE_HIT` | Cached response was served |
+| `EIDOS_CACHE_UPDATED` | Cache entry refreshed from network |
 | `EIDOS_NETWORK_ERROR` | Network request failed |
 | `EIDOS_CACHE_CLEARED` | Cache was cleared |
 
@@ -306,51 +321,35 @@ Messages received from the SW:
 
 ```
 eidos/
+├── api/                    Vercel serverless functions (demo endpoints)
 ├── packages/
-│   ├── core/           eidos npm package
+│   ├── core/               @sweidos/eidos npm package
 │   │   └── src/
 │   │       ├── types.ts
-│   │       ├── resource.ts     resource() implementation
-│   │       ├── action.ts       action() + queue replay
-│   │       ├── runtime.ts      init + SW registration
+│   │       ├── resource.ts     resource() — caching + handle
+│   │       ├── action.ts       action() + exponential backoff queue replay
+│   │       ├── runtime.ts      initEidos + SW registration
 │   │       ├── store.ts        Zustand store
 │   │       ├── sw-bridge.ts    postMessage channel
-│   │       ├── idb.ts          IndexedDB wrapper
+│   │       ├── idb.ts          IndexedDB CRUD wrapper
 │   │       └── react/          EidosProvider + hooks
-│   └── worker/         SW typed source
-│       └── src/sw.ts   → compiles to eidos-sw.js
+│   └── worker/             SW typed source
+│       └── src/sw.ts       → compiles to eidos-sw.js
 ├── apps/
-│   └── playground/     interactive demo dashboard
+│   └── playground/         Interactive demo dashboard
 │       └── public/
-│           └── eidos-sw.js   compiled service worker
-└── examples/           (planned)
-```
-
----
-
-## Dev Dashboard
-
-The playground at `apps/playground` is a full interactive dashboard that demonstrates every feature:
-
-```bash
-pnpm dev   # → http://localhost:3000
+│           └── eidos-sw.js compiled service worker
+└── .github/workflows/      CI/CD — deploy + npm release on push to main
 ```
 
-It includes:
-
-- **Overview** — live status + interactive products/orders demos
-- **Resources** — every registered resource with cache stats and strategy detail
-- **Action Queue** — live queue with per-item status and replay controls
-- **Intent Inspector** — step-by-step trace from intent declaration to SW rule
-- **How It Works** — architecture diagrams and lifecycle walkthroughs
-
 ---
 
 ## Vite Plugin
 
-To automatically copy `eidos-sw.js` into `public/` during dev and build, add this to your `vite.config.ts`:
+Automatically copy `eidos-sw.js` into `public/` on build:
 
 ```ts
+// vite.config.ts
 import { copyFileSync } from 'fs'
 import { resolve } from 'path'
 
@@ -359,7 +358,7 @@ function eidosPlugin() {
     name: 'eidos-sw',
     buildStart() {
       copyFileSync(
-        resolve('./node_modules/eidos/dist/eidos-sw.js'),
+        resolve('./node_modules/@sweidos/eidos/dist/eidos-sw.js'),
         resolve('./public/eidos-sw.js'),
       )
     },
@@ -371,26 +370,26 @@ function eidosPlugin() {
 
 ## Known Limitations
 
-These are real limitations in v0.1. They are documented so you know exactly what you're getting.
-
 | Limitation | Detail |
-|---|---|
-| GET-only caching | The SW only intercepts `GET` requests. `POST`/`PUT`/`DELETE` are never cached. |
-| Pathname matching | Resources match by pathname only. Cross-origin URLs require the full URL to be registered. |
-| Module-scope actions | `action()` must be called at module scope for replay to work after a page reload. |
-| No TTL | Cached resources do not expire automatically. Call `resource.invalidate()` to clear. |
-| Single SW | `EidosProvider` assumes `/eidos-sw.js`. Multiple SW registrations in one app are unsupported. |
+|------------|--------|
+| 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. |
+| 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. |
 
 ---
 
 ## Roadmap
 
+- [x] Cache TTL / `maxAge` expiration
+- [x] Exponential backoff with jitter for queue replay
+- [x] Per-resource `cacheName` override
+- [x] `resource.unregister()` for cleanup
 - [ ] URL pattern matching (wildcards, regex)
-- [ ] Cache TTL / expiration
 - [ ] Cross-origin resource support
-- [ ] Background Sync integration (native browser API)
+- [ ] Background Sync API integration
 - [ ] Vite plugin (first-class, published separately)
-- [ ] React Native / Expo adapter
+- [ ] Vue / Svelte bindings
 - [ ] TanStack Query integration package
 
 ---
@@ -398,22 +397,13 @@ These are real limitations in v0.1. They are documented so you know exactly what
 ## Contributing
 
 ```bash
-# Install
-pnpm install
-
-# Run the playground
-pnpm dev
-
-# Type-check everything
-pnpm type-check
-
-# Build the core package
-pnpm build:core
+pnpm install          # install all workspace deps
+pnpm dev              # run playground at localhost:3000
+pnpm type-check       # typecheck all packages
+pnpm --filter @sweidos/eidos build   # build core package
 ```
 
-The project uses pnpm workspaces. TypeScript strict mode is enabled everywhere.
-
-The naming (`Eidos`) is a placeholder. All references are easy to find/replace — the package name, SW filename, and message prefix are the only places the name appears.
+The project uses pnpm workspaces. TypeScript strict mode throughout.
 
 ---