@biglogic/rgs 2.7.0

package/dist/markdown/chapters/05-plugin-sdk.md

@@ -0,0 +1,290 @@
+# 🔧 Plugin SDK: Build Your Own Extensions
+
+This guide shows you how to create custom plugins for RGS (Argis) - React Globo State. Plugins are the way to extend the store with custom functionality.
+
+---
+
+## 📦 What is a Plugin?
+
+A plugin is a module that:
+
+1. Adds **lifecycle hooks** to react to store events
+2. Exposes **custom methods** via `store.plugins.yourPlugin.method()`
+3. Can **validate**, **transform**, or **track** data
+
+---
+
+## 🏗️ Plugin Structure
+
+Every plugin implements the `IPlugin` interface:
+
+```typescript
+import type { IPlugin, PluginContext } from 'argis'
+
+interface IPlugin {
+  name: string
+  hooks: {
+    onInit?: (ctx: PluginContext) => void | Promise<void>
+    onInstall?: (ctx: PluginContext) => void | Promise<void>
+    onSet?: (ctx: PluginContext) => void | Promise<void>
+    onGet?: (ctx: PluginContext) => void | Promise<void>
+    onRemove?: (ctx: PluginContext) => void | Promise<void>
+    onDestroy?: (ctx: PluginContext) => void | Promise<void>
+    onTransaction?: (ctx: PluginContext) => void | Promise<void>
+    onBeforeSet?: (ctx: PluginContext) => void | Promise<void>
+    onAfterSet?: (ctx: PluginContext) => void | Promise<void>
+  }
+}
+```
+
+---
+
+## 🎯 Creating Your First Plugin
+
+### Example: A Simple Logger Plugin
+
+```typescript
+import type { IPlugin, PluginContext } from 'argis'
+
+export const loggerPlugin = (): IPlugin => {
+  return {
+    name: 'my-logger',
+    hooks: {
+      onSet: ({ key, value }: PluginContext) => {
+        console.log(`[Logger] Set "${key}" to:`, value)
+      },
+      onGet: ({ key, value }: PluginContext) => {
+        console.log(`[Logger] Got "${key}":`, value)
+      },
+      onRemove: ({ key }: PluginContext) => {
+        console.log(`[Logger] Removed "${key}"`)
+      }
+    }
+  }
+}
+
+// Usage
+store._addPlugin(loggerPlugin())
+```
+
+---
+
+## 🔌 Registering Custom Methods
+
+Plugins can expose methods accessible via `store.plugins.pluginName.methodName()`:
+
+```typescript
+import type { IPlugin, PluginContext } from 'argis'
+
+export const counterPlugin = (): IPlugin => {
+  let _count = 0
+
+  return {
+    name: 'counter',
+    hooks: {
+      onInstall: ({ store }) => {
+        // Register methods with explicit plugin namespace
+        store._registerMethod('counter', 'increment', () => {
+          _count++
+          return _count
+        })
+
+        store._registerMethod('counter', 'decrement', () => {
+          _count--
+          return _count
+        })
+
+        store._registerMethod('counter', 'getCount', () => _count)
+
+        store._registerMethod('counter', 'reset', () => {
+          _count = 0
+          return _count
+        })
+      }
+    }
+  }
+}
+
+// Usage
+store._addPlugin(counterPlugin())
+
+store.plugins.counter.increment()   // returns 1
+store.plugins.counter.increment()  // returns 2
+store.plugins.counter.getCount()  // returns 2
+store.plugins.counter.decrement()  // returns 1
+store.plugins.counter.reset()      // returns 0
+```
+
+---
+
+## ⚙️ Plugin Configuration
+
+Plugins can accept configuration options:
+
+```typescript
+interface ValidationConfig {
+  email?: (value: string) => boolean | string
+  username?: (value: string) => boolean | string
+  maxLength?: number
+}
+
+export const validationPlugin = (config: ValidationConfig): IPlugin => {
+  return {
+    name: 'validation',
+    hooks: {
+      onBeforeSet: ({ key, value }) => {
+        const validator = config[key as keyof ValidationConfig]
+        if (validator && typeof value === 'string') {
+          const result = validator(value)
+          if (result !== true) {
+            throw new Error(`Validation failed for "${key}": ${result}`)
+          }
+        }
+
+        // Check maxLength
+        if (config.maxLength && typeof value === 'string' && value.length > config.maxLength) {
+          throw new Error(`"${key}" exceeds max length of ${config.maxLength}`)
+        }
+      }
+    }
+  }
+}
+
+// Usage
+store._addPlugin(validationPlugin({
+  email: (v) => v.includes('@') ? true : 'Invalid email',
+  username: (v) => v.length >= 3 ? true : 'Too short',
+  maxLength: 100
+}))
+```
+
+---
+
+## 🔄 Using Store Internals
+
+Plugins have access to internal store methods:
+
+```typescript
+export const auditPlugin = (): IPlugin => {
+  return {
+    name: 'audit',
+    hooks: {
+      onSet: ({ store, key, value, version }) => {
+        // Read other keys
+        const currentUser = store.get('currentUser')
+
+        // Set silently (without triggering hooks)
+        store._setSilently('_auditLog', [
+          ...(store.get('_auditLog') || []),
+          { action: 'set', key, timestamp: Date.now() }
+        ])
+
+        // Get version
+        const ver = store._getVersion(key)
+      }
+    }
+  }
+}
+```
+
+### Available Internal Methods
+
+| Method | Description |
+|--------|-------------|
+| `store.get(key)` | Get a value |
+| `store.set(key, value)` | Set a value |
+| `store._setSilently(key, value)` | Set without triggering hooks |
+| `store.list()` | Get all key-value pairs |
+| `store._getVersion(key)` | Get version number |
+| `store._subscribe(callback)` | Subscribe to changes |
+
+---
+
+## 🧪 Full Example: Persistence Plugin
+
+Here's a complete plugin that auto-saves to a custom backend:
+
+```typescript
+import type { IPlugin, PluginContext } from 'argis'
+
+interface AutoSaveConfig {
+  endpoint: string
+  debounceMs?: number
+  keys?: string[]  // Which keys to save
+}
+
+export const autoSavePlugin = (config: AutoSaveConfig): IPlugin => {
+  const { endpoint, debounceMs = 1000, keys } = config
+  let _saveTimeout: ReturnType<typeof setTimeout> | null = null
+
+  const save = async (store: any) => {
+    const data = keys
+      ? Object.fromEntries(keys.map(k => [k, store.get(k)]))
+      : store.list()
+
+    try {
+      await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data)
+      })
+      console.log('[AutoSave] Saved to', endpoint)
+    } catch (err) {
+      console.error('[AutoSave] Failed:', err)
+    }
+  }
+
+  return {
+    name: 'auto-save',
+    hooks: {
+      onInstall: async ({ store }) => {
+        // Load initial data
+        try {
+          const res = await fetch(endpoint)
+          const data = await res.json()
+          Object.entries(data).forEach(([k, v]) => {
+            store._setSilently(k, v)
+          })
+        } catch {
+          // Ignore load errors
+        }
+      },
+      onSet: ({ store }) => {
+        // Debounced save
+        if (_saveTimeout) clearTimeout(_saveTimeout)
+        _saveTimeout = setTimeout(() => save(store), debounceMs)
+      },
+      onDestroy: ({ store }) => {
+        // Save immediately on destroy
+        if (_saveTimeout) clearTimeout(_saveTimeout)
+        save(store)
+      }
+    }
+  }
+}
+
+// Usage
+store._addPlugin(autoSavePlugin({
+  endpoint: '/api/save',
+  debounceMs: 2000,
+  keys: ['user', 'settings', 'preferences']
+}))
+```
+
+---
+
+## 📋 Plugin Best Practices
+
+1. **Use Namespaced Methods** - Always use `store._registerMethod('pluginName', 'method', fn)`
+2. **Clean Up Resources** - Use `onDestroy` to clean up timers, listeners, etc.
+3. **Handle Errors** - Wrap async operations in try/catch
+4. **Document Configuration** - Provide clear TypeScript interfaces
+5. **Test Hooks** - Test each hook independently
+
+---
+
+## 📚 Related
+
+- [Plugin API Reference](../api/plugins.md)
+- [Chapter 5: Ecosystem and Plugins](05-plugins-and-extensibility.md)
+- [Case Studies](06-case-studies.md)

