@sweidos/eidos 1.0.16 → 1.0.19

package/README.md

@@ -72,7 +72,7 @@ pnpm add @sweidos/eidos
 cp node_modules/@sweidos/eidos/dist/eidos-sw.js public/eidos-sw.js
 ```
 
-> **Vite users** — automate this with the [Vite plugin snippet](#vite-plugin).
+> **Vite users** — use the [first-class Vite plugin](#vite-plugin) to automate this.
 
 ### 3. Wrap your app
 
@@ -115,7 +115,16 @@ export const createOrder = action(
 ### 5. Use in components
 
 ```tsx
-// TanStack Query
+// TanStack Query — first-class hooks
+import { useEidosQuery, useEidosMutation } from '@sweidos/eidos/query'
+
+const { data, isPending } = useEidosQuery<Product[]>(products)
+
+const mutation = useEidosMutation(createOrder, {
+  invalidates: [products], // clears cache + refetches on success
+})
+
+// Or with plain useQuery
 const { data } = useQuery(products.query<Product[]>())
 
 // Or plain async
@@ -145,6 +154,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 +305,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 +391,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 +475,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()` |
 
 ---
 
@@ -401,26 +508,96 @@ eidos/
 
 ## Vite Plugin
 
-Automatically copy `eidos-sw.js` into `public/` on build:
+`@sweidos/eidos` ships a first-class Vite plugin via the `@sweidos/eidos/vite` subpath. It automatically copies `eidos-sw.js` from the installed package into your `public/` directory on every build and dev-server start — keeping the SW in sync with the installed version.
 
 ```ts
 // vite.config.ts
-import { copyFileSync } from 'fs'
-import { resolve } from 'path'
-
-function eidosPlugin() {
-  return {
-    name: 'eidos-sw',
-    buildStart() {
-      copyFileSync(
-        resolve('./node_modules/@sweidos/eidos/dist/eidos-sw.js'),
-        resolve('./public/eidos-sw.js'),
-      )
+import { eidos } from '@sweidos/eidos/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [eidos()],
+})
+```
+
+**Options:**
+
+```ts
+eidos({
+  swDest: 'public/eidos-sw.js', // default — relative to project root
+})
+```
+
+No more manual `cp` step. The plugin runs on `buildStart` (prod builds) and `configureServer` (dev).
+
+---
+
+## TanStack Query Integration
+
+`@sweidos/eidos/query` provides first-class hooks for [TanStack Query v5](https://tanstack.com/query/latest). Requires `@tanstack/react-query` — already optional in Eidos, just install it.
+
+### Setup (once)
+
+```ts
+// main.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { withEidosQueryClient } from '@sweidos/eidos/query'
+
+const queryClient = new QueryClient()
+withEidosQueryClient(queryClient) // bridges handle.invalidate() → TQ cache
+
+root.render(
+  <QueryClientProvider client={queryClient}>
+    <EidosProvider swPath="/eidos-sw.js">
+      <App />
+    </EidosProvider>
+  </QueryClientProvider>
+)
+```
+
+### `useEidosQuery(handle, options?)`
+
+Wraps `useQuery` with Eidos-smart defaults:
+- `networkMode: 'always'` — Eidos owns offline; queries run even when `navigator.onLine` is false
+- `retry: false` — Eidos handles retries at the SW/replay layer
+
+```tsx
+import { useEidosQuery } from '@sweidos/eidos/query'
+
+function ProductList() {
+  const { data, isPending, isError } = useEidosQuery<Product[]>(products)
+  // ...
+}
+```
+
+### `useEidosMutation(handle, options?)`
+
+Wraps `useMutation` for a single-argument action handle:
+- `networkMode: 'always'` — action queues offline automatically
+- `invalidates` — clears Eidos cache + invalidates TQ entries on success
+
+```tsx
+import { useEidosMutation } from '@sweidos/eidos/query'
+
+function OrderForm() {
+  const mutation = useEidosMutation(createOrder, {
+    invalidates: [products],           // refetch product list after order
+    onSuccess(data) {
+      if ('queued' in data) toast('Saved offline — will sync when back online')
+      else toast(`Order #${data.id} created!`)
     },
-  }
+  })
+
+  return <button onClick={() => mutation.mutate({ productId: 1, qty: 2 })}>Buy</button>
 }
 ```
 
+### `withEidosQueryClient(client)`
+
+Registers a `QueryClient` with Eidos. After calling this:
+- `handle.invalidate()` also calls `queryClient.invalidateQueries({ queryKey: ['eidos', url] })`
+- Both systems stay in sync automatically, even when cache is cleared outside of mutations
+
 ---
 
 ## Known Limitations
@@ -428,7 +605,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,12 +617,12 @@ 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
-- [ ] Vite plugin (first-class, published separately)
-- [ ] Vue / Svelte bindings
-- [ ] TanStack Query integration package
+- [x] URL pattern matching (`*`, `**`, `:param`)
+- [x] Cross-origin resource support
+- [x] Background Sync API integration
+- [x] Vite plugin (`@sweidos/eidos/vite` subpath — ships in the main package)
+- [x] Vue / Svelte bindings (framework-agnostic reactive stores)
+- [x] TanStack Query integration (`@sweidos/eidos/query` subpath — `useEidosQuery`, `useEidosMutation`, `withEidosQueryClient`)
 
 ---