@biglogic/rgs 3.8.2 → 3.9.1

package/package.json

@@ -1,23 +1,30 @@
 {
   "name": "@biglogic/rgs",
-  "version": "3.8.2",
-  "license": "MIT",
+  "code": "argis",
+  "version": "3.9.1",
   "description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
-  "type": "module",
-  "main": "./index.js",
+  "main": "./index.cjs",
+  "browser": "./index.cjs",
   "types": "./index.d.ts",
-  "typings": "./types/*",
-  "homepage": "https://github.com/BigLogic-ca/rgs",
-  "engines": {
-    "node": ">=16.0.0"
-  },
+  "typing": "./types/*",
+  "homepage": "https://a51.gitbook.io/rgs",
+  "license": "MIT",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true
   },
-  "files": [
-    "**/*"
+  "copyright": "Dario Passariello",
+  "author": "Dario Passariello",
+  "contributors": [
+    {
+      "name": "Dario Passariello",
+      "email": "dariopassarielloa@gmail.com"
+    },
+    {
+      "name": "Valeria Cala Scaglitta",
+      "email": "valeriacalascaglitta@gmail.com"
+    }
   ],
   "keywords": [
     "rgs",
@@ -33,23 +40,18 @@
     "react-globo-state",
     "argis"
   ],
-  "copyright": "Dario Passariello",
-  "author": "Dario Passariello <dariopassariello@gmail.com>",
-  "contributors": [
-    {
-      "name": "Dario Passariello",
-      "email": "dariopassariello@gmail.com",
-      "url": "https://dario.passariello.ca/"
-    },
+  "funding": [
     {
-      "name": "Valeria Cala Scaglitta",
-      "email": "valeriacalascaglitta@gmail.com"
+      "type": "patreon",
+      "url": "https://www.patreon.com/passariello"
     }
   ],
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/BigLogic-ca/rgs"
+  "engines": {
+    "node": ">=16.0.0"
   },
+  "files": [
+    "**/*"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BigLogic-ca/rgs.git"
@@ -59,31 +61,25 @@
   },
   "support": {
     "name": "Dario Passariello",
-    "url": "https://github.com/passariello/",
+    "url": "https://dario.passariello.ca/",
     "email": "dariopassariello@gmail.com"
   },
-  "scripts": {
-    "dev": "npm run build:watch",
-    "build": "node -e \"const fs=require('fs');if(fs.existsSync('./dist'))fs.rmSync('./dist',{recursive:true});\" && node ./esbuild.config.mjs && npx tsc -p tsconfig.json --emitDeclarationOnly",
-    "build:watch": "node ./esbuild.config.mjs --watch",
-    "build:extension": "cd vscode-extension && vsce package -o ../dist/rgs-extension.vsix",
-    "lint": "cd tests && npm run lint",
-    "tsc": "cd tests && tsc --noEmit",
-    "test": "cd tests && npm test"
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-dom": {
+      "optional": false
+    }
   },
-  "dependencies": {
-    "immer": "11.1.4"
+  "module": "./index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    },
+    "./types/*": "./types/*"
   },
-  "devDependencies": {
-    "@types/node": "^25.3.3",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "esbuild": "0.27.3",
-    "esbuild-node-externals": "1.20.1",
-    "esbuild-plugin-copy": "2.1.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tslib": "^2.8.1",
-    "typescript": "^5.9.3"
-  }
+  "typings": "./index.d.ts"
 }

package/types/rgs.d.ts

@@ -0,0 +1,7 @@
+interface Window {
+  [key: string]: any
+}
+
+// interface globalThis {
+//   [key: string]: any
+// }

package/docs/SUMMARY.md

