@biglogic/rgs 3.7.6 → 3.7.9

package/docs/chapters/04-persistence-and-safety.md

@@ -1,125 +1,125 @@
-# 🏗️ Chapter 4: Persistence and Safety - Built like a Tank
-
-In a real-world application, state that vanishes on page refresh is a developer failure. RGS handles data saving **intelligently**.
-
-## 💾 Persistence: "Set and Forget"
-
-When you initialize RGS or a Magnetar, you can enable persistence. But it's not a simple `localStorage.set`.
-
-```typescript
-initState({
-  persist: true,
-  storage: 'local' // or 'session', or a custom adapter
-});
-```
-
-### Advanced Storage: Beyond 5MB
-
-For applications that need to store massive amounts of data (Gigabytes), standard `localStorage` is not enough. RGS provides official plugins for advanced scenarios:
-
-| Technology | Capacity | Purpose | Plugin |
-| :--- | :--- | :--- | :--- |
-| **LocalStorage** | ~5MB | Basic UI settings, small profiles. | Core (Native) |
-| **IndexedDB** | GBs | Offline-first apps, large datasets, logs. | `indexedDBPlugin` |
-| **Cloud Sync** | Unlimited | Remote backup, cross-device sync. | `cloudSyncPlugin` |
-
----
-
-## ☁️ Hybrid Persistence: The "Cloud-Cloud" Strategy
-
-RGS allows you to combine local power with cloud safety. You can store your active data in **IndexedDB** for speed and capacity, while automatically backing it up to a remote database (MongoDB, Firebase, SQL) using the **Cloud Sync Plugin**.
-
-### Why use Cloud Sync?
-- **Differential Updates**: Safely sends only what was changed since the last sync.
-- **Scheduled or On-Demand**: Sync every 5 minutes automatically, or triggered by a "Save to Cloud" button.
-- **Diagnostics**: Track how much data you are syncing and detect errors before they reach the user.
-
----
-
-### What happens under the hood?
-
-```mermaid
-sequenceDiagram
-    participant C as Component
-    participant RGS as Globo State
-    participant S as LocalStorage
-
-    Note over C,RGS: User clicks a button
-    C->>RGS: set('count', 10)
-    RGS-->>C: Update UI (Instant)
-
-    Note over RGS: Waiting 300ms (Debounce)
-
-    RGS->>S: Write to Disk
-    Note right of S: Data saved successfully
-```
-
-- **Debouncing**: If you update the state 100 times in one second, RGS writes to the disk only once at the end. This saves battery life and browser performance.
-- **Selective Persistence**: Don't want to save everything? You can tell RGS which keys to ignore or which ones to save only temporarily.
-
-## 🛡️ Immutability: The Immer Shield
-
-Have you ever had bugs where state changed "mysteriously" because you mutated an array directly? RGS uses **Immer** at its core (the Stellar Engine).
-
-**Dangerous Code (Standard JS):**
-
-```javascript
-const user = store.get('user');
-user.permissions.push('admin'); // BOOM! You mutated the original without triggering a re-render.
-```
-
-**The RGS Way:**
-
-```javascript
-store.set('user', (draft) => {
-  draft.permissions.push('admin'); // SAFE! RGS creates an immutable copy for you.
-});
-```
-
-## 🕵️ Validation: Schema Plugin
-
-Never trust data coming back from the server or saved in the browser 6 months ago. Use the **schemaPlugin**.
-
-```typescript
-import { schemaPlugin } from '@biglogic/rgs';
-import { z } from 'zod'; // Recommended!
-
-const store = initState();
-store._addPlugin(schemaPlugin({
-  price: (val) => typeof val === 'number' && val > 0,
-  email: (val) => val.includes('@')
-}));
-```
-
-If anyone tries to `set('price', -50)`, RGS will block the operation and warn you. **Clean State = Happy App.**
-
----
-
-## ⚠️ Size Limits: maxObjectSize & maxTotalSize
-
-Protect your app from memory issues with automatic size warnings:
-
-```typescript
-const store = initState({
-  // Warn if single value exceeds 5MB (default: 5MB)
-  maxObjectSize: 5 * 1024 * 1024,
-  // Warn if total store exceeds 50MB (default: 50MB)
-  maxTotalSize: 50 * 1024 * 1024
-});
-
-// Setting a value that exceeds the limit will trigger a warning
-store.set('largeData', bigObject); // Warns if > maxObjectSize
-```
-
----
-
-## 💡 Case Study: The Cart that Never Lost an Item
-
-**Challenge**: User adds products, closes the browser, comes back after two days. The cart must still be there, and synced with their account on other devices.
-**RGS Solution**:
-
-1. Enable `indexedDBPlugin` for robust local storage (handles thousands of items).
-2. Use `cloudSyncPlugin` to bridge the local state with your company's MongoDB Atlas or Firebase.
-3. Result? 5-star UX with full data durability and cross-device sync.
-
-**Next step:** [Ecosystem and Plugins: Extending the Power](05-plugins-and-extensibility.md)
+# 🏗️ Chapter 4: Persistence and Safety - Built like a Tank
+
+In a real-world application, state that vanishes on page refresh is a developer failure. RGS handles data saving **intelligently**.
+
+## 💾 Persistence: "Set and Forget"
+
+When you initialize RGS or a Magnetar, you can enable persistence. But it's not a simple `localStorage.set`.
+
+```typescript
+initState({
+  persist: true,
+  storage: 'local' // or 'session', or a custom adapter
+});
+```
+
+### Advanced Storage: Beyond 5MB
+
+For applications that need to store massive amounts of data (Gigabytes), standard `localStorage` is not enough. RGS provides official plugins for advanced scenarios:
+
+| Technology | Capacity | Purpose | Plugin |
+| :--- | :--- | :--- | :--- |
+| **LocalStorage** | ~5MB | Basic UI settings, small profiles. | Core (Native) |
+| **IndexedDB** | GBs | Offline-first apps, large datasets, logs. | `indexedDBPlugin` |
+| **Cloud Sync** | Unlimited | Remote backup, cross-device sync. | `cloudSyncPlugin` |
+
+---
+
+## ☁️ Hybrid Persistence: The "Cloud-Cloud" Strategy
+
+RGS allows you to combine local power with cloud safety. You can store your active data in **IndexedDB** for speed and capacity, while automatically backing it up to a remote database (MongoDB, Firebase, SQL) using the **Cloud Sync Plugin**.
+
+### Why use Cloud Sync?
+- **Differential Updates**: Safely sends only what was changed since the last sync.
+- **Scheduled or On-Demand**: Sync every 5 minutes automatically, or triggered by a "Save to Cloud" button.
+- **Diagnostics**: Track how much data you are syncing and detect errors before they reach the user.
+
+---
+
+### What happens under the hood?
+
+```mermaid
+sequenceDiagram
+    participant C as Component
+    participant RGS as Globo State
+    participant S as LocalStorage
+
+    Note over C,RGS: User clicks a button
+    C->>RGS: set('count', 10)
+    RGS-->>C: Update UI (Instant)
+
+    Note over RGS: Waiting 300ms (Debounce)
+
+    RGS->>S: Write to Disk
+    Note right of S: Data saved successfully
+```
+
+- **Debouncing**: If you update the state 100 times in one second, RGS writes to the disk only once at the end. This saves battery life and browser performance.
+- **Selective Persistence**: Don't want to save everything? You can tell RGS which keys to ignore or which ones to save only temporarily.
+
+## 🛡️ Immutability: The Immer Shield
+
+Have you ever had bugs where state changed "mysteriously" because you mutated an array directly? RGS uses **Immer** at its core (the Stellar Engine).
+
+**Dangerous Code (Standard JS):**
+
+```javascript
+const user = store.get('user');
+user.permissions.push('admin'); // BOOM! You mutated the original without triggering a re-render.
+```
+
+**The RGS Way:**
+
+```javascript
+store.set('user', (draft) => {
+  draft.permissions.push('admin'); // SAFE! RGS creates an immutable copy for you.
+});
+```
+
+## 🕵️ Validation: Schema Plugin
+
+Never trust data coming back from the server or saved in the browser 6 months ago. Use the **schemaPlugin**.
+
+```typescript
+import { schemaPlugin } from '@biglogic/rgs';
+import { z } from 'zod'; // Recommended!
+
+const store = initState();
+store._addPlugin(schemaPlugin({
+  price: (val) => typeof val === 'number' && val > 0,
+  email: (val) => val.includes('@')
+}));
+```
+
+If anyone tries to `set('price', -50)`, RGS will block the operation and warn you. **Clean State = Happy App.**
+
+---
+
+## ⚠️ Size Limits: maxObjectSize & maxTotalSize
+
+Protect your app from memory issues with automatic size warnings:
+
+```typescript
+const store = initState({
+  // Warn if single value exceeds 5MB (default: 5MB)
+  maxObjectSize: 5 * 1024 * 1024,
+  // Warn if total store exceeds 50MB (default: 50MB)
+  maxTotalSize: 50 * 1024 * 1024
+});
+
+// Setting a value that exceeds the limit will trigger a warning
+store.set('largeData', bigObject); // Warns if > maxObjectSize
+```
+
+---
+
+## 💡 Case Study: The Cart that Never Lost an Item
+
+**Challenge**: User adds products, closes the browser, comes back after two days. The cart must still be there, and synced with their account on other devices.
+**RGS Solution**:
+
+1. Enable `indexedDBPlugin` for robust local storage (handles thousands of items).
+2. Use `cloudSyncPlugin` to bridge the local state with your company's MongoDB Atlas or Firebase.
+3. Result? 5-star UX with full data durability and cross-device sync.
+
+**Next step:** [Ecosystem and Plugins: Extending the Power](05-plugins-and-extensibility.md)

