@biglogic/rgs 3.8.4 → 3.9.2

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

@@ -1,125 +0,0 @@
-# 🏗️ 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/philosophy.md

@@ -1,54 +0,0 @@
-# 🧠 Chapter 1: The Philosophy - Panzer vs. Bicycle
-
-You are a developer. You have deadlines. You have bugs. But more importantly, you have a reputation to protect.
-
-## 🚜 Choose Your Vehicle
-
-Most state managers focus on being "lightweight" or "easy." **RGS (Argis)** has evolved beyond that. It is a framework designed for high-stakes applications where data leakage is a disaster and production uptime is non-negotiable.
-
-### The Bicycle (Standard Hooks/Context)
-
-If you just need a counter for a simple todo list, use a basic hook or `useState`. You don't need a Panzer to go to the grocery store. It's light, it's fast to set up, but it offers zero protection when the road gets rough.
-
-### The Panzer (RGS)
-
-If you are building an Enterprise platform where:
-
-- **Isolation is King**: User A's data must never collide with User B's state.
-- **Fail-Safe Security**: RBAC (Role-Based Access Control) is built into the state layer.
-- **Resilience**: The app must survive uninitialized states without crashing (`Ghost Stores`).
-
-...then you need a Panzer. **You need RGS.**
-
----
-
-## 🚀 Surgical Performance: Atomic Access
-
-RGS was born from a "crazy" idea: **State should be global by nature, but atomic by access.**
-
-### 🔴 Camp A: Context API (The Re-render Rain)
-
-In React Context, any change in the provider forces a global re-render of the entire tree consuming it. Change a theme brand color? The whole product list re-renders.
-
-### 🟢 Camp B: RGS (The Sniper)
-
-In RGS, only the component observing a specific key wakes up. Change the 'cart'? Only the cart icon updates. Total silence for the rest of the application.
-
----
-
-## 🛡️ Defensive Engineering
-
-We don't just manage state; we protect it:
-
-- **Zero Boilerplate**: No actions, no reducers. Just `.set()` and Move on.
-- **Fail-Closed Security**: If a pattern is defined but doesn't explicitly match the action, access is denied. No exceptions.
-- **Ghost Stores**: If a component accesses an uninitialized store, we return a Proxy that warns you but **keeps the UI alive**. No more `ReferenceError: store is not defined`.
-
-## 💡 Case Study: "No-Stress" E-commerce
-
-Imagine a shopping cart.
-
-- **Standard Approach**: The user adds a sock, and the entire product list (2000 items) re-renders because they share a Context.
-- **RGS Approach**: Adds the item with `set('cart', [...])`. Only the tiny cart badge updates. 3ms execution time. Happy client, happy developer.
-
-**Next step:** [Quick Start: 30-Second Setup](02-getting-started.md)

package/docs/chapters/security-architecture.md

