@biglogic/rgs 3.8.4 → 3.9.1

package/docs/README.md

@@ -1,483 +0,0 @@
-# 🚀 ARGIS (RGS) - Reactive Global State
-
-<div align="center">
-
-> **"Atomic Precision. Immutable Safety. Zen Simplicity."**
-> The state management engine that **won't let you fail**.
-
-[![npm version](https://img.shields.io/npm/v/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-[![npm downloads](https://img.shields.io/npm/dm/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React-19+-61DAFB.svg)](https://react.dev/)
-
-</div>
-
----
-
-## ⚡ TL;DR - Why ARGIS (RGS) Will Change How You Code Forever
-
-```tsx
-// One line. Zero boilerplate. Enterprise-grade power.
-const useUser = gstate({
-  name: 'Alice',
-  cart: [],
-  preferences: { theme: 'dark' }
-})
-
-// That's it. Use it anywhere:
-const name = useUser(s => s.name)
-const theme = useUser(s => s.preferences.theme)
-
-// Mutations? Just write it. Immer handles immutability automatically.
-useUser(s => {
-  s.cart.push({ id: 1, item: 'Coffee Machine', price: 99 })
-})
-```
-
-**Stop fighting your state management. Start building.**
-
----
-
-## 🎯 Why Developers Are **Obsessed** With ARGIS (RGS)
-
-| Feature | Other Libraries | ARGIS (RGS) |
-|---------|----------------|--------------|
-| **API Complexity** | 10+ functions, providers, reducers | **1 function** - `gstate()` |
-| **Immutability** | Manual spreads, Redux boilerplate | **Automatic** - Powered by Immer |
-| **Security** | None | **AES-256 + RBAC + GDPR** built-in |
-| **Persistence** | Manual localStorage/sessionStorage | **First-class** - Auto-save anywhere |
-| **Offline/Cloud Sync** | Non-existent | **Local-First + Cloud Sync** included |
-| **Bundle Size** | 10-50KB+ | **~2KB** minimal / **~32KB** full |
-| **Type Safety** | Partial | **100% TypeScript** out of the box |
-
-### 🔥 The Truth About State Management
-
-Most libraries make you **choose** between:
-- ✗ Simplicity vs Power
-- ✗ Security vs Speed
-- ✗ Offline vs Cloud
-
-**ARGIS (RGS) gives you ALL of it.**
-
----
-
-## 🏆 RGS vs The Competition
-
-| Feature | **RGS (Argis)** | Zustand | Redux Toolkit | Recoil | Jotai |
-|---------|:---:|:---:|:---:|:---:|:---:|
-| **Philosophy** | Zen State | Minimalist | Enterprise Flux | Atomic | Atomic |
-| **API Surface** | **1 Function** | Simple | Complex | Complex | Simple |
-| **Mutations** | **Magic (Immer)** | Manual | Magic | Manual | Manual |
-| **Security** | 🛡️ **AES-256 + RBAC** | ❌ | ❌ | ❌ | ❌ |
-| **Persistence** | 💾 **First-class** | 🔌 | 🔌 | 🔌 | 🔌 |
-| **Local-First Sync** | ✅ **Built-in** | ❌ | ❌ | ❌ | ❌ |
-| **Bundle Size** | **~2KB/32KB** | ~1KB | >10KB | >20KB | ~3KB |
-
-> **RGS is the ONLY library treating Security and Persistence as first-class citizens.**
-
----
-
-## 🚀 Installation
-
-```bash
-# The fastest way to upgrade your React app
-npm install @biglogic/rgs
-```
-
-```bash
-# Or with pnpm
-pnpm add @biglogic/rgs
-
-# Or with yarn
-yarn add @biglogic/rgs
-```
-
----
-
-## 🎮 Quick Start - 30 Seconds to Glory
-
-### The Zen Way (Recommended)
-
-```tsx
-import { gstate } from '@biglogic/rgs'
-
-// ONE line creates a typed store hook
-const useStore = gstate({
-  count: 0,
-  user: { name: 'Alice', email: 'alice@example.com' }
-})
-
-function Counter() {
-  // Type-safe selectors - the React way
-  const count = useStore(s => s.count)
-  const userName = useStore(s => s.user.name)
-
-  // Direct mutations - just write JavaScript
-  const increment = () => useStore(s => { s.count++ })
-
-  return (
-    <div>
-      <h1>Hello, {userName}!</h1>
-      <p>Count: {count}</p>
-      <button onClick={increment}>+1</button>
-    </div>
-  )
-}
-```
-
-### The Classic Way (Global Store)
-
-```tsx
-import { initState, useStore } from '@biglogic/rgs'
-
-// Initialize once at app root
-initState({ namespace: 'myapp' })
-
-// Use anywhere in your app
-const [user, setUser] = useStore('user')
-const [theme, setTheme] = useStore('theme')
-```
-
----
-
-## 🛡️ Enterprise-Grade Security (No Extra Code)
-
-### AES-256-GCM Encryption
-
-```tsx
-// Your sensitive data is encrypted automatically
-const useAuth = gstate({
-  token: 'jwt-token-here',
-  refreshToken: 'refresh-token'
-}, { encoded: true })  // 🔐 AES-256-GCM encryption enabled
-```
-
-### RBAC (Role-Based Access Control)
-
-```tsx
-const store = gstate({
-  adminPanel: { users: [], settings: {} },
-  userProfile: {}
-}, {
-  rbac: {
-    admin: ['adminPanel', 'userProfile'],
-    user: ['userProfile'],
-    guest: []
-  }
-})
-
-// Only admins can touch adminPanel
-store.set('adminPanel', { users: ['new'] }) // ✅ Works for admins
-```
-
-### GDPR Compliance
-
-```tsx
-// Export all user data (GDPR requirement)
-store.exportData()  // Returns JSON of all stored data
-
-// Delete all user data (GDPR "right to be forgotten")
-store.deleteData()
-```
-
----
-
-## 💾 Persistence That Just Works
-
-### Built-in Storage Adapters
-
-```tsx
-// localStorage (default) - survives browser restart
-const useSettings = gstate({ theme: 'dark' }, { persist: true })
-
-// sessionStorage - survives page refresh but not tab close
-const useSession = gstate({ temporary: 'data' }, { storage: 'session' })
-
-// Memory only - for ephemeral data
-const useMemory = gstate({ cache: [] }, { storage: 'memory' })
-
-// IndexedDB - for GB-scale data
-const useBigData = gstate({ dataset: [] })
-store._addPlugin(indexedDBPlugin({ dbName: 'my-app-db' }))
-```
-
----
-
-## 🔌 Plugins Ecosystem - Extend Without Limits
-
-RGS comes with **11+ official plugins** ready to supercharge your app:
-
-| Plugin | Purpose | One-Liner |
-|--------|---------|-----------|
-| `undoRedoPlugin` | Time travel through state | `store.undo()` / `store.redo()` |
-| `syncPlugin` | Cross-tab sync (no server) | `store._addPlugin(syncPlugin(...))` |
-| `indexedDBPlugin` | GB-scale storage | `store._addPlugin(indexedDBPlugin(...))` |
-| `cloudSyncPlugin` | Cloud backup & sync | `store.plugins.cloudSync.sync()` |
-| `devToolsPlugin` | Redux DevTools | `store._addPlugin(devToolsPlugin(...))` |
-| `immerPlugin` | Mutable-style updates | `store.setWithProduce('key', fn)` |
-| `snapshotPlugin` | Save/restore checkpoints | `store.takeSnapshot('backup')` |
-| `schemaPlugin` | Runtime validation | `store._addPlugin(schemaPlugin(...))` |
-| `guardPlugin` | Transform on set | `store._addPlugin(guardPlugin(...))` |
-| `analyticsPlugin` | Track changes | `store._addPlugin(analyticsPlugin(...))` |
-| `debugPlugin` | Console access (DEV) | `window.gstate.list()` |
-
-### Undo/Redo - Never Lose Work
-
-```tsx
-import { undoRedoPlugin } from '@biglogic/rgs'
-
-const store = gstate({ text: '' })
-store._addPlugin(undoRedoPlugin({ limit: 50 }))
-
-// User makes changes...
-store.set('text', 'Hello World')
-store.set('text', 'Hello Universe')
-
-// Oops! Let's go back
-store.undo()  // Returns to 'Hello World'
-store.redo()   // Returns to 'Hello Universe'
-```
-
-### Cross-Tab Sync - Real-Time Everywhere
-
-```tsx
-import { syncPlugin } from '@biglogic/rgs/advanced'
-
-const store = gstate({ theme: 'light' })
-store._addPlugin(syncPlugin({ channelName: 'my-app' }))
-
-// Change in Tab 1 → Instantly updates Tab 2, Tab 3, etc.
-// ZERO server calls. Pure browser magic.
-```
-
-### Cloud Sync - Your Data, Everywhere
-
-```tsx
-import { cloudSyncPlugin, createMongoAdapter } from '@biglogic/rgs/advanced'
-
-const adapter = createMongoAdapter(
-  'https://data.mongodb-api.com/...',
-  'your-api-key'
-)
-
-const store = gstate({ todos: [] })
-store._addPlugin(cloudSyncPlugin({
-  adapter,
-  autoSyncInterval: 30000  // Every 30 seconds
-}))
-
-// Manual sync when needed
-await store.plugins.cloudSync.sync()
-```
-
----
-
-## ☁️ Local-First Sync - Offline by Default
-
-The **killer feature** that makes RGS unique:
-
-```tsx
-import { gstate, useSyncedState } from '@biglogic/rgs'
-
-// Create store with automatic offline-first sync
-const store = gstate({
-  todos: [],
-  user: null
-}, {
-  namespace: 'myapp',
-  sync: {
-    endpoint: 'https://api.example.com/sync',
-    authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,
-    syncOnReconnect: true,
-    strategy: 'last-write-wins'
-  }
-})
-
-// Works offline. Automatically syncs when online.
-function TodoList() {
-  const [todos, setTodos] = useSyncedState('todos')
-
-  const addTodo = (text) => {
-    setTodos([...todos, { id: Date.now(), text }])
-    // Synced automatically! ✨
-  }
-
-  return <ul>{todos.map(t => <li>{t.text}</li>)}</ul>
-}
-```
-
----
-
-## ⚡ Advanced Superpowers
-
-### Computed Values (Derived State)
-
-```tsx
-const store = gstate({
-  firstName: 'John',
-  lastName: 'Doe'
-})
-
-// Auto-calculated derived state
-store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)
-
-const fullName = store.get('fullName') // "John Doe"
-```
-
-### Error Handling
-
-```tsx
-const store = gstate({ data: null }, {
-  onError: (error, context) => {
-    console.error(`Error in ${context.operation}:`, error.message)
-    // Send to Sentry, Datadog, etc.
-  }
-})
-```
-
-### Size Limits (Memory Protection)
-
-```tsx
-const store = gstate({ data: {} }, {
-  maxObjectSize: 5 * 1024 * 1024,  // Warn if single value > 5MB
-  maxTotalSize: 50 * 1024 * 1024    // Warn if total > 50MB
-})
-```
-
----
-
-## 📦 Build Sizes - Choose Your Weapon
-
-### Minimal Version (~0.16 KB)
-For embedded systems, widgets, IoT:
-
-```javascript
-import { createStore } from '@biglogic/rgs/core/minimal'
-
-const store = createStore({ count: 0 })
-store.get('count')        // → 0
-store.set('count', 5)     // → true
-```
-
-### Full Version (~32 KB)
-For production React apps with all features:
-
-```javascript
-import { gstate, createStore } from '@biglogic/rgs'
-
-const useCounter = gstate({ count: 0 })
-const count = useCounter(s => s.count)
-```
-
-| Version | Size | Use Case |
-|---------|------|----------|
-| **Minimal** | 0.16 KB | Embedded, IoT, Widgets |
-| **Full** | ~32 KB | React Apps, Enterprise |
-
----
-
-## 🧪 Testing - Rock-Solid Reliability
-
-```bash
-# Run unit tests
-npm run test
-
-# Run E2E tests (Playwright)
-npm run test:e2e
-```
-
-- ✅ **100+ Unit Tests** (Jest) - Core logic, stores, hooks
-- ✅ **E2E Tests** (Playwright) - Real browser, cross-tab sync
-- ✅ **Concurrency Testing** - Race condition verification
-- ✅ **Security Tests** - AES-256, RBAC, GDPR
-
----
-
-## 🏗️ Architecture
-
-```mermaid
-graph TB
-    subgraph API
-        A[gstate] --> D[IStore]
-        B[useStore] --> D
-        C[createStore] --> D
-    end
-
-    D --> E[Storage Adapter]
-    D --> F[Immer Proxy]
-    D --> G[Plugins]
-    D --> H[Security]
-    D --> I[Async Store]
-
-    E --> J[local]
-    E --> K[session]
-    E --> L[memory]
-
-    G --> M[UndoRedo]
-    G --> N[Sync]
-    G --> O[Schema]
-    G --> P[Analytics]
-```
-
-### Core Components
-
-| Component | Description |
-|-----------|-------------|
-| **gstate()** | Creates store + hook in one line |
-| **useStore()** | React hook for subscribing to state |
-| **createStore()** | Classic store factory |
-| **IStore** | Core interface with get/set/subscribe |
-| **StorageAdapters** | local, session, memory persistence |
-| **Plugins** | Immer, Undo/Redo, Sync, Schema, etc. |
-| **Security** | Encryption, RBAC, GDPR consent |
-
----
-
-## 📚 Documentation
-
-- [Getting Started](docs/chapters/02-getting-started.md)
-- [Plugin SDK](docs/chapters/05-plugin-sdk.md)
-- [Security Architecture](docs/chapters/09-security-architecture.md)
-- [Migration Guide](docs/chapters/08-migration-guide.md)
-- [API Reference](docs/api.md)
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.
-
-```bash
-# Clone and setup
-git clone https://github.com/BigLogic-ca/rgs.git
-cd rgs
-npm install
-
-# Run tests
-npm run test
-```
-
----
-
-## 📄 License
-
-**MIT** © [Dario Passariello](https://github.com/passariello)
-
----
-
-<div align="center">
-
-## 🔥 Built for Those Who Demand **Excellence**
-
-[![Powered by Immer](https://img.shields.io/badge/Powered%20by-Immer-2ECC71.svg)](https://github.com/immerjs/immer)
-[![Typed with TypeScript](https://img.shields.io/badge/Typed%20with-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
-[![Tested with Jest](https://img.shields.io/badge/Tested%20with-Jest-C21325.svg)](https://jestjs.io/)
-[![E2E with Playwright](https://img.shields.io/badge/E2E%20with-Playwright-2ECC71.svg)](https://playwright.dev/)
-
-**Made with ❤️ and a lot of caffè espresso!**
-
-[⬆ Back to top](#-argis-rgs---reactive-global-state)
-
-</div>

package/docs/SUMMARY.md

@@ -1,55 +0,0 @@
-# 🌌 Argis (RGS) - Reactive Global State: The Final Guide
-
-Welcome to the definitive documentation for **Reactive Global State (RGS)**. If you are here, you're likely tired of endless boilerplate, complex configurations, and state management tools that seem to require a PhD in rocket science.
-
-This documentation is written for everyone: from **easy setup** for those who just want things to work, to **advanced implementation** for those who want to master the engine.
-
----
-
-## 🗺️ Summary
-
-- **[The Philosophy: Panzer vs. Bicycle](chapters/philosophy.md)**
-  - Reliability and Security as First-Class Citizens.
-  - The "Ironclad" Core: Simplicity meets Power.
-
-- **[Quick Start: 30-Second Setup](chapters/getting-started.md)**
-  - Deploying the RGS Panzer in your React project.
-
-- **[The Magnetar Way: One-Liner Power](chapters/the-magnetar-way.md)**
-  - Creating stores and hooks simultaneously. Types included.
-
-- **[Persistence and Safety](chapters/persistence-and-safety.md)**
-  - Never lose user data again (without localStorage headaches).
-  - Native immutability with Immer (Stellar Engine).
-
-- **[Ecosystem and Plugins](chapters/plugins-and-extensibility.md)**
-  - DevTools, Cross-Tab Sync, Analytics, and Typed Plugins.
-
-- **[Plugin SDK: Build Your Own Extensions](chapters/plugin-sdk.md)**
-  - Create custom plugins with lifecycle hooks.
-  - Register methods via `store.plugins`.
-  - Full API reference and examples.
-
-- **[Case Studies: Real World Strategies](chapters/case-studies.md)**
-  - **E-commerce**: Cart isolation and atomic updates.
-  - **Dashboards**: Multi-store strategies and complex flows.
-
-- **[Architectural Insights (FAQ)](chapters/07-faq.md)**
-  - Honest answers on security, performance, and Proxies.
-
-- **[Migration Guide](chapters/migration-guide.md)**
-  - Upgrading to latest version (Enterprise Isolation)
-  - Upgrading to previous version (`secure` → `encoded`)
-
-- **[Security Architecture & Hardening](chapters/security-architecture.md)**
-  - Advanced XSS prevention and deep cloning reliability.
-  - AES-256-GCM and RBAC.
-
-- **[Local-First Sync Engine](chapters/local-first-sync.md)**
-  - Offline-by-default with automatic background sync.
-  - Conflict resolution strategies (last-write-wins, merge, etc.).
-  - `useSyncedState` hook for React components.
-
----
-
-> *"Make things simple, but not simpler than necessary."* – RGS Team

package/docs/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-modernist

package/docs/chapters/case-studies.md

@@ -1,69 +0,0 @@
-# 🛒 Chapter 6: Case Studies - Real Strategies
-
-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/docs/chapters/faq.md

@@ -1,53 +0,0 @@
-# ❓ Chapter 7: FAQ - Architectural Insights
-
-This section provides technical context for the design decisions behind RGS (Argis) - Reactive Global 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.