@braine/quantum-query 1.1.1 → 1.2.1

package/README.md

@@ -1,22 +1,23 @@
 # @braine/quantum-query
 
 **State Management at the Speed of Light.**
-> A unified architecture that merges Store, Actions, and API Logic into single, high-performance "Smart Models".
+> A unified, signal-based architecture that merges Store, Actions, and API Logic into a single, high-performance ecosystem.
 
 [![npm version](https://img.shields.io/npm/v/@braine/quantum-query.svg)](https://www.npmjs.com/package/@braine/quantum-query)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Why "Quantum"?
-Existing libraries behave like "Buses". They stop at every station (component) to check if someone needs to get off (re-render).
+## ⚡️ Why "Quantum"?
+Existing libraries (Redux, RTK Query) behave like "Buses". They stop at every station (component) to check if someone needs to get off (re-render via O(n) selectors).
+
 **Quantum-Query** behaves like a teleporter. It updates *only* the specific component listening to a specific property, instantly.
 
-*   **O(1) Reactivity**: No selectors. No linear scans.
-*   **Zero Boilerplate**: No reduces, no thunks, no providers.
-*   **Enterprise Grade**: Built-in HTTP client with automatic deduplication, retries, and cancellation.
+*   **O(1) Reactivity**: Powered by Atomic Signals. Zero selectors. No "Top-Down" re-renders.
+*   **Zero Boilerplate**: No reducers, no providers, no slices, no thunks.
+*   **Enterprise Ecosystem**: Persistence, Plugins, Deduplication, and Validation included.
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @braine/quantum-query
@@ -24,13 +25,32 @@ npm install @braine/quantum-query
 
 ---
 
-## The "Smart Model" Pattern
+## 🚀 Quick Start (React Hooks)
+
+If you just want to fetch data, it works exactly like you expect.
+
+```typescript
+import { useQuery } from '@braine/quantum-query';
+
+function UserProfile({ id }) {
+    const { data, isLoading } = useQuery({
+        queryKey: ['user', id],
+        queryFn: () => fetch(`/api/user/${id}`).then(r => r.json()),
+        staleTime: 5000 // Auto-cache for 5s
+    });
+
+    if (isLoading) return <div>Loading...</div>;
+    return <div>Hello, {data.name}!</div>;
+}
+```
+
+---
 
-Stop splitting your logic between Redux (Client) and React Query (Server). Use **Smart Models**.
+## 🧠 The "Smart Model" Pattern (Advanced)
 
-### 1. Define It
-`defineModel` wraps your state, computed properties, and actions into one reactive entity.
+Stop splitting your logic between Redux (Client State) and React Query (Server State). **Smart Models** combine state, computed properties, and actions into one reactive entity.
 
+### 1. Define Model
 ```typescript
 import { defineModel } from '@braine/quantum-query';
 
@@ -45,48 +65,47 @@ export const TodoModel = defineModel({
   computed: {
     activeCount() {
       return this.items.length;
+    },
+    isEmpty() {
+      return this.items.length === 0;
     }
   },
 
   // 3. Actions (Sync + Async + Optimistic)
   actions: {
-    async add(text: string) {
-      // Optimistic Update (Instant UI)
-      this.items.push(text);
-      
-      try {
-        await api.post('/todos', { text });
-      } catch (err) {
-        this.items.pop(); // Auto-Rollback
-      }
+    add(text: string) {
+      this.items.push(text); // Direct mutation (proxied)
+    },
+    async save() {
+       await api.post('/todos', { items: this.items });
     }
   }
 });
 ```
 
-### 2. Use It
-Just use it.
-
+### 2. Use Model
 ```tsx
 import { useStore } from '@braine/quantum-query';
 import { TodoModel } from './models/TodoModel';
 
 function TodoApp() {
-  const model = useStore(TodoModel); // Auto-subscribes!
+  // auto-subscribes ONLY to properties accessed in this component
+  const model = useStore(TodoModel); 
 
   return (
-    <button onClick={() => model.add("Ship it")}>
-      Active: {model.activeCount}
-    </button>
+    <div>
+      <h1>Active: {model.activeCount}</h1>
+      <button onClick={() => model.add("Ship it")}>Add</button>
+    </div>
   );
 }
 ```
 
 ---
 
-## Enterprise HTTP Client
+## 🌐 Enterprise HTTP Client
 
-We built a fetch wrapper that matches **RTK Query** in power but keeps **Axios** simplicity.
+We built a fetch wrapper that matches **RTK Query** in power but keeps **Axios** simplicity. It includes **Automatic Deduplication** and **Retries**.
 
 ```typescript
 import { createHttpClient } from '@braine/quantum-query';
@@ -94,9 +113,9 @@ import { createHttpClient } from '@braine/quantum-query';
 export const api = createHttpClient({
   baseURL: 'https://api.myapp.com',
   timeout: 5000, 
-  retry: { retries: 3 }, // Exponential backoff for 5xx/Network errors
+  retry: { retries: 3 }, // Exponential backoff for Network errors
   
-  // Auth Handling
+  // Auth Handling (Auto-Refresh)
   auth: {
     getToken: () => localStorage.getItem('token'),
     onTokenExpired: async () => {
@@ -107,22 +126,87 @@ export const api = createHttpClient({
   }
 });
 
-// Automatic Deduplication
-// If 5 components call this at once, only 1 request is sent!
-const users = await api.get('/users');
+// data is strictly typed!
+const user = await api.get<User>('/me');
+```
+
+---
+
+## 🛡️ Data Integrity (Runtime Safety)
+
+Don't trust the backend. Validate it. We support **Zod**, **Valibot**, or **Yup** schemas directly in the hook.
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.enum(['admin', 'user'])
+});
+
+const { data } = useQuery({
+   queryKey: ['user'],
+   queryFn: fetchUser,
+   schema: UserSchema // Throws descriptive error if API returns garbage
+});
+```
+
+---
+
+## 🔌 Plugin System (Middleware) 🆕
+
+Inject logic into every request lifecycle (Logging, Analytics, Performance Monitoring).
+
+```typescript
+import { queryCache } from '@braine/quantum-query';
+
+queryCache.use({
+    name: 'logger',
+    onFetchStart: (key) => console.log('Fetching', key),
+    onFetchError: (key, error) => console.error(`Fetch failed for ${key}:`, error)
+});
 ```
 
 ---
 
-## Comparison
+## 💾 Persistence Adapter 🆕
+
+Persist your cache to `localStorage` (or IndexedDB/AsyncStorage) automatically. Works offline.
 
-| Feature | Redux Toolkit | TanStack Query | **Quantum-Query** |
+```typescript
+import { persistQueryClient, createLocalStoragePersister } from '@braine/quantum-query/persist';
+
+persistQueryClient({
+    queryClient: queryCache,
+    persister: createLocalStoragePersister(),
+    maxAge: 1000 * 60 * 60 * 24 // 24 hours
+});
+```
+
+---
+
+## 📚 Documentation
+
+*   **[API Reference](docs/api.md)**: Full method signatures and options.
+*   **[Recipes](docs/recipes.md)**: Common patterns (Auth, Infinite Scroll, Optimistic UI).
+*   **[Migration Guide](docs/migration.md)**: Step-by-step guide from RTK Query / Redux.
+
+---
+
+## 🆚 Comparison
+
+| Feature | RTK Query | TanStack Query | **Quantum-Query** |
 | :--- | :--- | :--- | :--- |
-| **Philosophy** | Reducers + Thunks | Server Cache Only | **Unified Smart Models** |
-| **Boilerplate** | High | Medium | **Zero** |
-| **Performance** | O(N) Selectors | Good | **O(1) Direct Access** |
-| **Deduplication**| Yes | Yes | **Yes** |
-| **Bundle Size** | Heavy | Medium | **Tiny (<5kb)** |
+| **Architecture** | Redux (Store + Slices) | Observers | **Atomic Signals** ✅ |
+| **Boilerplate** | High (Provider + Store) | Medium | **Zero** ✅ |
+| **Re-Renders** | Selector-based (O(n)) | Observer-based | **Signal-based (O(1))** ✅ |
+| **Smart Models** | ❌ (Requires Redux) | ❌ | **Built-in** ✅ |
+| **Bundle Size** | ~17kb | ~13kb | **~3kb** ✅ |
+| **Deduplication** | Yes | Yes | **Yes** ✅ |
+| **Persistence** | `redux-persist` | Experimental | **Built-in First Class** ✅ |
+
+---
 
 ## License
 MIT