@@ -1,55 +0,0 @@
-# 🌌 Argis (RGS) - Reactive Global State: The Final Guide
-
-Welcome to the definitive documentation for **Reactive Global State (RGS)**. If you are here, you're likely tired of endless boilerplate, complex configurations, and state management tools that seem to require a PhD in rocket science.
-
-This documentation is written for everyone: from **easy setup** for those who just want things to work, to **advanced implementation** for those who want to master the engine.
-
----
-
-## 🗺️ Summary
-
-- **[The Philosophy: Panzer vs. Bicycle](chapters/philosophy.md)**
-  - Reliability and Security as First-Class Citizens.
-  - The "Ironclad" Core: Simplicity meets Power.
-
-- **[Quick Start: 30-Second Setup](chapters/getting-started.md)**
-  - Deploying the RGS Panzer in your React project.
-
-- **[The Magnetar Way: One-Liner Power](chapters/the-magnetar-way.md)**
-  - Creating stores and hooks simultaneously. Types included.
-
-- **[Persistence and Safety](chapters/persistence-and-safety.md)**
-  - Never lose user data again (without localStorage headaches).
-  - Native immutability with Immer (Stellar Engine).
-
-- **[Ecosystem and Plugins](chapters/plugins-and-extensibility.md)**
-  - DevTools, Cross-Tab Sync, Analytics, and Typed Plugins.
-
-- **[Plugin SDK: Build Your Own Extensions](chapters/plugin-sdk.md)**
-  - Create custom plugins with lifecycle hooks.
-  - Register methods via `store.plugins`.
-  - Full API reference and examples.
-
-- **[Case Studies: Real World Strategies](chapters/case-studies.md)**
-  - **E-commerce**: Cart isolation and atomic updates.
-  - **Dashboards**: Multi-store strategies and complex flows.
-
-- **[Architectural Insights (FAQ)](chapters/07-faq.md)**
-  - Honest answers on security, performance, and Proxies.
-
-- **[Migration Guide](chapters/migration-guide.md)**
-  - Upgrading to latest version (Enterprise Isolation)
-  - Upgrading to previous version (`secure` → `encoded`)
-
-- **[Security Architecture & Hardening](chapters/security-architecture.md)**
-  - Advanced XSS prevention and deep cloning reliability.
-  - AES-256-GCM and RBAC.
-
-- **[Local-First Sync Engine](chapters/local-first-sync.md)**
-  - Offline-by-default with automatic background sync.
-  - Conflict resolution strategies (last-write-wins, merge, etc.).
-  - `useSyncedState` hook for React components.
-
----
-
-> *"Make things simple, but not simpler than necessary."* – RGS Team

package/docs/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-modernist

package/docs/chapters/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/docs/chapters/faq.md

@@ -1,53 +0,0 @@
-# ❓ Chapter 7: FAQ - Architectural Insights
-
-This section provides technical context for the design decisions behind RGS (Argis) - Reactive Global 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/docs/chapters/getting-started.md

@@ -1,68 +0,0 @@
-# ⚡ Chapter 2: Quick Start - From Zero to State in 30 Seconds
-
-Stop wasting time on boilerplate. Here is how you deploy the RGS Panzer in your React project.
-
-## 1. Installation
-
-The engine is lightweight but armored.
-
-```bash
-npm install rgs
-```
-
-## 2. Initialization: The "Big Bang"
-
-In your main entry file (e.g., `main.tsx` or `App.tsx`), wake up the engine once.
-
-```typescript
-import { initState, useStore } from '@biglogic/rgs';
-
-// Initialize with optional settings
-initState({
-  namespace: 'my-awesome-app',
-  persistence: true // Optional: Saves everything to localStorage automatically
-});
-```
-
-## 3. Usage: Instant Reactions
-
-Use the `useStore` hook. No providers, no wrappers. Just raw, atomic power.
-
-```tsx
-import { useStore } from '@biglogic/rgs';
-
-function Counter() {
-  // If 'count' doesn't exist yet, it defaults to undefined. Easy.
-  const [count, setCount] = useStore<number>('count');
-
-  return (
-    <div className="card">
-      <h1>Power Level: {count ?? 0}</h1>
-      <button onClick={() => setCount((prev) => (prev || 0) + 1)}>
-        Boost Power 💥
-      </button>
-    </div>
-  );
-}
-```
-
-## 🧐 What just happened?
-
-- **Reactive Subscription**: `useStore('count')` tells React to watch the 'count' key. Surgical updates only.
-- **Global Scope**: `setCount` updates the value everywhere in the app, instantly.
-- **Resilient Nature**: If you access a key that hasn't been set yet, RGS returns `undefined` gracefully instead of throwing a tantrum.
-
-## 🚨 Pro Tip: Direct Store Access
-
-Need to access state outside of React components? Simple.
-
-```typescript
-import { getStore } from '@biglogic/rgs';
-
-const value = getStore()?.get('count');
-getStore()?.set('count', 9001);
-```
-
----
-
-**Next step:** [The Magnetar Way: One-Liner Power](03-the-magnetar-way.md)

