@biglogic/rgs 3.7.0 → 3.7.2

package/docs/api.md

@@ -1,381 +0,0 @@
-# 📚 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/chapters/01-philosophy.md

@@ -1,54 +0,0 @@
-# 🧠 Chapter 1: The Philosophy - Panzer vs. Bicycle
-
-You are a developer. You have deadlines. You have bugs. But more importantly, you have a reputation to protect.
-
-## 🚜 Choose Your Vehicle
-
-Most state managers focus on being "lightweight" or "easy." **RGS (Argis)** has evolved beyond that. It is a framework designed for high-stakes applications where data leakage is a disaster and production uptime is non-negotiable.
-
-### The Bicycle (Standard Hooks/Context)
-
-If you just need a counter for a simple todo list, use a basic hook or `useState`. You don't need a Panzer to go to the grocery store. It's light, it's fast to set up, but it offers zero protection when the road gets rough.
-
-### The Panzer (RGS)
-
-If you are building an Enterprise platform where:
-
-- **Isolation is King**: User A's data must never collide with User B's state.
-- **Fail-Safe Security**: RBAC (Role-Based Access Control) is built into the state layer.
-- **Resilience**: The app must survive uninitialized states without crashing (`Ghost Stores`).
-
-...then you need a Panzer. **You need RGS.**
-
----
-
-## 🚀 Surgical Performance: Atomic Access
-
-RGS was born from a "crazy" idea: **State should be global by nature, but atomic by access.**
-
-### 🔴 Camp A: Context API (The Re-render Rain)
-
-In React Context, any change in the provider forces a global re-render of the entire tree consuming it. Change a theme brand color? The whole product list re-renders.
-
-### 🟢 Camp B: RGS (The Sniper)
-
-In RGS, only the component observing a specific key wakes up. Change the 'cart'? Only the cart icon updates. Total silence for the rest of the application.
-
----
-
-## 🛡️ Defensive Engineering
-
-We don't just manage state; we protect it:
-
-- **Zero Boilerplate**: No actions, no reducers. Just `.set()` and Move on.
-- **Fail-Closed Security**: If a pattern is defined but doesn't explicitly match the action, access is denied. No exceptions.
-- **Ghost Stores**: If a component accesses an uninitialized store, we return a Proxy that warns you but **keeps the UI alive**. No more `ReferenceError: store is not defined`.
-
-## 💡 Case Study: "No-Stress" E-commerce
-
-Imagine a shopping cart.
-
-- **Standard Approach**: The user adds a sock, and the entire product list (2000 items) re-renders because they share a Context.
-- **RGS Approach**: Adds the item with `set('cart', [...])`. Only the tiny cart badge updates. 3ms execution time. Happy client, happy developer.
-
-**Next step:** [Quick Start: 30-Second Setup](02-getting-started.md)

package/docs/chapters/02-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/03-the-magnetar-way.md

@@ -1,69 +0,0 @@
-# 🌌 Chapter 3: The Magnetar Way - Peak Simplicity
-
-If you are a fan of "Clean Code" or just hate writing imports, the **Magnetar** method is your new best friend.
-
-It's a single function that creates the store and the hook simultaneously. **Zero config, 100% typed.**
-
-## 🛠️ The "Master" Example
-
-Let's create a User Profile module.
-
-```typescript
-import { gstate } from '@biglogic/rgs';
-
-// 1. Define the state and create everything in ONE shot
-// Pass a string namespace to enable automatic persistence to localStorage
-export const useUser = gstate({
-  name: 'Guest',
-  isLogged: false,
-  preferences: { theme: 'dark', lang: 'en' }
-}, 'user_module'); // Auto-persists to localStorage (excludes sensitive fields)
-
-// Or use an object config for more control:
-export const useUserNoPersist = gstate({
-  name: 'Guest',
-  isLogged: false
-}, { namespace: 'user_module', autoPersist: false }); // No persistence
-
-// 2. Use it anywhere
-function ProfileHeader() {
-  const [name, setName] = useUser('name');
-  // Note: 'setName' is already typed! It only accepts strings.
-
-  return <h1>Hello, {name}!</h1>;
-}
-```
-
-## 💎 Why Magnetar Rocks
-
-1. **Inferred Types**: No need to define `<string>`. TypeScript looks at the initial value you passed to `gstate` and figures it out.
-2. **Auto-Persistence**: When you pass a string namespace, RGS automatically persists to localStorage (excluding sensitive fields like tokens, passwords, secrets).
-3. **Security**: Sensitive fields (containing 'token', 'password', 'secret', 'key') are automatically excluded from persistence.
-
-```typescript
-// You can access the store OUTSIDE components!
-const currentUser = useUser.get('name');
-useUser.set('isLogged', true);
-
-// You can even compute data on the fly (Computed State)
-useUser.compute('fullName', ['firstName', 'lastName'], (s) => `${s.firstName} ${s.lastName}`);
-```
-
-## 🚜 Production Strategy: "The Store Folder"
-
-Don't scatter stores everywhere. Create a `src/stores` folder and put your Magnetar files there:
-
-- `auth.ts`
-- `cart.ts`
-- `settings.ts`
-
-Then import them whenever needed. It’s clean, fast, and professional.
-
-## 🧠 Reflection for the Senior Dev
-
-*"Wait, does Magnetar create a new store every time?"*
-Yes, and that's the point! You can have isolated micro-stores for every domain of your app, while still keeping the ability to make them talk to each other. It’s the evolution of the "Atomic State" concept.
-
----
-
-**Next step:** [Persistence and Safety: Data Never Dies](04-persistence-and-safety.md)

