@biglogic/rgs 3.1.0 → 3.5.0

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.

package/plugins/index.js

@@ -1,34 +0,0 @@
-export { immerPlugin } from "./official/immer.plugin";
-export { undoRedoPlugin } from "./official/undo-redo.plugin";
-export { schemaPlugin } from "./official/schema.plugin";
-export { devToolsPlugin } from "./official/devtools.plugin";
-export { snapshotPlugin } from "./official/snapshot.plugin";
-export { guardPlugin } from "./official/guard.plugin";
-export { analyticsPlugin } from "./official/analytics.plugin";
-export { syncPlugin } from "./official/sync.plugin";
-export { debugPlugin } from "./official/debug.plugin";
-export { indexedDBPlugin } from "./official/indexeddb.plugin";
-export { cloudSyncPlugin, createMongoAdapter, createFirestoreAdapter, createSqlRestAdapter } from "./official/cloud-sync.plugin";
-export const loggerPlugin = (options) => ({
-    name: 'gstate-logger',
-    hooks: {
-        onSet: ({ key, value, version }) => {
-            const time = new Date().toLocaleTimeString(), groupLabel = `[gState] SET: ${key} (v${version}) @ ${time}`;
-            if (options?.collapsed)
-                console.groupCollapsed(groupLabel);
-            else
-                console.group(groupLabel);
-            console.info('%c Value:', 'color: #4CAF50; font-weight: bold;', value);
-            console.groupEnd();
-        },
-        onRemove: ({ key }) => {
-            console.warn(`[gState] REMOVED: ${key}`);
-        },
-        onTransaction: ({ key }) => {
-            if (key === 'START')
-                console.group('── TRANSACTION START ──');
-            else
-                console.groupEnd();
-        }
-    }
-});

package/plugins/official/analytics.plugin.js

@@ -1,19 +0,0 @@
-export const analyticsPlugin = (options) => ({
-    name: 'gstate-analytics',
-    hooks: {
-        onSet: ({ key, value }) => {
-            if (!key)
-                return;
-            if (!options.keys || options.keys.includes(key)) {
-                options.provider({ key, value, action: 'SET' });
-            }
-        },
-        onRemove: ({ key }) => {
-            if (!key)
-                return;
-            if (!options.keys || options.keys.includes(key)) {
-                options.provider({ key, value: null, action: 'REMOVE' });
-            }
-        }
-    }
-});

package/plugins/official/cloud-sync.plugin.js