package/docs/chapters/local-first-sync.md

@@ -1,146 +0,0 @@
-# 🚀 Chapter 10: Local-First Sync Engine
-
-RGS now includes a powerful **Local-First Sync Engine** that makes your app work offline by default and automatically synchronize when connectivity is restored.
-
-## Why Local-First?
-
-Traditional apps require an internet connection to work. Local-First apps work immediately with local data and sync in the background when possible.
-
-### Benefits
-
-- **Instant Load** - No waiting for server responses
-- **Works Offline** - App functions without internet
-- **Better UX** - No loading spinners for data
-- **Conflict Resolution** - Smart merge strategies
-
-## Quick Start
-
-```typescript
-import { gstate, useSyncedState } from '@biglogic/rgs'
-
-// Create store with sync enabled
-const store = gstate({
-  todos: [],
-  user: null
-}, {
-  namespace: 'myapp',
-  sync: {
-    endpoint: 'https://api.example.com/sync',
-    // Use a getter function for secure token retrieval
-    authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,  // Sync every 30s
-    syncOnReconnect: true    // Auto-sync when back online
-  }
-})
-
-// Use in React components
-function TodoList() {
-  const [todos, setTodos] = useSyncedState('todos')
-
-  // Add todo - automatically queued for sync
-  const addTodo = (text) => {
-    setTodos([...todos, { id: Date.now(), text }])
-  }
-
-  return <div>{/* ... */}</div>
-}
-```
-
-## Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `endpoint` | `string` | required | Remote sync server URL |
-| `authToken` | `string` or `() => string \| null` | - | Authentication token or getter function for secure retrieval |
-| `strategy` | `string` | `'last-write-wins'` | Conflict resolution |
-| `autoSyncInterval` | `number` | `30000` | Auto-sync interval (ms) |
-| `syncOnReconnect` | `boolean` | `true` | Sync on network restore |
-| `debounceTime` | `number` | `1000` | Batch changes (ms) |
-| `maxRetries` | `number` | `3` | Failed sync retries |
-| `onConflict` | `function` | - | Custom conflict handler |
-| `onSync` | `function` | - | Sync completion callback |
-
-## Conflict Resolution Strategies
-
-### 1. Last-Write-Wins (Default)
-
-```typescript
-sync: { strategy: 'last-write-wins' }
-```
-Latest timestamp wins - simplest strategy.
-
-### 2. Server-Wins
-
-```typescript
-sync: { strategy: 'server-wins' }
-```
-Always prefer remote values - useful for read-heavy apps.
-
-### 3. Client-Wins
-
-```typescript
-sync: { strategy: 'client-wins' }
-```
-Always prefer local values - useful for write-heavy apps.
-
-### 4. Custom Merge
-
-```typescript
-sync: {
-  strategy: 'merge',
-  onConflict: (conflict) => {
-    // Custom logic for merging
-    return {
-      action: 'merge',
-      value: { /* merged result */ }
-    }
-  }
-}
-```
-
-## Hook API
-
-### useSyncedState
-
-```typescript
-const [value, setValue, syncState] = useSyncedState('key')
-
-// syncState contains:
-// - isOnline: boolean
-// - isSyncing: boolean
-// - pendingChanges: number
-// - conflicts: number
-```
-
-### useSyncStatus
-
-```typescript
-const status = useSyncStatus()
-// Global sync status across all stores
-```
-
-## Manual Sync Control
-
-```typescript
-// Force sync
-await store.plugins.sync.flush()
-
-// Get sync state
-const state = store.plugins.sync.getState()
-```
-
-## Integration with Persistence
-
-The Sync Engine works seamlessly with RGS's existing persistence layer:
-
-- **Local Storage** - Data persists locally first
-- **IndexedDB** - For larger datasets
-- **Cloud Sync** - Optional remote backup
-
-Your data survives browser refresh, works offline, and stays synchronized across devices.
-
-## Next Steps
-
-- Learn about [Security Architecture](09-security-architecture.md)
-- Explore [Plugin SDK](05-plugin-sdk.md)
-- Check [Migration Guide](08-migration-guide.md)