@biglogic/rgs 2.9.3 → 3.0.0

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

@@ -172,6 +172,53 @@ store.recordConsent('user123', 'marketing', true)
 
 ---
 
+## 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
@@ -203,4 +250,4 @@ If you relied on `addAccessRule()` from the global export to affect a `createSto
 
 ---
 
-## Last updated: 2026-02-15
+## Last updated: 2026-02-16

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

@@ -0,0 +1,40 @@
+# 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/package.json

@@ -1,79 +1,84 @@
-{
-  "name": "@biglogic/rgs",
-  "version": "2.9.3",
-  "description": "Argis (RGS) - React Globo State: A react state everywhere made easy",
-  "deprecated": false,
-  "preferGlobal": true,
-  "type": "module",
-  "keywords": [
-    "rgs",
-    "gstate",
-    "state-management",
-    "react",
-    "enterprise",
-    "hooks",
-    "global-state",
-    "immer",
-    "biglogic",
-    "persistence",
-    "react-globo-state",
-    "argis"
-  ],
-  "license": "MIT",
-  "author": "Dario Passariello",
-  "contributors": [
-    {
-      "name": "Dario Passariello",
-      "email": "dariopassariello@gmail.com",
-      "url": "https://dario.passariello.ca/"
-    },
-    {
-      "name": "Valeria Cala Scaglitta",
-      "email": "valeriacalascaglitta@gmail.com"
-    }
-  ],
-  "main": "./index.js",
-  "types": "./index.d.ts",
-  "exports": {
-    ".": "./index.js"
-  },
-  "scripts": {
-    "build": "tsc --emitDeclarationOnly --outDir dist && node ./esbuild.config.mjs",
-    "npm: pack": "npm run build && cd dist && npm pack",
-    "npm: publish": "npm run build && cd dist && npm publish --access=public"
-  },
-  "dependencies": {
-    "immer": "^11.1.4"
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0",
-    "react-dom": ">=16.8.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "10.0.1",
-    "@playwright/test": "1.58.2",
-    "@testing-library/dom": "10.4.1",
-    "@testing-library/jest-dom": "6.9.1",
-    "@testing-library/react": "16.3.2",
-    "@types/jest": "30.0.0",
-    "@types/node": "25.2.3",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.0",
-    "@typescript-eslint/parser": "^8.56.0",
-    "dphelper": "2.6.3",
-    "esbuild": "0.27.3",
-    "esbuild-plugin-copy": "2.1.1",
-    "eslint": "^10.0.0",
-    "eslint-plugin-react": "7.37.5",
-    "eslint-plugin-react-hooks": "7.0.1",
-    "jest": "30.2.0",
-    "jest-environment-jsdom": "30.2.0",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "ts-jest": "29.4.6",
-    "tslib": "^2.8.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "8.56.0"
-  }
-}
+{
+  "name": "@biglogic/rgs",
+  "version": "3.0.0",
+  "description": "Argis (RGS) - React Globo State: A react state everywhere made easy",
+  "type": "module",
+  "keywords": [
+    "rgs",
+    "gstate",
+    "state-management",
+    "react",
+    "enterprise",
+    "hooks",
+    "global-state",
+    "immer",
+    "biglogic",
+    "persistence",
+    "react-globo-state",
+    "argis"
+  ],
+  "homepage": "https://https://github.com/BigLogic-ca/rgs",
+  "bugs": {
+    "url": "https://github.com/BigLogic-ca/rgs/issues"
+  },
+  "license": "MIT",
+  "author": "Dario Passariello <dariopassariello@gmail.com>",
+  "contributors": [
+    {
+      "name": "Dario Passariello",
+      "email": "dariopassariello@gmail.com",
+      "url": "https://dario.passariello.ca/"
+    },
+    {
+      "name": "Valeria Cala Scaglitta",
+      "email": "valeriacalascaglitta@gmail.com"
+    }
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly --outDir dist && node ./esbuild.config.mjs && npm run build:extension",
+    "build:extension": "cd vscode-extension && vsce package -o ../dist",
+    "test": "jest --config tests/jest/jest.config.ts",
+    "npm: pack": "npm run build && cd dist && npm pack",
+    "npm: publish": "npm run build && cd dist && npm publish --access=public"
+  },
+  "dependencies": {
+    "immer": "^11.1.4"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@playwright/test": "1.58.2",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@types/jest": "30.0.0",
+    "@types/node": "25.2.3",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "dphelper": "2.6.3",
+    "esbuild": "0.27.3",
+    "esbuild-plugin-copy": "2.1.1",
+    "eslint": "^10.0.0",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "7.0.1",
+    "globals": "17.3.0",
+    "jest": "30.2.0",
+    "jest-environment-jsdom": "30.2.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "ts-jest": "29.4.6",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "8.56.0"
+  }
+}

package/plugins/index.d.ts

@@ -7,7 +7,9 @@ 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";
 import type { IPlugin } from "../core/types";
-export declare const loggerPlugin: (options?: {
+export declare const loggerPlugin: <S extends Record<string, unknown>>(options?: {
     collapsed?: boolean;
-}) => IPlugin;
+}) => IPlugin<S>;

package/plugins/official/cloud-sync.plugin.d.ts

@@ -0,0 +1,22 @@
+import type { IPlugin } from '../../core/types';
+export interface SyncStats {
+    lastSyncTimestamp: number | null;
+    totalKeysSynced: number;
+    totalBytesSynced: number;
+    syncCount: number;
+    lastDuration: number;
+    errors: number;
+}
+export interface CloudSyncAdapter {
+    name: string;
+    save: (data: Record<string, unknown>) => Promise<boolean>;
+}
+export interface CloudSyncOptions {
+    adapter: CloudSyncAdapter;
+    autoSyncInterval?: number;
+    onSync?: (stats: SyncStats) => void;
+}
+export declare const cloudSyncPlugin: <S extends Record<string, unknown>>(options: CloudSyncOptions) => IPlugin<S>;
+export declare const createMongoAdapter: (apiUrl: string, apiKey: string) => CloudSyncAdapter;
+export declare const createFirestoreAdapter: (db: unknown, docPath: string) => CloudSyncAdapter;
+export declare const createSqlRestAdapter: (endpoint: string, authToken: string) => CloudSyncAdapter;

package/plugins/official/immer.plugin.d.ts

@@ -1,2 +1,2 @@
 import type { IPlugin } from '../../core/types';
-export declare const immerPlugin: () => IPlugin;
+export declare const immerPlugin: <S extends Record<string, unknown>>() => IPlugin<S>;

package/plugins/official/indexeddb.plugin.d.ts

@@ -0,0 +1,7 @@
+import type { IPlugin } from '../../core/types';
+export interface IndexedDBOptions {
+    dbName?: string;
+    storeName?: string;
+    version?: number;
+}
+export declare const indexedDBPlugin: <S extends Record<string, unknown>>(options?: IndexedDBOptions) => IPlugin<S>;

package/plugins/official/undo-redo.plugin.d.ts

@@ -1,4 +1,4 @@
 import type { IPlugin } from '../../core/types';
-export declare const undoRedoPlugin: (options?: {
+export declare const undoRedoPlugin: <S extends Record<string, unknown>>(options?: {
     limit?: number;
-}) => IPlugin;
+}) => IPlugin<S>;