@biglogic/rgs 3.0.1 → 3.2.0

package/markdown/chapters/06-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/markdown/chapters/07-faq.md

@@ -1,53 +0,0 @@
-# ❓ 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.

package/markdown/chapters/08-migration-guide.md

@@ -1,253 +0,0 @@
-# 🔄 Migration Guide
-
-## Upgrading from Previous Versions
-
-### Security: `secure` → `encoded`
-
-**IMPORTANT:** The `secure` option has been deprecated in favor of `encoded` to clarify that it only applies **base64 encoding**, not encryption.
-
-#### ❌ Old Code (Deprecated)
-
-```typescript
-store.set('apiKey', 'secret123', {
-  persist: true,
-  secure: true  // ⚠️ DEPRECATED: This is NOT encryption!
-})
-```
-
-#### ✅ New Code (Recommended)
-
-```typescript
-store.set('apiKey', 'secret123', {
-  persist: true,
-  encoded: true  // ✅ Clear: This is base64 encoding
-})
-```
-
-#### Backward Compatibility
-
-Your old code will **still work**, but you'll see a deprecation warning in TypeScript:
-
-```typescript
-/** @deprecated Use 'encoded' instead. 'secure' only applies base64 encoding, not encryption. */
-secure?: boolean
-```
-
-#### Why This Change?
-
-Base64 encoding is **NOT encryption**. It's trivial to decode:
-
-```javascript
-// Anyone can decode base64
-const encoded = btoa(JSON.stringify({ secret: 'password123' }))
-const decoded = JSON.parse(atob(encoded)) // { secret: 'password123' }
-```
-
-**For real security**, use proper encryption libraries like:
-
-- `crypto-js` (AES encryption)
-- `tweetnacl` (NaCl encryption)
-- Web Crypto API (`crypto.subtle`)
-
----
-
-### Error Handling: `onError` Callback
-
-**NEW:** You can now catch and handle errors from plugins, hydration, and other operations.
-
-#### Example: Custom Error Logging
-
-```typescript
-import { initState, useStore } from '@biglogic/rgs'
-
-const store = initState({
-  namespace: 'myapp',
-  onError: (error, context) => {
-    // Send to your error tracking service
-    console.error(`[gState Error] ${context.operation}:`, error)
-
-    if (context.operation === 'hydration') {
-      // Handle corrupted localStorage
-      localStorage.clear()
-      alert('Storage corrupted, resetting...')
-    }
-
-    if (context.operation.startsWith('plugin:')) {
-      // Handle plugin crashes
-      Sentry.captureException(error, { tags: { plugin: context.operation } })
-    }
-  }
-})
-```
-
-#### Error Context
-
-```typescript
-interface ErrorContext {
-  operation: string  // 'hydration', 'plugin:name:hook', 'set'
-  key?: string       // State key (if applicable)
-}
-```
-
----
-
-### Performance: `maxObjectSize` Warning
-
-**NEW:** Get warned when storing objects larger than a configurable limit (default: 5MB).
-
-#### Example: Custom Size Limit
-
-```typescript
-import { createStore } from '@biglogic/rgs'
-
-const store = createStore({
-  maxObjectSize: 10 * 1024 * 1024, // 10MB limit
-  onError: (error, context) => {
-    if (context.operation === 'set') {
-      console.warn(`Large object detected in key: ${context.key}`)
-    }
-  }
-})
-
-// This will trigger a warning if > 10MB
-store.set('bigData', hugeArray)
-```
-
-#### Disable Size Checking
-
-```typescript
-const store = createStore({
-  maxObjectSize: 0  // Disable size warnings
-})
-```
-
----
-
-## Upgrading to Latest Version (The Enterprise Update)
-
-**IMPORTANT:** This release introduces a fundamental shift towards **Multi-Store Isolation**. Security rules and GDPR consents are now instance-bound rather than global.
-
-### 1. Security: Global → Instance-Specific
-
-In previous versions, security rules were shared globally. Now, each store instance maintains its own rules for better isolation in micro-frontend environments.
-
-#### ❌ Deprecated Global Methods
-
-```typescript
-import { addAccessRule, recordConsent } from '@biglogic/rgs'
-
-// ⚠️ DEPRECATED: These affect the 'default' store only and are less isolated
-addAccessRule('user_*', ['read', 'write'])
-```
-
-#### ✅ Recommended Instance Methods
-
-```typescript
-const store = createStore({ namespace: 'my-isolated-app' })
-
-// ✅ Use the instance methods
-store.addAccessRule('user_*', ['read', 'write'])
-store.recordConsent('user123', 'marketing', true)
-```
-
-### 2. Operational Resilience: Ghost Stores
-
-**NEW:** If you access a store that hasn't finished its initialization (e.g., during slow hydration), RGS now returns a **Ghost Store Proxy**.
-
-- **Behavior:** It prevents application crashes by providing a safe fallback.
-- **Developer Warning:** It logs a detailed warning in the console so you can fix the initialization sequence.
-
-### 3. Performance: Regex Caching
-
-**NEW:** Permission checks now use an internal **Regex Cache** per instance.
-
-- **Why?** Avoids the overhead of re-compiling regex strings on every `.get()` or `.set()` call.
-- **Impact:** Significant performance boost for applications with high-frequency state updates and complex RBAC rules.
-
-### 4. Advanced Plugin Typing
-
-**NEW:** Introducing `GStatePlugins` for Module Augmentation.
-
-- You can now define types for your custom plugins to get full IDE autocomplete.
-
----
-
-## v2.9.5: The Architecture & Safety Update (2026-02-16)
-
-This release focuses on improving developer ergonomics, security visibility, and complex dependency handling.
-
-### 1. Nested Computed Dependencies
-**NEW:** Computed values can now re-trigger based on other computed values.
-
-```typescript
-store.compute('tax', (get) => (get<number>('subtotal') || 0) * 0.2)
-store.compute('total', (get) => (get<number>('subtotal') || 0) + (get<number>('tax') || 0))
-```
-
-### 2. Direct Store Access: `getStore()`
-**NEW:** A top-level utility to retrieve the default store without React hooks.
-
-```typescript
-import { getStore } from '@biglogic/rgs'
-
-export const toggleTheme = () => {
-  const store = getStore()
-  if (store) store.set('mode', 'dark')
-}
-```
-
-### 3. Exposed Metadata: `namespace` and `userId`
-**NEW:** Store instances now expose their identifying properties as read-only getters.
-
-```typescript
-const store = createStore({ namespace: 'auth-vault', userId: 'user-001' })
-console.log(store.namespace) // 'auth-vault'
-console.log(store.userId)    // 'user-001'
-```
-
-### 4. High-Volume & Hybrid Sync (Plugins)
-**NEW:** Support for GB-scale storage and Remote Cloud Backups.
-
-- **IndexedDB Plugin**: Replaces localStorage for massive browser datasets.
-- **Cloud Sync Plugin**: Differential synchronization to MongoDB, Firebase, or any SQL backend.
-
-```typescript
-// Example: Manual Cloud Sync
-const result = await store.plugins.cloudSync.sync()
-console.log('Stats:', store.plugins.cloudSync.getStats())
-```
-
----
-
-## Breaking Changes
-
-### 🔒 Security Isolation
-
-If you relied on `addAccessRule()` from the global export to affect a `createStore()` instance, you must now call `store.addAccessRule()` on that specific instance.
-
----
-
-## Recommended Actions
-
-### 1. Migrate Security Calls to Store Instances
-
-**Priority:** High (if using multiple stores)
-
-**Effort:** Low
-
-### 2. Implement `GStatePlugins` for Custom Plugins
-
-**Priority:** Medium (Developer Experience)
-
-**Effort:** Low
-
----
-
-## Need Help?
-
-- **Issues:** [GitHub Issues](https://github.com/dpassariello/rgs/issues)
-- **Docs:** [Galaxy Documentation](../SUMMARY.md)
-
----
-
-## Last updated: 2026-02-16

package/markdown/chapters/09-security-architecture.md

@@ -1,40 +0,0 @@
-# Security Architecture & Hardening
-
-## Overview
-React Globo 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.
-
-## 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.
-
-## 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.