@biglogic/rgs 2.7.0

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

@@ -0,0 +1,206 @@
+# 🔄 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 } from 'argis'
+
+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 'argis'
+
+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 'argis'
+
+// ⚠️ 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.
+
+---
+
+## 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-15

package/dist/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@biglogic/rgs",
+  "version": "2.7.0",
+  "description": "Argis (RGS) - React Globo State: A react state everywhere made easy",
+  "keywords": [
+    "rgs",
+    "gstate",
+    "state-management",
+    "react",
+    "enterprise",
+    "hooks",
+    "global-state",
+    "immer",
+    "biglogic",
+    "persistence",
+    "react-globo-state",
+    "argis"
+  ],
+  "license": "MIT",
+  "author": "Dario Passariello",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./advanced": {
+      "types": "./dist/advanced.d.ts",
+      "default": "./dist/advanced.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly --outDir dist && node ./esbuild.config.mjs",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config ./tests/jest/jest.config.ts",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config ./tests/jest/jest.config.ts --watch",
+    "test:e2e": "playwright test --config ./tests/playwright/playwright.config.ts",
+    "type-check": "tsc --noEmit",
+    "npm:publish": "npm run build && npm publish --access=public",
+    "lint": "eslint . --ext .ts,.tsx --config tests/eslint/eslint.config.mjs"
+  },
+  "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.55.0",
+    "@typescript-eslint/parser": "^8.55.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.55.0"
+  }
+}

package/dist/plugins/index.d.ts

@@ -0,0 +1,13 @@
+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";
+import type { IPlugin } from "../core/types";
+export declare const loggerPlugin: (options?: {
+    collapsed?: boolean;
+}) => IPlugin;

package/dist/plugins/official/analytics.plugin.d.ts

@@ -0,0 +1,9 @@
+import type { IPlugin } from '../../core/types';
+export declare const analyticsPlugin: (options: {
+    provider: (event: {
+        key: string;
+        value: unknown;
+        action: string;
+    }) => void;
+    keys?: string[];
+}) => IPlugin;

package/dist/plugins/official/debug.plugin.d.ts

@@ -0,0 +1,2 @@
+import type { IPlugin } from '../../core/types';
+export declare const debugPlugin: () => IPlugin;

package/dist/plugins/official/devtools.plugin.d.ts

@@ -0,0 +1,4 @@
+import type { IPlugin } from '../../core/types';
+export declare const devToolsPlugin: (options?: {
+    name?: string;
+}) => IPlugin;

package/dist/plugins/official/guard.plugin.d.ts

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

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

@@ -0,0 +1,2 @@
+import type { IPlugin } from '../../core/types';
+export declare const immerPlugin: () => IPlugin;

package/dist/plugins/official/schema.plugin.d.ts

@@ -0,0 +1,2 @@
+import type { IPlugin } from '../../core/types';
+export declare const schemaPlugin: (schemas: Record<string, (val: unknown) => boolean | string>) => IPlugin;

package/dist/plugins/official/snapshot.plugin.d.ts

@@ -0,0 +1,2 @@
+import type { IPlugin } from '../../core/types';
+export declare const snapshotPlugin: () => IPlugin;

package/dist/plugins/official/sync.plugin.d.ts

@@ -0,0 +1,4 @@
+import type { IPlugin } from '../../core/types';
+export declare const syncPlugin: (options?: {
+    channelName?: string;
+}) => IPlugin;

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

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

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@biglogic/rgs",
+  "version": "2.7.0",
+  "description": "Argis (RGS) - React Globo State: A react state everywhere made easy",
+  "keywords": [
+    "rgs",
+    "gstate",
+    "state-management",
+    "react",
+    "enterprise",
+    "hooks",
+    "global-state",
+    "immer",
+    "biglogic",
+    "persistence",
+    "react-globo-state",
+    "argis"
+  ],
+  "license": "MIT",
+  "author": "Dario Passariello",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./advanced": {
+      "types": "./dist/advanced.d.ts",
+      "default": "./dist/advanced.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly --outDir dist && node ./esbuild.config.mjs",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config ./tests/jest/jest.config.ts",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config ./tests/jest/jest.config.ts --watch",
+    "test:e2e": "playwright test --config ./tests/playwright/playwright.config.ts",
+    "type-check": "tsc --noEmit",
+    "npm:publish": "npm run build && npm publish --access=public",
+    "lint": "eslint . --ext .ts,.tsx --config tests/eslint/eslint.config.mjs"
+  },
+  "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.55.0",
+    "@typescript-eslint/parser": "^8.55.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.55.0"
+  }
+}