package/docs/chapters/05-plugins-and-extensibility.md

@@ -1,190 +1,190 @@
-# 🔌 Chapter 5: Ecosystem and Plugins - Become a Power User
-
-RGS is not a closed box. It's a modular engine that you can extend to cover every business need. All plugins are designed to be "Plug & Play".
-
-## 🔌 Available Plugins
-
-RGS includes 11 official plugins:
-
-| Plugin | Purpose | Import |
-|--------|---------|--------|
-| `devToolsPlugin` | Redux DevTools integration | `rgs` |
-| `debugPlugin` | Console debug access (DEV only) | `rgs` |
-| `indexedDBPlugin` | GB-scale Local Storage | `rgs/advanced` |
-| `cloudSyncPlugin` | Remote Cloud Backup/Sync | `rgs/advanced` |
-| `syncPlugin` | Cross-tab synchronization | `rgs/advanced` |
-| `immerPlugin` | Immer for mutable-style updates | `rgs` |
-| `snapshotPlugin` | Save/restore state snapshots | `rgs` |
-| `undoRedoPlugin` | History management | `rgs` |
-| `schemaPlugin` | Schema validation | `rgs` |
-| `guardPlugin` | Pre-set value transformation | `rgs` |
-| `analyticsPlugin` | Track state changes | `rgs` |
-
-## 🔎 1. DevTools: See Under the Hood
-
-Import the official plugin and you'll see every state change, transaction, and execution time in the console or dev tools (Redux DevTools support included!).
-
-```typescript
-import { devToolsPlugin } from '@biglogic/rgs';
-
-store._addPlugin(devToolsPlugin({ name: 'My Store' }));
-```
-
-## 🐛 2. Debug: Console Access (DEV ONLY)
-
-⚠️ **FOR DEVELOPMENT ONLY** - This plugin is automatically disabled in production.
-
-Access your store directly from the browser console:
-
-```typescript
-import { debugPlugin } from '@biglogic/rgs';
-
-// Always wrap in dev check
-if (process.env.NODE_ENV === 'development') {
-  store._addPlugin(debugPlugin())
-}
-```
-
-Then in the browser console:
-```javascript
-gstate.list()        // View all state
-gstate.get('key')   // Get a value
-gstate.set('key', val) // Set a value
-gstate.info()        // Store info
-gstate.banner()     // Show help
-```
-
-##  2. Cross-Tab Sync: Multi-Tab Magic
-
-Have your app open in three browser tabs? With the `syncPlugin`, if a user changes the theme in one tab, all other tabs update instantly. **Without hitting the server.**
-
-```typescript
-import { syncPlugin } from 'rgs/advanced';
-
-store._addPlugin(syncPlugin({ channelName: 'my_app_sync' }));
-```
-
-## 🔐 3. Encode Option: Base64 Encoding
-
-Use the `encoded` option for simple base64 encoding (not encryption, just obfuscation):
-
-```typescript
-// Per-value encoding
-store.set('token', 'secret-value', { persist: true, encoded: true })
-
-// Or global encoding for all persisted values
-const store = initState({ encoded: true })
-```
-
-> **Note:** Use `encryptionKey` with AES-256-GCM for real security. The `encoded` option is just simple obfuscation.
-
-## 🕐 4. TTL (Time To Live): Expiring Data
-
-Use the `ttl` option in persist to make data expire automatically:
-
-```typescript
-store.set('session_token', tokenValue, {
-  persist: true,
-  ttl: 3600000 // Expires in 1 hour
-});
-```
-
-## 🎲 5. Undo/Redo: History Management
-
-```typescript
-import { undoRedoPlugin } from '@biglogic/rgs';
-
-store._addPlugin(undoRedoPlugin({ limit: 50 }));
-
-// Later...
-store.undo();
-store.redo();
-store.canUndo(); // boolean
-store.canRedo(); // boolean
-```
-
-## 📸 6. Snapshots: Save & Restore State
-
-```typescript
-import { snapshotPlugin } from '@biglogic/rgs';
-
-store._addPlugin(snapshotPlugin());
-
-// Save current state
-store.takeSnapshot('backup_1');
-
-// Restore
-store.restoreSnapshot('backup_1');
-
-// List all snapshots
-store.listSnapshots(); // ['backup_1', ...]
-
-// Delete
-store.deleteSnapshot('backup_1');
-store.clearSnapshots();
-```
-
-## 🛡️ 7. Guard: Pre-Set Transformation
-
-Transform values before they hit the store:
-
-```typescript
-import { guardPlugin } from '@biglogic/rgs';
-
-store._addPlugin(guardPlugin({
-  'user_input': (val) => val.trim().toLowerCase()
-}));
-```
-
-## ✅ 8. Schema: Validation
-
-Validate values before setting:
-
-```typescript
-import { schemaPlugin } from '@biglogic/rgs';
-
-store._addPlugin(schemaPlugin({
-  'email': (val) => {
-    if (typeof val !== 'string') return 'Must be a string';
-    return val.includes('@') ? true : 'Invalid email';
-  }
-}));
-```
-
-## 📊 9. Analytics: Track Changes
-
-```typescript
-import { analyticsPlugin } from '@biglogic/rgs';
-
-store._addPlugin(analyticsPlugin({
-  provider: (event) => {
-    console.log('State changed:', event);
-    // Send to analytics service
-  },
-  keys: ['user', 'cart'] // Only track these keys
-}));
-```
-
-## 🔄 10. Immer Integration
-
-```typescript
-import { immerPlugin } from '@biglogic/rgs';
-
-store._addPlugin(immerPlugin());
-
-// Update nested state with Immer
-store.setWithProduce('user', (draft) => {
-  draft.name = 'New Name';
-  draft.address.city = 'New City';
-});
-```
-
----
-
-## 💡 A Word of Wisdom for Easy & Advanced Scenarios
-
-Plugins are used to **abstract the boring logic**. If you find yourself writing the same `useEffect` to sync two things in 5 different parts of your app... **Stop.** Create a plugin or use an existing one.
-
-The best code is the code you write once and forget about.
-
-**Next step:** [Case Studies: Real-World Production Strategies](06-case-studies.md)
+# 🔌 Chapter 5: Ecosystem and Plugins - Become a Power User
+
+RGS is not a closed box. It's a modular engine that you can extend to cover every business need. All plugins are designed to be "Plug & Play".
+
+## 🔌 Available Plugins
+
+RGS includes 11 official plugins:
+
+| Plugin | Purpose | Import |
+|--------|---------|--------|
+| `devToolsPlugin` | Redux DevTools integration | `rgs` |
+| `debugPlugin` | Console debug access (DEV only) | `rgs` |
+| `indexedDBPlugin` | GB-scale Local Storage | `rgs/advanced` |
+| `cloudSyncPlugin` | Remote Cloud Backup/Sync | `rgs/advanced` |
+| `syncPlugin` | Cross-tab synchronization | `rgs/advanced` |
+| `immerPlugin` | Immer for mutable-style updates | `rgs` |
+| `snapshotPlugin` | Save/restore state snapshots | `rgs` |
+| `undoRedoPlugin` | History management | `rgs` |
+| `schemaPlugin` | Schema validation | `rgs` |
+| `guardPlugin` | Pre-set value transformation | `rgs` |
+| `analyticsPlugin` | Track state changes | `rgs` |
+
+## 🔎 1. DevTools: See Under the Hood
+
+Import the official plugin and you'll see every state change, transaction, and execution time in the console or dev tools (Redux DevTools support included!).
+
+```typescript
+import { devToolsPlugin } from '@biglogic/rgs';
+
+store._addPlugin(devToolsPlugin({ name: 'My Store' }));
+```
+
+## 🐛 2. Debug: Console Access (DEV ONLY)
+
+⚠️ **FOR DEVELOPMENT ONLY** - This plugin is automatically disabled in production.
+
+Access your store directly from the browser console:
+
+```typescript
+import { debugPlugin } from '@biglogic/rgs';
+
+// Always wrap in dev check
+if (process.env.NODE_ENV === 'development') {
+  store._addPlugin(debugPlugin())
+}
+```
+
+Then in the browser console:
+```javascript
+gstate.list()        // View all state
+gstate.get('key')   // Get a value
+gstate.set('key', val) // Set a value
+gstate.info()        // Store info
+gstate.banner()     // Show help
+```
+
+##  2. Cross-Tab Sync: Multi-Tab Magic
+
+Have your app open in three browser tabs? With the `syncPlugin`, if a user changes the theme in one tab, all other tabs update instantly. **Without hitting the server.**
+
+```typescript
+import { syncPlugin } from 'rgs/advanced';
+
+store._addPlugin(syncPlugin({ channelName: 'my_app_sync' }));
+```
+
+## 🔐 3. Encode Option: Base64 Encoding
+
+Use the `encoded` option for simple base64 encoding (not encryption, just obfuscation):
+
+```typescript
+// Per-value encoding
+store.set('token', 'secret-value', { persist: true, encoded: true })
+
+// Or global encoding for all persisted values
+const store = initState({ encoded: true })
+```
+
+> **Note:** Use `encryptionKey` with AES-256-GCM for real security. The `encoded` option is just simple obfuscation.
+
+## 🕐 4. TTL (Time To Live): Expiring Data
+
+Use the `ttl` option in persist to make data expire automatically:
+
+```typescript
+store.set('session_token', tokenValue, {
+  persist: true,
+  ttl: 3600000 // Expires in 1 hour
+});
+```
+
+## 🎲 5. Undo/Redo: History Management
+
+```typescript
+import { undoRedoPlugin } from '@biglogic/rgs';
+
+store._addPlugin(undoRedoPlugin({ limit: 50 }));
+
+// Later...
+store.undo();
+store.redo();
+store.canUndo(); // boolean
+store.canRedo(); // boolean
+```
+
+## 📸 6. Snapshots: Save & Restore State
+
+```typescript
+import { snapshotPlugin } from '@biglogic/rgs';
+
+store._addPlugin(snapshotPlugin());
+
+// Save current state
+store.takeSnapshot('backup_1');
+
+// Restore
+store.restoreSnapshot('backup_1');
+
+// List all snapshots
+store.listSnapshots(); // ['backup_1', ...]
+
+// Delete
+store.deleteSnapshot('backup_1');
+store.clearSnapshots();
+```
+
+## 🛡️ 7. Guard: Pre-Set Transformation
+
+Transform values before they hit the store:
+
+```typescript
+import { guardPlugin } from '@biglogic/rgs';
+
+store._addPlugin(guardPlugin({
+  'user_input': (val) => val.trim().toLowerCase()
+}));
+```
+
+## ✅ 8. Schema: Validation
+
+Validate values before setting:
+
+```typescript
+import { schemaPlugin } from '@biglogic/rgs';
+
+store._addPlugin(schemaPlugin({
+  'email': (val) => {
+    if (typeof val !== 'string') return 'Must be a string';
+    return val.includes('@') ? true : 'Invalid email';
+  }
+}));
+```
+
+## 📊 9. Analytics: Track Changes
+
+```typescript
+import { analyticsPlugin } from '@biglogic/rgs';
+
+store._addPlugin(analyticsPlugin({
+  provider: (event) => {
+    console.log('State changed:', event);
+    // Send to analytics service
+  },
+  keys: ['user', 'cart'] // Only track these keys
+}));
+```
+
+## 🔄 10. Immer Integration
+
+```typescript
+import { immerPlugin } from '@biglogic/rgs';
+
+store._addPlugin(immerPlugin());
+
+// Update nested state with Immer
+store.setWithProduce('user', (draft) => {
+  draft.name = 'New Name';
+  draft.address.city = 'New City';
+});
+```
+
+---
+
+## 💡 A Word of Wisdom for Easy & Advanced Scenarios
+
+Plugins are used to **abstract the boring logic**. If you find yourself writing the same `useEffect` to sync two things in 5 different parts of your app... **Stop.** Create a plugin or use an existing one.
+
+The best code is the code you write once and forget about.
+
+**Next step:** [Case Studies: Real-World Production Strategies](06-case-studies.md)