@@ -1,117 +0,0 @@
-export const cloudSyncPlugin = (options) => {
-    const { adapter, autoSyncInterval } = options;
-    const lastSyncedVersions = new Map();
-    const stats = {
-        lastSyncTimestamp: null,
-        totalKeysSynced: 0,
-        totalBytesSynced: 0,
-        syncCount: 0,
-        lastDuration: 0,
-        errors: 0
-    };
-    let timer = null;
-    return {
-        name: 'cloudSync',
-        hooks: {
-            onInstall: ({ store }) => {
-                store._registerMethod('cloudSync', 'sync', async () => {
-                    const startTime = performance.now();
-                    const dirtyData = {};
-                    let bytesCount = 0;
-                    try {
-                        const allData = store.list();
-                        const keys = Object.keys(allData);
-                        for (const key of keys) {
-                            const currentVersion = store._getVersion?.(key) || 0;
-                            const lastVersion = lastSyncedVersions.get(key) || 0;
-                            if (currentVersion > lastVersion) {
-                                const val = allData[key];
-                                dirtyData[key] = val;
-                                bytesCount += JSON.stringify(val).length;
-                                lastSyncedVersions.set(key, currentVersion);
-                            }
-                        }
-                        if (Object.keys(dirtyData).length === 0)
-                            return { status: 'no-change', stats };
-                        const success = await adapter.save(dirtyData);
-                        if (success) {
-                            stats.lastSyncTimestamp = Date.now();
-                            stats.totalKeysSynced += Object.keys(dirtyData).length;
-                            stats.totalBytesSynced += bytesCount;
-                            stats.syncCount++;
-                            stats.lastDuration = performance.now() - startTime;
-                            if (options.onSync)
-                                options.onSync(stats);
-                            return { status: 'success', stats };
-                        }
-                        else {
-                            throw new Error(`Adapter ${adapter.name} failed to save.`);
-                        }
-                    }
-                    catch (err) {
-                        stats.errors++;
-                        console.error(`[gState] Cloud Sync Failed (${adapter.name}):`, err);
-                        return { status: 'error', error: String(err), stats };
-                    }
-                });
-                store._registerMethod('cloudSync', 'getStats', () => stats);
-                if (autoSyncInterval && autoSyncInterval > 0) {
-                    timer = setInterval(() => {
-                        const plugins = store.plugins;
-                        const cs = plugins.cloudSync;
-                        if (cs)
-                            cs.sync();
-                    }, autoSyncInterval);
-                }
-            },
-            onDestroy: () => {
-                if (timer)
-                    clearInterval(timer);
-            }
-        }
-    };
-};
-export const createMongoAdapter = (apiUrl, apiKey) => ({
-    name: 'MongoDB-Atlas',
-    save: async (data) => {
-        const response = await fetch(`${apiUrl}/action/updateOne`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'api-key': apiKey },
-            body: JSON.stringify({
-                dataSource: 'Cluster0',
-                database: 'rgs_cloud',
-                collection: 'user_states',
-                filter: { id: 'global_state' },
-                update: { $set: { data, updatedAt: Date.now() } },
-                upsert: true
-            })
-        });
-        return response.ok;
-    }
-});
-export const createFirestoreAdapter = (db, docPath) => ({
-    name: 'Firebase-Firestore',
-    save: async (data) => {
-        try {
-            console.log('[Mock] Firestore Syncing:', data);
-            return true;
-        }
-        catch (e) {
-            return false;
-        }
-    }
-});
-export const createSqlRestAdapter = (endpoint, authToken) => ({
-    name: 'SQL-REST-API',
-    save: async (data) => {
-        const response = await fetch(endpoint, {
-            method: 'PATCH',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${authToken}`
-            },
-            body: JSON.stringify(data)
-        });
-        return response.ok;
-    }
-});

package/plugins/official/debug.plugin.js

@@ -1,62 +0,0 @@
-export const debugPlugin = () => {
-    if (process.env.NODE_ENV === 'production') {
-        return { name: 'gstate-debug-noop', hooks: {} };
-    }
-    return {
-        name: 'gstate-debug',
-        hooks: {
-            onInstall: ({ store }) => {
-                if (typeof window !== 'undefined') {
-                    window.gstate = {
-                        list: () => {
-                            console.log('[gState] Current state:', store.list());
-                            return store.list();
-                        },
-                        get: (key) => {
-                            const val = store.get(key);
-                            console.log(`[gState] get('${key}'):`, val);
-                            return val;
-                        },
-                        set: (key, value) => {
-                            const result = store.set(key, value);
-                            console.log(`[gState] set('${key}', ${JSON.stringify(value)}):`, result);
-                            return result;
-                        },
-                        watch: (key, callback) => {
-                            const unwatch = store.watch(key, callback);
-                            console.log(`[gState] watching '${key}'`);
-                            return unwatch;
-                        },
-                        info: () => {
-                            const info = {
-                                namespace: store.namespace,
-                                isReady: store.isReady,
-                                keys: Object.keys(store.list()),
-                                size: Object.keys(store.list()).length
-                            };
-                            console.log('[gState] Store Info:', info);
-                            return info;
-                        },
-                        banner: () => {
-                            console.log(`
-╔═══════════════════════════════════════╗
-║         🧲 gState Debug            ║
-║   Type: gstate.list()              ║
-║        gstate.get(key)            ║
-║        gstate.set(key, value)    ║
-║        gstate.info()              ║
-╚═══════════════════════════════════════╝
-              `);
-                        }
-                    };
-                    console.log('[gState] Debug plugin installed. Type gstate.banner() for help.');
-                }
-            },
-            onDestroy: () => {
-                if (typeof window !== 'undefined') {
-                    delete window.gstate;
-                }
-            }
-        }
-    };
-};

package/plugins/official/devtools.plugin.js

@@ -1,28 +0,0 @@
-export const devToolsPlugin = (options) => {
-    const ext = globalThis;
-    const global = ext;
-    const extension = global.__REDUX_DEVTOOLS_EXTENSION__;
-    if (!extension?.connect) {
-        return { name: 'gstate-devtools-noop', hooks: {} };
-    }
-    let _devTools = null;
-    return {
-        name: 'gstate-devtools',
-        hooks: {
-            onInstall: ({ store }) => {
-                _devTools = extension.connect({ name: options?.name || 'Magnetar Store' });
-                _devTools.init(store.list());
-            },
-            onSet: ({ key, store }) => {
-                if (!key || !_devTools)
-                    return;
-                _devTools.send(`SET_${key.toUpperCase()}`, store.list());
-            },
-            onRemove: ({ key, store }) => {
-                if (!key || !_devTools)
-                    return;
-                _devTools.send(`REMOVE_${key.toUpperCase()}`, store.list());
-            }
-        }
-    };
-};

package/plugins/official/guard.plugin.js

@@ -1,15 +0,0 @@
-export const guardPlugin = (guards) => ({
-    name: 'gstate-guard',
-    hooks: {
-        onBeforeSet: ({ key, value, store: _store }) => {
-            if (!key)
-                return;
-            const guard = guards[key];
-            if (guard) {
-                const transformed = guard(value);
-                if (transformed !== value) {
-                }
-            }
-        }
-    }
-});

package/plugins/official/immer.plugin.js

@@ -1,10 +0,0 @@
-export const immerPlugin = () => ({
-    name: 'gstate-immer',
-    hooks: {
-        onInstall: ({ store }) => {
-            store._registerMethod('immer', 'setWithProduce', ((key, updater) => {
-                return store.set(key, updater);
-            }));
-        }
-    }
-});

package/plugins/official/indexeddb.plugin.js

@@ -1,102 +0,0 @@
-export const indexedDBPlugin = (options = {}) => {
-    const dbName = options.dbName || 'rgs-db';
-    const storeName = options.storeName || 'states';
-    const dbVersion = options.version || 1;
-    let db = null;
-    const getDB = () => {
-        return new Promise((resolve, reject) => {
-            if (db)
-                return resolve(db);
-            const request = indexedDB.open(dbName, dbVersion);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => {
-                db = request.result;
-                resolve(db);
-            };
-            request.onupgradeneeded = (event) => {
-                const database = event.target.result;
-                if (!database.objectStoreNames.contains(storeName)) {
-                    database.createObjectStore(storeName);
-                }
-            };
-        });
-    };
-    const save = async (key, value) => {
-        const database = await getDB();
-        return new Promise((resolve, reject) => {
-            const tx = database.transaction(storeName, 'readwrite');
-            const store = tx.objectStore(storeName);
-            const request = store.put(value, key);
-            request.onsuccess = () => resolve();
-            request.onerror = () => reject(request.error);
-        });
-    };
-    const load = async (key) => {
-        const database = await getDB();
-        return new Promise((resolve, reject) => {
-            const tx = database.transaction(storeName, 'readonly');
-            const store = tx.objectStore(storeName);
-            const request = store.get(key);
-            request.onsuccess = () => resolve(request.result);
-            request.onerror = () => reject(request.error);
-        });
-    };
-    const remove = async (key) => {
-        const database = await getDB();
-        return new Promise((resolve, reject) => {
-            const tx = database.transaction(storeName, 'readwrite');
-            const store = tx.objectStore(storeName);
-            const request = store.delete(key);
-            request.onsuccess = () => resolve();
-            request.onerror = () => reject(request.error);
-        });
-    };
-    return {
-        name: 'indexedDB',
-        hooks: {
-            onInstall: ({ store }) => {
-                store._registerMethod('indexedDB', 'clear', async () => {
-                    const database = await getDB();
-                    const tx = database.transaction(storeName, 'readwrite');
-                    tx.objectStore(storeName).clear();
-                });
-            },
-            onInit: async ({ store }) => {
-                const database = await getDB();
-                const tx = database.transaction(storeName, 'readonly');
-                const objectStore = tx.objectStore(storeName);
-                const request = objectStore.getAllKeys();
-                request.onsuccess = async () => {
-                    const keys = request.result;
-                    const prefix = store.namespace + '_';
-                    for (const key of keys) {
-                        if (key.startsWith(prefix)) {
-                            const val = await load(key);
-                            if (val) {
-                                const storeKey = key.substring(prefix.length);
-                                store._setSilently(storeKey, val.d);
-                            }
-                        }
-                    }
-                };
-            },
-            onSet: async ({ key, value, store }) => {
-                if (!key)
-                    return;
-                const prefix = store.namespace + '_';
-                const data = {
-                    d: value,
-                    t: Date.now(),
-                    v: store._getVersion?.(key) || 1
-                };
-                await save(`${prefix}${key}`, data);
-            },
-            onRemove: async ({ key, store }) => {
-                if (!key)
-                    return;
-                const prefix = store.namespace + '_';
-                await remove(`${prefix}${key}`);
-            }
-        }
-    };
-};