package/docs/chapters/04-persistence-and-safety.md

@@ -1,125 +0,0 @@
-# 🏗️ Chapter 4: Persistence and Safety - Built like a Tank
-
-In a real-world application, state that vanishes on page refresh is a developer failure. RGS handles data saving **intelligently**.
-
-## 💾 Persistence: "Set and Forget"
-
-When you initialize RGS or a Magnetar, you can enable persistence. But it's not a simple `localStorage.set`.
-
-```typescript
-initState({
-  persist: true,
-  storage: 'local' // or 'session', or a custom adapter
-});
-```
-
-### Advanced Storage: Beyond 5MB
-
-For applications that need to store massive amounts of data (Gigabytes), standard `localStorage` is not enough. RGS provides official plugins for advanced scenarios:
-
-| Technology | Capacity | Purpose | Plugin |
-| :--- | :--- | :--- | :--- |
-| **LocalStorage** | ~5MB | Basic UI settings, small profiles. | Core (Native) |
-| **IndexedDB** | GBs | Offline-first apps, large datasets, logs. | `indexedDBPlugin` |
-| **Cloud Sync** | Unlimited | Remote backup, cross-device sync. | `cloudSyncPlugin` |
-
----
-
-## ☁️ Hybrid Persistence: The "Cloud-Cloud" Strategy
-
-RGS allows you to combine local power with cloud safety. You can store your active data in **IndexedDB** for speed and capacity, while automatically backing it up to a remote database (MongoDB, Firebase, SQL) using the **Cloud Sync Plugin**.
-
-### Why use Cloud Sync?
-- **Differential Updates**: Safely sends only what was changed since the last sync.
-- **Scheduled or On-Demand**: Sync every 5 minutes automatically, or triggered by a "Save to Cloud" button.
-- **Diagnostics**: Track how much data you are syncing and detect errors before they reach the user.
-
----
-
-### What happens under the hood?
-
-```mermaid
-sequenceDiagram
-    participant C as Component
-    participant RGS as Globo State
-    participant S as LocalStorage
-
-    Note over C,RGS: User clicks a button
-    C->>RGS: set('count', 10)
-    RGS-->>C: Update UI (Instant)
-
-    Note over RGS: Waiting 300ms (Debounce)
-
-    RGS->>S: Write to Disk
-    Note right of S: Data saved successfully
-```
-
-- **Debouncing**: If you update the state 100 times in one second, RGS writes to the disk only once at the end. This saves battery life and browser performance.
-- **Selective Persistence**: Don't want to save everything? You can tell RGS which keys to ignore or which ones to save only temporarily.
-
-## 🛡️ Immutability: The Immer Shield
-
-Have you ever had bugs where state changed "mysteriously" because you mutated an array directly? RGS uses **Immer** at its core (the Stellar Engine).
-
-**Dangerous Code (Standard JS):**
-
-```javascript
-const user = store.get('user');
-user.permissions.push('admin'); // BOOM! You mutated the original without triggering a re-render.
-```
-
-**The RGS Way:**
-
-```javascript
-store.set('user', (draft) => {
-  draft.permissions.push('admin'); // SAFE! RGS creates an immutable copy for you.
-});
-```
-
-## 🕵️ Validation: Schema Plugin
-
-Never trust data coming back from the server or saved in the browser 6 months ago. Use the **schemaPlugin**.
-
-```typescript
-import { schemaPlugin } from '@biglogic/rgs';
-import { z } from 'zod'; // Recommended!
-
-const store = initState();
-store._addPlugin(schemaPlugin({
-  price: (val) => typeof val === 'number' && val > 0,
-  email: (val) => val.includes('@')
-}));
-```
-
-If anyone tries to `set('price', -50)`, RGS will block the operation and warn you. **Clean State = Happy App.**
-
----
-
-## ⚠️ Size Limits: maxObjectSize & maxTotalSize
-
-Protect your app from memory issues with automatic size warnings:
-
-```typescript
-const store = initState({
-  // Warn if single value exceeds 5MB (default: 5MB)
-  maxObjectSize: 5 * 1024 * 1024,
-  // Warn if total store exceeds 50MB (default: 50MB)
-  maxTotalSize: 50 * 1024 * 1024
-});
-
-// Setting a value that exceeds the limit will trigger a warning
-store.set('largeData', bigObject); // Warns if > maxObjectSize
-```
-
----
-
-## 💡 Case Study: The Cart that Never Lost an Item
-
-**Challenge**: User adds products, closes the browser, comes back after two days. The cart must still be there, and synced with their account on other devices.
-**RGS Solution**:
-
-1. Enable `indexedDBPlugin` for robust local storage (handles thousands of items).
-2. Use `cloudSyncPlugin` to bridge the local state with your company's MongoDB Atlas or Firebase.
-3. Result? 5-star UX with full data durability and cross-device sync.
-
-**Next step:** [Ecosystem and Plugins: Extending the Power](05-plugins-and-extensibility.md)