package/dist/markdown/chapters/05-plugins-and-extensibility.md

@@ -0,0 +1,174 @@
+# 🔌 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 8 official plugins:
+
+| Plugin | Purpose | Import |
+|--------|---------|--------|
+| `devToolsPlugin` | Redux DevTools integration | `rgs` |
+| `debugPlugin` | Console debug access (DEV only) | `rgs` |
+| `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 'argis';
+
+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 'argis';
+
+// 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. 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
+});
+```
+
+## 🎲 4. Undo/Redo: History Management
+
+```typescript
+import { undoRedoPlugin } from 'argis';
+
+store._addPlugin(undoRedoPlugin({ limit: 50 }));
+
+// Later...
+store.undo();
+store.redo();
+store.canUndo(); // boolean
+store.canRedo(); // boolean
+```
+
+## 📸 5. Snapshots: Save & Restore State
+
+```typescript
+import { snapshotPlugin } from 'argis';
+
+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();
+```
+
+## 🛡️ 6. Guard: Pre-Set Transformation
+
+Transform values before they hit the store:
+
+```typescript
+import { guardPlugin } from 'argis';
+
+store._addPlugin(guardPlugin({
+  'user_input': (val) => val.trim().toLowerCase()
+}));
+```
+
+## ✅ 7. Schema: Validation
+
+Validate values before setting:
+
+```typescript
+import { schemaPlugin } from 'argis';
+
+store._addPlugin(schemaPlugin({
+  'email': (val) => {
+    if (typeof val !== 'string') return 'Must be a string';
+    return val.includes('@') ? true : 'Invalid email';
+  }
+}));
+```
+
+## 📊 8. Analytics: Track Changes
+
+```typescript
+import { analyticsPlugin } from 'argis';
+
+store._addPlugin(analyticsPlugin({
+  provider: (event) => {
+    console.log('State changed:', event);
+    // Send to analytics service
+  },
+  keys: ['user', 'cart'] // Only track these keys
+}));
+```
+
+## 🔄 9. Immer Integration
+
+```typescript
+import { immerPlugin } from 'argis';
+
+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)

package/dist/markdown/chapters/06-case-studies.md

@@ -0,0 +1,69 @@
+# 🛒 Chapter 6: Case Studies - Real Strategies for Real People
+
+In this chapter, we put theory aside and see how RGS solves the problems that keep you up at night (or at least frustrated in the office).
+
+---
+
+## 🍎 Case 1: High-Performance E-commerce
+
+**The Problem**: A shopping cart with 50 items, complex sidebar filters, and a product list that must update without "jumping" the whole page.
+
+**The RGS Strategy**:
+
+1. **Atomic Filters**: Don't save the entire filters object. Use separate keys (`category`, `priceRange`, `search`). This way, if the user only changes the price, the search bar doesn't re-render.
+2. **Persistent Cart**: Use `gstate` with a `cart` namespace.
+3. **Computed State for Totals**:
+
+   ```javascript
+   cartStore.compute('totalAmount', ['items'], (s) =>
+     s.items.reduce((acc, curr) => acc + curr.price, 0)
+   );
+   ```
+
+**Why do this?** Because the component displaying the total price updates *only* when the `items` array changes, not when the user's name or shipping address changes. **Zero waste.**
+
+---
+
+## 📊 Case 2: Real-time Dashboard (Sockets/Events)
+
+**The Problem**: You receive thousands of updates via WebSocket (e.g., crypto prices or server notifications), and React can't keep up.
+
+**The RGS Strategy**:
+
+1. **Atomic Transactions**: In RGS, you can group updates.
+
+   ```javascript
+   socket.on('bulk_update', (data) => {
+     store.transaction(() => {
+       data.forEach(item => store.set(`price_${item.id}`, item.price));
+     });
+   });
+   ```
+
+**Why do this?** Instead of triggering 100 React updates, the `transaction` triggers **only one** at the end. Your dashboard's performance will go from "tractor" to "Ferrari".
+
+---
+
+## 🏦 Case 3: Multi-Step Forms (User Onboarding)
+
+**The Problem**: A signup form with 5 steps. If the user hits "Back" or refreshes the page, they lose everything.
+
+**The RGS Strategy**:
+
+1. Use a dedicated `gstate` called `onboarding`.
+2. Enable `persist: true`.
+3. At each step, just call `set('step1', values)`.
+**Why do this?** Because you don't have to manage manual saving logic. When the user returns, the fields are already populated. At the very end (Step 5), call `store.destroy()` to clean up. Clean and elegant.
+
+---
+
+## 🛡️ Message for Advanced Architects
+
+*"But I could do all this with a custom cache and an event bus..."*
+Sure you could. You could also walk to work instead of driving. But RGS is the car: it's tested, it handles edge cases (closed tabs, full storage, corrupted types), and it lets you focus on **business logic**, not infrastructure.
+
+Stop reinventing the wheel. Use RGS.
+
+---
+
+**Next step:** [FAQ: For the Skeptics and the Curious](07-faq.md)

package/dist/markdown/chapters/07-faq.md

@@ -0,0 +1,53 @@
+# ❓ Chapter 7: FAQ - Architectural Insights
+
+This section provides technical context for the design decisions behind RGS (Argis) - React Globo State.
+
+## 1. "Why integrate Security and GDPR into the State layer?"
+
+**The Rationale:** In enterprise environments, ensuring that every data access is authorized is critical. By integrating **RBAC** and **Auditing** directly into the store instance, we provide a "Secure-by-Default" architecture. This prevents common oversights where developers might forget to apply permission checks in custom middleware or component logic.
+
+## 2. "How does RGS compare to the React Context API?"
+
+**The Technical Difference:** Context is a dependency injection tool. When values change, React often triggers broad re-renders across the consumer tree. RGS uses a **Surgical Subscription** model. Only components observing a specific key are notified of changes, ensuring optimal performance even in data-heavy applications.
+
+## 3. "Is there a performance overhead for Safety Features?"
+
+**The Trade-off:** Capabilities like deep freezing (immutability) and sanitization do introduce a small computational cost (typically 1-2ms). We believe this is a worthwhile investment to prevent accidental state mutations and security vulnerabilities. For performance-critical scenarios (like high-frequency animations), these features can be selectively disabled.
+
+## 4. "How is Type Safety handled with string keys?"
+
+**The Approach:** String keys provide the flexibility needed for dynamic and runtime-generated state namespaces. For developers requiring strict type safety, RGS offers the `gstate` factory and `GStatePlugins` augmentation, allowing you to define a fully typed interface for your store and its plugins.
+
+## 5. "What logic dictates the use of 'Ghost Stores'?"
+
+**Operational Resilience:** Many applications experience race conditions during hydration or initialization. Instead of allowing the application to crash due to an uninitialized reference, RGS returns a protective Proxy. This Proxy logs a developer warning while providing a safe fallback, ensuring the user interface remains functional while the developer addresses the initialization sequence.
+
+## 6. "Is it compatible with modern React patterns (SSR/Next.js)?"
+
+**Yes.** RGS is built on top of `useSyncExternalStore` and is fully compatible with Concurrent Rendering and Server-Side Rendering (SSR). It works seamlessly with Next.js, Remix, and other modern frameworks without hydration mismatch issues.
+
+## 7. "Where do the best practices and improvements come from?"
+
+**The Process:** All improvements and best practices are based on:
+
+- **Official React Documentation** - useSyncExternalStore for SSR, hooks rules, React 18/19 features
+- **TypeScript Best Practices** - Type safety patterns, generics, strict mode
+- **Security Standards** - OWASP for XSS prevention, AES-256-GCM encryption, RBAC patterns
+- **Community Libraries** - Patterns from Zustand, Redux, Jotai for plugin architecture
+- **Enterprise Patterns** - Error handling, multi-store isolation, GDPR compliance
+
+Key fixes (like security isolation per-store, Immer optional loading) come from common issues in similar libraries.
+
+---
+
+## 🛑 Best Practices: Maximizing Reliability
+
+1. **State Granularity**: Use RGS for global, persistent, or secured data. For transient UI state (like toggle transitions), standard `useState` is more appropriate.
+2. **Namespace Management**: Always define a unique namespace for your store to prevent data collisions in shared domain environments.
+3. **Rule Validation**: Ensure your RBAC rules are tested against your expected key patterns to maintain a robust security posture.
+
+---
+
+## 👋 Conclusion
+
+RGS is designed for teams that prioritize long-term maintainability and system stability. By handling the complexities of security and persistence at the architectural level, we allow developers to focus on building features with confidence.