@biglogic/rgs 3.9.6 → 3.9.8

package/docs/markdown/api.md

@@ -0,0 +1,381 @@
+# 📚 API Reference
+
+Complete API reference for RGS (Argis) - Reactive Global State.
+
+---
+
+## Core Functions
+
+### `initState`
+
+Initializes a global store instance.
+
+```typescript
+function initState<S extends Record<string, unknown>>(
+  config?: StoreConfig<S>
+): IStore<S>
+```
+
+**Parameters:**
+- `config` - Optional store configuration
+
+**Returns:** `IStore<S>`
+
+**Example:**
+```typescript
+const store = initState({
+  namespace: 'myApp',
+  version: 1,
+  persistByDefault: true,
+  onError: (error, context) => {
+    console.error(`Error in ${context.operation}:`, error.message)
+  }
+})
+```
+
+---
+
+### `useStore`
+
+React hook for reactive state.
+
+```typescript
+function useStore<T = unknown, S extends Record<string, unknown> = Record<string, unknown>>(
+  key: string,
+  store?: IStore<S>
+): readonly [T | undefined, (val: T | StateUpdater<T>, options?: PersistOptions) => boolean]
+```
+
+**Parameters:**
+- `key` - State key to subscribe to
+- `store` - Optional store instance
+
+**Returns:** Tuple of `[value, setter]`
+
+---
+
+### `createStore`
+
+Creates a new store instance.
+
+```typescript
+function createStore<S extends Record<string, unknown>>(
+  config?: StoreConfig<S>
+): IStore<S>
+```
+
+---
+
+### `getStore`
+
+Retrieves the currently active default store instance. Useful for accessing the store outside of React components or in utility functions.
+
+```typescript
+function getStore(): IStore<Record<string, unknown>> | null
+```
+
+**Returns:** The active `IStore` or `null` if no store was initialized via `initState`.
+
+---
+
+## Store Interface (`IStore`)
+
+### State Operations
+
+#### `set`
+
+Sets a value in the store.
+
+```typescript
+store.set<T>(key: string, value: T | StateUpdater<T>, options?: PersistOptions): boolean
+```
+
+#### `get`
+
+Gets a value from the store.
+
+```typescript
+store.get<T>(key: string): T | null
+```
+
+#### `remove` / `delete`
+
+Removes a value from the store.
+
+```typescript
+store.remove(key: string): boolean
+store.delete(key: string): boolean
+```
+
+#### `deleteAll`
+
+Removes all values from the store.
+
+```typescript
+store.deleteAll(): void
+```
+
+#### `list`
+
+Returns all key-value pairs.
+
+```typescript
+store.list(): Record<string, unknown>
+```
+
+---
+
+### Metadata Properties
+
+#### `namespace`
+
+The unique namespace of the store (read-only).
+
+```typescript
+store.namespace: string
+```
+
+#### `userId`
+
+The current user ID associated with the store for RBAC and audit logs (read-only).
+
+```typescript
+store.userId?: string
+```
+
+---
+
+### Computed Values
+
+#### `compute`
+
+Creates or retrieves a computed (derived) value.
+
+```typescript
+store.compute<T>(key: string, selector: ComputedSelector<T>): T
+```
+
+**Example:**
+```typescript
+const fullName = store.compute('fullName', (get) => {
+  const first = get<string>('firstName')
+  const last = get<string>('lastName')
+  return `${first} ${last}`
+})
+```
+
+> **Note:** RGS supports **nested computed dependencies**. A computed value can reactively depend on other computed values in the same store.
+
+---
+
+### Watching Changes
+
+#### `watch`
+
+Watches for changes on a specific key.
+
+```typescript
+store.watch<T>(key: string, callback: WatcherCallback<T>): () => void
+```
+
+**Returns:** Unsubscribe function
+
+---
+
+### Transactions
+
+#### `transaction`
+
+Groups multiple operations into a single transaction.
+
+```typescript
+store.transaction(fn: () => void): void
+```
+
+---
+
+### Middleware
+
+#### `use`
+
+Adds a middleware function.
+
+```typescript
+store.use(middleware: Middleware): void
+```
+
+---
+
+### Lifecycle
+
+#### `destroy`
+
+Destroys the store and cleans up resources.
+
+```typescript
+store.destroy(): void
+```
+
+---
+
+## Plugin API
+
+### `_addPlugin`
+
+Adds a plugin to the store.
+
+```typescript
+store._addPlugin(plugin: IPlugin): void
+```
+
+### `_removePlugin`
+
+Removes a plugin from the store.
+
+```typescript
+store._removePlugin(name: string): void
+```
+
+### `_registerMethod`
+
+Registers a custom method on the store.
+
+```typescript
+// New signature (recommended)
+store._registerMethod(pluginName: string, methodName: string, fn: (...args) => unknown): void
+```
+
+---
+
+## Plugins Property
+
+Access plugin methods via `store.plugins`:
+
+```typescript
+store.plugins.undoRedo.undo()
+store.plugins.undoRedo.redo()
+store.plugins.counter.increment()
+store.plugins.cloudSync.sync()
+store.plugins.cloudSync.getStats()
+```
+
+---
+
+## Configuration (`StoreConfig`)
+
+```typescript
+interface StoreConfig<S> {
+  /** Unique namespace for this store */
+  namespace?: string
+  /** Schema version */
+  version?: number
+  /** Suppress console warnings */
+  silent?: boolean
+  /** Debounce time for disk flush (default: 150ms) */
+  debounceTime?: number
+  /** Custom storage adapter */
+  storage?: CustomStorage | Storage
+  /** Migration function */
+  migrate?: (oldState: Record<string, unknown>, oldVersion: number) => S
+  /** Error handler */
+  onError?: (error: Error, context: { operation: string; key?: string }) => void
+  /** Max object size in bytes (default: 5MB) */
+  maxObjectSize?: number
+  /** Max total store size in bytes (default: 50MB) */
+  maxTotalSize?: number
+  /** AES-256-GCM encryption key */
+  encryptionKey?: EncryptionKey
+  /** Enable audit logging */
+  auditEnabled?: boolean
+  /** Current user ID for audit */
+  userId?: string
+  /** Enable input validation */
+  validateInput?: boolean
+  /** Access control rules */
+  accessRules?: Array<{
+    pattern: string | ((key: string, userId?: string) => boolean)
+    permissions: Permission[]
+  }>
+  /** Enable Immer (default: true) */
+  immer?: boolean
+}
+```
+
+---
+
+## Persistence Options (`PersistOptions`)
+
+```typescript
+interface PersistOptions {
+  /** Persist to storage (default: localStorage) */
+  persist?: boolean
+  /** Base64 encode the value */
+  encoded?: boolean
+  /** AES-256-GCM encryption */
+  encrypted?: boolean
+  /** Time-to-live in milliseconds */
+  ttl?: number
+}
+```
+
+---
+
+## Types
+
+### `StateUpdater`
+
+```typescript
+type StateUpdater<T> = (draft: T) => void | T
+```
+
+### `ComputedSelector`
+
+```typescript
+type ComputedSelector<T> = (get: <V>(key: string) => V | null) => T
+```
+
+### `WatcherCallback`
+
+```typescript
+type WatcherCallback<T> = (value: T | null) => void
+```
+
+### `Middleware`
+
+```typescript
+type Middleware<T = unknown> = (key: string, value: T, meta: StoreMetadata) => void
+```
+
+---
+
+## Security Types
+
+### `Permission`
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin'
+```
+
+### `AccessRule`
+
+```typescript
+interface AccessRule {
+  pattern: string | ((key: string, userId?: string) => boolean)
+  permissions: Permission[]
+}
+```
+
+---
+
+## Plugin Hooks
+
+| Hook | Description |
+|------|-------------|
+| `onInit` | Called when plugin is first initialized |
+| `onInstall` | Called when plugin is added to store |
+| `onBeforeSet` | Called before a value is set |
+| `onSet` | Called after a value is set |
+| `onGet` | Called when a value is retrieved |
+| `onRemove` | Called when a value is removed |
+| `onDestroy` | Called when store is destroyed |
+| `onTransaction` | Called during a transaction |

package/docs/markdown/case-studies.md

@@ -0,0 +1,69 @@
+# 🛒 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](faq.md)

package/docs/markdown/faq.md

@@ -0,0 +1,53 @@
+# ❓ 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/markdown/getting-started.md

@@ -0,0 +1,68 @@
+# ⚡ 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](the-magnetar-way.md)

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

@@ -0,0 +1,146 @@
+# 🚀 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](security-architecture.md)
+- Explore [Plugin SDK](plugin-sdk.md)
+- Check [Migration Guide](migration-guide.md)