@@ -1,50 +0,0 @@
-# Security Architecture & Hardening
-
-## Overview
-Reactive Global State (RGS) is designed with a "Security-First" philosophy. Our architecture ensures that global state is not only reactive but protected against common web vulnerabilities and unauthorized access.
-
-## 1. Data Sanitization (XSS Defense)
-The `sanitizeValue` utility provides a robust baseline defense by stripping malicious content from strings and objects before they enter the store.
-
-- **Scheme Blocking**: Specifically blocks `javascript:`, `vbscript:`, and `data:text/html` schemes.
-- **Tag Removal**: Automatically removes dangerous HTML tags such as `<script>`, `<iframe>`, `<form>`, and `<meta>`.
-- **Entity Removal**: Strips HTML entities (`&#...;`) to prevent obfuscation-based bypasses.
-
-## 2. Advanced Deep Cloning
-To ensure state immutability and prevent unintended side effects, RGS uses an intelligent cloning engine:
-- **Native structuredClone**: Leverages the browser's native API for maximum performance.
-- **Support for Collections**: Extends cloning capabilities to `Map` and `Set` objects.
-- **Circular Reference Protection**: Uses `WeakMap` to handle complex nested structures safely.
-
-## 3. Cryptography (AES-256-GCM)
-The security module uses the Web Crypto API to provide high-performance, authenticated encryption:
-- **AES-GCM**: Provides both confidentiality and integrity verification.
-- **GCM (Galois/Counter Mode)**: Ensures that data has not been tampered with during storage.
-- **Safe Random UUID**: Fallback generation for environments without Web Crypto API.
-
-## 4. RBAC (Role-Based Access Control)
-RGS supports fine-grained access rules:
-- **Fail-Closed Design**: Access is denied by default if any rules are defined.
-- **Regex Caching**: Store instances cache compiled regular expressions for ultra-fast permission checks.
-- **ReDoS Protection**: Regex patterns have a 100ms timeout to prevent denial-of-service attacks.
-- **Storage Key Validation**: All persisted keys are validated against a strict pattern before storage.
-
-## 5. Security Best Practices
-For real-world implementations, refer to the `examples/security-best-practices` directory, which covers:
-- **Encryption Key Management**: Using `generateEncryptionKey()` for secure key generation.
-- **Audit Logging**: Tracking all store modifications for compliance.
-- **GDPR Compliance**: Managing user consent and data export/deletion.
-
-## Summary of 2.9.5 Enhancements
-- Robust regex patterns for `sanitizeValue`.
-- Recursive sanitization for plain objects.
-- `Map` and `Set` support in `deepClone`.
-- **Exposed Metadata**: Store instances now expose read-only `namespace` and `userId`.
-- **Direct Store Access**: Added `getStore()` utility for non-React contexts.
-
-## Summary of 3.7.0 Enhancements
-- **ReDoS Protection**: Regex patterns timeout after 100ms to prevent malicious patterns.
-- **Safe UUID**: Fallback UUID generation for environments without Web Crypto API.
-- **Storage Key Validation**: Keys validated before persistence to prevent injection.
-- **Production Safety**: Global window access only enabled in development mode (`NODE_ENV !== 'production'`).
-- **PBKDF2 Key Derivation**: New `deriveKeyFromPassword()` and `generateSalt()` functions for secure password-based encryption (NIST SC-12 compliant).

package/docs/chapters/the-magnetar-way.md

@@ -1,69 +0,0 @@
-# 🌌 Chapter 3: The Magnetar Way - Peak Simplicity
-
-If you are a fan of "Clean Code" or just hate writing imports, the **Magnetar** method is your new best friend.
-
-It's a single function that creates the store and the hook simultaneously. **Zero config, 100% typed.**
-
-## 🛠️ The "Master" Example
-
-Let's create a User Profile module.
-
-```typescript
-import { gstate } from '@biglogic/rgs';
-
-// 1. Define the state and create everything in ONE shot
-// Pass a string namespace to enable automatic persistence to localStorage
-export const useUser = gstate({
-  name: 'Guest',
-  isLogged: false,
-  preferences: { theme: 'dark', lang: 'en' }
-}, 'user_module'); // Auto-persists to localStorage (excludes sensitive fields)
-
-// Or use an object config for more control:
-export const useUserNoPersist = gstate({
-  name: 'Guest',
-  isLogged: false
-}, { namespace: 'user_module', autoPersist: false }); // No persistence
-
-// 2. Use it anywhere
-function ProfileHeader() {
-  const [name, setName] = useUser('name');
-  // Note: 'setName' is already typed! It only accepts strings.
-
-  return <h1>Hello, {name}!</h1>;
-}
-```
-
-## 💎 Why Magnetar Rocks
-
-1. **Inferred Types**: No need to define `<string>`. TypeScript looks at the initial value you passed to `gstate` and figures it out.
-2. **Auto-Persistence**: When you pass a string namespace, RGS automatically persists to localStorage (excluding sensitive fields like tokens, passwords, secrets).
-3. **Security**: Sensitive fields (containing 'token', 'password', 'secret', 'key') are automatically excluded from persistence.
-
-```typescript
-// You can access the store OUTSIDE components!
-const currentUser = useUser.get('name');
-useUser.set('isLogged', true);
-
-// You can even compute data on the fly (Computed State)
-useUser.compute('fullName', ['firstName', 'lastName'], (s) => `${s.firstName} ${s.lastName}`);
-```
-
-## 🚜 Production Strategy: "The Store Folder"
-
-Don't scatter stores everywhere. Create a `src/stores` folder and put your Magnetar files there:
-
-- `auth.ts`
-- `cart.ts`
-- `settings.ts`
-
-Then import them whenever needed. It’s clean, fast, and professional.
-
-## 🧠 Reflection for the Senior Dev
-
-*"Wait, does Magnetar create a new store every time?"*
-Yes, and that's the point! You can have isolated micro-stores for every domain of your app, while still keeping the ability to make them talk to each other. It’s the evolution of the "Atomic State" concept.
-
----
-
-**Next step:** [Persistence and Safety: Data Never Dies](04-persistence-and-safety.md)