@biglogic/rgs 3.7.0 → 3.7.2

package/core/types.d.ts

@@ -1,163 +0,0 @@
-import type { EncryptionKey, AuditEntry, Permission, AccessRule } from './security';
-import type { SyncConfig } from './sync';
-export interface PersistOptions {
-    persist?: boolean;
-    encoded?: boolean;
-    encrypted?: boolean;
-    ttl?: number;
-}
-export interface StoreMetadata {
-    version: number;
-    lastUpdated: number;
-}
-export type StoreSubscriber = () => void;
-export type Middleware<T = unknown> = (key: string, value: T, meta: StoreMetadata) => void;
-export type StateUpdater<T> = (draft: T) => void | T;
-export type ComputedSelector<T> = (get: <V>(key: string) => V | null) => T;
-export type WatcherCallback<T> = (value: T | null) => void;
-export interface PluginMethod<T = unknown> {
-    (...args: unknown[]): T;
-}
-export type PluginMethods<T extends Record<string, PluginMethod>> = T;
-export type PluginHookName = 'onInit' | 'onInstall' | 'onSet' | 'onGet' | 'onRemove' | 'onDestroy' | 'onTransaction' | 'onBeforeSet' | 'onAfterSet';
-export interface PluginContext<S extends Record<string, unknown> = Record<string, unknown>> {
-    store: IStore<S>;
-    key?: string;
-    value?: unknown;
-    version?: number;
-}
-export interface IPlugin<S extends Record<string, unknown> = Record<string, unknown>> {
-    name: string;
-    hooks: {
-        [K in PluginHookName]?: (context: PluginContext<S>) => void | Promise<void>;
-    };
-}
-export declare const createTypedPlugin: <T extends Record<string, PluginMethod>>(name: string, methods: T) => IPlugin & {
-    methods: T;
-};
-export interface IStore<S extends Record<string, unknown> = Record<string, unknown>> {
-    set<K extends keyof S>(key: K, valOrUp: S[K] | StateUpdater<S[K]>, options?: PersistOptions): boolean;
-    get<K extends keyof S>(key: K): S[K] | null;
-    set<T = unknown>(key: string, valOrUp: T | StateUpdater<T>, options?: PersistOptions): boolean;
-    get<T = unknown>(key: string): T | null;
-    compute<T = unknown>(key: string, selector: ComputedSelector<T>): T;
-    watch<K extends keyof S>(key: K, callback: WatcherCallback<S[K]>): () => void;
-    watch<T = unknown>(key: string, callback: WatcherCallback<T>): () => void;
-    remove(key: keyof S | string): boolean;
-    delete(key: keyof S | string): boolean;
-    deleteAll(): boolean;
-    list(): Record<string, unknown>;
-    use(m: Middleware): void;
-    transaction(fn: () => void): void;
-    destroy(): void;
-    _addPlugin(plugin: IPlugin<S>): void;
-    _removePlugin(name: string): void;
-    _subscribe(cb: StoreSubscriber, key?: string): () => void;
-    _getVersion(key: string): number;
-    _setSilently(key: string, value: unknown): void;
-    _registerMethod(pluginName: string, methodName: string, fn: (...args: unknown[]) => unknown): void;
-    getSnapshot(): S;
-    addAccessRule(pattern: string | ((key: string, userId?: string) => boolean), permissions: Permission[]): void;
-    hasPermission(key: string, action: Permission, userId?: string): boolean;
-    recordConsent(userId: string, purpose: string, granted: boolean): import('./security').ConsentRecord;
-    hasConsent(userId: string, purpose: string): boolean;
-    getConsents(userId: string): import('./security').ConsentRecord[];
-    revokeConsent(userId: string, purpose: string): import('./security').ConsentRecord | null;
-    exportUserData(userId: string): {
-        userId: string;
-        exportedAt: number;
-        consents: import('./security').ConsentRecord[];
-    };
-    deleteUserData(userId: string): {
-        success: boolean;
-        deletedConsents: number;
-    };
-    readonly isReady: boolean;
-    readonly namespace: string;
-    readonly userId?: string;
-    whenReady(): Promise<void>;
-    readonly plugins: GStatePlugins;
-}
-export interface GStatePlugins {
-    security: {
-        addAccessRule: (pattern: string | ((key: string, userId?: string) => boolean), permissions: Permission[]) => void;
-        recordConsent: (userId: string, purpose: string, granted: boolean) => import('./security').ConsentRecord;
-        hasConsent: (userId: string, purpose: string) => boolean;
-        getConsents: (userId: string) => import('./security').ConsentRecord[];
-        revokeConsent: (userId: string, purpose: string) => import('./security').ConsentRecord | null;
-        exportUserData: (userId: string) => {
-            userId: string;
-            exportedAt: number;
-            consents: import('./security').ConsentRecord[];
-        };
-        deleteUserData: (userId: string) => {
-            success: boolean;
-            deletedConsents: number;
-        };
-    };
-    undoRedo: {
-        undo: () => boolean;
-        redo: () => boolean;
-        canUndo: () => boolean;
-        canRedo: () => boolean;
-    };
-    immer: {
-        setWithProduce: <T>(key: string, updater: (draft: T) => void) => boolean;
-    };
-    cloudSync: {
-        sync: () => Promise<{
-            status: string;
-            stats: import('../plugins/official/cloud-sync.plugin').SyncStats;
-        }>;
-        getStats: () => import('../plugins/official/cloud-sync.plugin').SyncStats;
-    };
-    sync: {
-        flush: () => Promise<import('../core/sync').SyncResult>;
-        getState: () => import('../core/sync').SyncState;
-        onStateChange: (callback: (state: import('../core/sync').SyncState) => void) => () => void;
-    };
-    logger: Record<string, never>;
-    [key: string]: unknown;
-}
-export interface StoreConfig<S extends Record<string, unknown> = Record<string, unknown>> {
-    namespace?: string;
-    version?: number;
-    silent?: boolean;
-    debounceTime?: number;
-    storage?: CustomStorage | Storage;
-    migrate?: (oldState: Record<string, unknown>, oldVersion: number) => S;
-    persistByDefault?: boolean;
-    persistence?: boolean;
-    persist?: boolean;
-    onError?: (error: Error, context: {
-        operation: string;
-        key?: string;
-    }) => void;
-    maxObjectSize?: number;
-    maxTotalSize?: number;
-    encryptionKey?: EncryptionKey;
-    auditEnabled?: boolean;
-    userId?: string;
-    validateInput?: boolean;
-    encoded?: boolean;
-    accessRules?: Array<{
-        pattern: string | ((key: string, userId?: string) => boolean);
-        permissions: Permission[];
-    }>;
-    immer?: boolean;
-    sync?: SyncConfig;
-}
-export interface CustomStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-    key(index: number): string | null;
-    length: number;
-}
-export interface AsyncState<T> {
-    data: T | null;
-    loading: boolean;
-    error: Error | null;
-    updatedAt: number | null;
-}
-export type { EncryptionKey, AuditEntry, Permission, AccessRule };

package/core/utils.d.ts

@@ -1,2 +0,0 @@
-export declare const deepClone: <T>(obj: T) => T;
-export declare const isEqual: (a: unknown, b: unknown) => boolean;

package/docs/README.md

@@ -1,389 +0,0 @@
-# Argis (RGS) - Reactive Global State
-
-> "The Magnetar" **Atomic Precision. Immutable Safety. Zen Simplicity.**
-> The most powerful state management engine for React. Built for those who demand industrial-grade reliability with a zero-boilerplate experience.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![version](https://img.shields.io/npm/v/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-[![downloads](https://img.shields.io/npm/dm/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-
-![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-![React](https://img.shields.io/badge/React-gray?logo=React)
-![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
-![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
-![Jest](https://img.shields.io/badge/Jest-gray?logo=jest)
-![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
-![ESLint](https://img.shields.io/badge/Eslint-gray?logo=eslint)
-![esbuild](https://img.shields.io/badge/esbuild-gray?logo=esbuild)
-
-![Snik](https://img.shields.io/badge/Snyk-gray?logo=Snyk)
-![Snik](https://img.shields.io/badge/Socket-gray?logo=socket)
-
-<!-- [![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/rgs) -->
-
----
-
-## 🌟 Why Magnetar?
-
-We took the simplicity of **Reactive Global State (RGS)** and fused it with the architecture of a **High-Performance Kernel**. It's the only library that gives you:
-
-- **💎 Absolute Immutability**: Powered by **Immer**. No more manual spreads. State is frozen by default.
-- **🛡️ Industrial-Grade Safety**: Deep Proxy guards that throw `Forbidden Mutation` errors if you try to bypass the kernel.
-- **🔌 Enterprise Ecosystem**: A real plugin architecture with 10+ official modules (Sync, Storage, DevTools, etc.).
-- **⚛️ Power on Demand**: Advanced async and persistence tools isolated in the `advanced` export.
-- **🏗️ Stellar Architecture**: Zero circular dependencies. Modular, clean, and 100% type-safe.
-
----
-
-## gState vs useState
-
-| Feature | RGS gState | React useState |
-|---------|--------|----------|
-| **Global state across components** | ✅ Automatic sharing | ❌ Need Context/props |
-| **Provider wrapper** | ✅ Not needed | ❌ Required |
-| **Persistence (localStorage)** | ✅ Built-in | ❌ Manual |
-| **Data encryption** | ✅ AES-256-GCM | ❌ |
-| **Multiple namespaces/stores** | ✅ | ❌ |
-| **Plugins (Immer, Undo/Redo)** | ✅ | ❌ |
-| **Audit logging** | ✅ | ❌ |
-| **RBAC/GDPR consent** | ✅ | ❌ |
-| **SSR/Hydration** | ✅ Automatic | ❌ Manual |
-| **Computed values** | ✅ | ❌ |
-
-### When to use what?
-
-- **useState**: Local UI, single component, temporary state
-- **gState**:
-  - Shared state across multiple components
-  - Persistent data (preferences, cart, authentication)
-  - Sensitive data (encryption)
-  - Advanced features (undo/redo, snapshots)
-  - Enterprise (audit, RBAC, GDPR)
-
----
-
-## ⚔️ The Arena: RGS vs The World
-
-|Feature|**RGS (Argis)**|Zustand|Redux Toolkit|Recoil|
-|:---|:---|:---|:---|:---|
-| **Philosophy** | **Zen State** | Minimalist | Enterprise Flux | Atomic |
-| **API Surface** | **1 Function** | Simple | Complex | Complex |
-| **Mutations** | **Magic (Immer)** | Manual Spreads | Magic (Immer) | Manual |
-| **Selectors** | ✅ **Type-Safe** | ✅ Functional | ✅ Functional | ⚠️ Selectors |
-| **Security** | 🛡️ **AES-256 + RBAC** | ❌ None | ❌ Ecosystem | ❌ None |
-| **Persistence** | 💾 **First-class** | 🔌 Middleware | 🔌 Middleware | 🔌 Effects |
-| **Async** | ✅ **Atomic** | ✅ Async/Await | ✅ Thunks | ✅ Suspense |
-| **Local-First Sync** | ✅ **Built-in** | ❌ None | ❌ None | ❌ None |
-| **Bundle Size** | **~2kB** | ~1kB | >10kB | >20kB |
-
-> **RGS** is the only library on the market that treats **Security** and **Persistence** as first-class citizens.
-
----
-
-### Installation
-
-```shell
-npm install @biglogic/rgs
-```
-
----
-
-### Examples and guide
-
-**[github.com/BigLogic-ca/rgs](https://github.com/BigLogic-ca/rgs)**
-
----
-
-## 🏗️ Architecture
-
-```mermaid
-graph TB
-    subgraph API
-        A[gstate] --> D[IStore]
-        B[useStore] --> D
-        C[createStore] --> D
-    end
-
-    D --> E[Storage Adapter]
-    D --> F[Immer Proxy]
-    D --> G[Plugins]
-    D --> H[Security]
-    D --> I[Async Store]
-
-    E --> J[local]
-    E --> K[session]
-    E --> L[memory]
-
-    G --> M[UndoRedo]
-    G --> N[Sync]
-    G --> O[Schema]
-    G --> P[Analytics]
-```
-
-### Core Components
-
-| Component | Description |
-|-----------|-------------|
-| **gstate()** | Creates store + hook in one line |
-| **useStore()** | React hook for subscribing to state |
-| **createStore()** | Classic store factory |
-| **IStore** | Core interface with get/set/subscribe |
-| **StorageAdapters** | local, session, memory persistence |
-| **Plugins** | Immer, Undo/Redo, Sync, Schema, etc. |
-| **Security** | Encryption, RBAC, GDPR consent |
-
----
-
-## Requirements
-
-- **React 16.8+** (for hooks support)
-- **React DOM**
-
-## ⚡ Zero-Boilerplate Quickstart
-
-### Path A: The Zen Way (Modular)
-
-Best for modern applications. Clean imports, zero global pollution, **Type-Safe**.
-
-```tsx
-import { gstate } from '@biglogic/rgs'
-
-// 1. Create a typed store hook
-const useCounter = gstate({ count: 0, user: { name: 'Alice' } })
-
-// 2. Use with Type-Safe Selectors (Preferred)
-const count = useCounter(state => state.count)
-const userName = useCounter(state => state.user.name)
-
-// OR use string keys (Legacy)
-const [count, setCount] = useCounter('count')
-```
-
-### Path B: The Classic Way (Global)
-
-Best for shared state across the entire application.
-
-```tsx
-// 1. Initialize once
-import { initState, useStore } from '@biglogic/rgs'
-initState({ namespace: 'app' })
-
-// 2. Use anywhere
-const [user, setUser] = useStore('user')
-```
-
----
-
-## 🛡️ Security Architecture
-
-RGS includes enterprise-grade security features to protect your application and user data:
-
-### ReDoS Protection
-All regex patterns used in RBAC permission matching include timeout protection (100ms) to prevent Regex Denial of Service attacks.
-
-### Safe UUID Generation
-Falls back to cryptographically secure random UUID generation when native `crypto.randomUUID()` is unavailable.
-
-### Input Validation
-- **Storage Key Validation**: Keys are validated against `/^[a-zA-Z0-9_.-]+$/` to prevent injection attacks
-- **Value Sanitization**: All persisted values are sanitized to prevent XSS attacks
-
-### Encryption
-- **AES-256-GCM**: Industry-standard encryption for sensitive data
-- **Encoded Mode**: Use `{ encoded: true }` option for base64-encoded storage (note: renamed from `secure` for clarity)
-
-### GDPR Compliance
-- Consent management system
-- Data export (`exportData()`)
-- Data deletion (`deleteData()`)
-
-### Development vs Production
-Global `gstate` exposure to window is only enabled in development mode (`NODE_ENV !== 'production'`).
-
----
-
-## 📚 Quick Examples
-
-```tsx
-const store = gstate({ theme: 'dark' }, "my-app")
-```
-
-### Encryption
-
-```tsx
-const secureStore = gstate({ token: 'xxx' }, { encoded: true })
-```
-
-### Undo/Redo
-
-```tsx
-const store = gstate({ count: 0 })
-store._addPlugin(undoRedoPlugin({ limit: 50 }))
-
-store.undo()
-store.redo()
-```
-
-### Cross-Tab Sync
-
-```tsx
-const store = gstate({ theme: 'light' })
-store._addPlugin(syncPlugin({ channelName: 'my-app' }))
-```
-
-```tsx
-const store = gstate({ firstName: 'John', lastName: 'Doe' })
-store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)
-
-const [fullName] = store('fullName') // "John Doe"
-```
-
-### Error Handling with onError
-
-Handle errors gracefully with the `onError` callback - perfect for production apps:
-
-```tsx
-const store = gstate({ data: null }, {
-  onError: (error, context) => {
-    console.error(`Error in ${context.operation}:`, error.message)
-    // Send to error tracking service (Sentry, etc.)
-  }
-})
-```
-
-### Size Limits (maxObjectSize & maxTotalSize)
-
-Protect your app from memory issues with automatic size warnings:
-
-```tsx
-const store = gstate({ data: {} }, {
-  // Warn if single value exceeds 5MB (Default is 0/Disabled for performance)
-  maxObjectSize: 5 * 1024 * 1024,
-  // Warn if total store exceeds 50MB (Default is 0/Disabled)
-  maxTotalSize: 50 * 1024 * 1024
-})
-```
-
-### Local-First Sync (Offline-by-Default)
-
-RGS now includes a powerful Local-First Sync Engine that makes your app work offline by default:
-
-```tsx
-import { gstate, useSyncedState } from '@biglogic/rgs'
-
-// Create store with built-in sync
-const store = gstate({
-  todos: [],
-  user: null
-}, {
-  namespace: 'myapp',
-  sync: {
-    endpoint: 'https://api.example.com/sync',
-    // Use a getter function to avoid exposing token in memory
-    authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,  // Sync every 30s
-    syncOnReconnect: true,   // Auto-sync when back online
-    strategy: 'last-write-wins'  // Conflict resolution
-  }
-})
-
-// Use in React - automatically synced!
-function TodoList() {
-  const [todos, setTodos] = useSyncedState('todos')
-
-  // Works offline automatically
-  const addTodo = (text) => {
-    setTodos([...todos, { id: Date.now(), text }])
-  }
-
-  return <div>{/* ... */}</div>
-}
-```
-
----
-
-## Multiple Stores
-
-You can create multiple independent stores using namespaces:
-
-```tsx
-// Option 1: gstate with namespace
-const userStore = gstate({ name: 'John' }, { namespace: 'users' })
-const appStore = gstate({ theme: 'dark' }, { namespace: 'app' })
-
-// In components - same key, different stores
-const [name] = userStore('name')     // 'John'
-const [theme] = appStore('theme')    // 'dark'
-
-// Option 2: initState + useStore (global default store)
-initState({ namespace: 'global' })
-const [value, setValue] = useStore('key')
-```
-
-**Tip**: Keys are unique per-namespace, so you can use the same key name in different stores.
-
-## 🚀 Advanced Superpowers
-
-### 🔌 Official Plugin Ecosystem
-
-Extend the core functionality dynamically with specialized modules.
-
-1. **ImmerPlugin**: Adds `setWithProduce` for functional updates.
-2. **UndoRedoPlugin**: Multi-level history management.
-3. **PersistencePlugin**: Advanced storage with custom serialization.
-4. **SyncPlugin**: Cross-tab state synchronization via BroadcastChannel.
-5. **SchemaPlugin**: Runtime validation (perfect for Zod).
-6. **DevToolsPlugin**: Redux DevTools integration.
-7. **TTLPlugin**: Time-to-live management.
-8. **AnalyticsPlugin**: Tracking bridge for metrics.
-9. **SnapshotPlugin**: Manual state checkpointing.
-10. **GuardPlugin**: Data transformation layer.
-11. **Local-First Sync**: Built-in offline-first with auto-sync (NEW!)
-
-```typescript
-import { createStore, PersistencePlugin, undoRedoPlugin } from '@biglogic/rgs'
-
-const store = createStore()
-store._addPlugin(PersistencePlugin({ storage: 'localStorage' }))
-store._addPlugin(undoRedoPlugin({ limit: 50 }))
-
-// Undo like a pro
-store.undo()
-```
-
-### 🔬 Power Tools (Import from `rgs/advanced`)
-
-Need the heavy artillery? We've got you covered.
-
-- `createAsyncStore(fetcher)`: Atomic async state management.
-- `StorageAdapters`: High-level interfaces for any storage engine.
-- `Middleware / IPlugin`: Build your own extensions.
-
----
-
-## 🛡️ Quality & Testing
-
-RGS is built with an obsession for reliability. Our test suite covers multiple layers to ensure zero-regressions:
-
-- **Unit Tests (Jest)**: 100+ tests covering core logic, stores, and hooks.
-- **E2E Tests (Playwright)**: Real-world browser testing for cross-tab synchronization and Web Crypto API.
-- **Concurrency Testing**: Verification of race conditions in multi-tab environments.
-
-```bash
-# Run unit tests
-npm run test
-
-# Run E2E tests
-npm run test:e2e
-```
-
----
-
-## 📄 License
-
-MIT © [Dario Passariello](https://github.com/dpassariello)
-
----
-
-**Designed for those who build the future.**
-Made with ❤️ and a lot of caffe' espresso!

package/docs/SUMMARY.md

@@ -1,64 +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/01-philosophy.md)**
-  - Reliability and Security as First-Class Citizens.
-  - The "Ironclad" Core: Simplicity meets Power.
-
-- **[Quick Start: 30-Second Setup](chapters/02-getting-started.md)**
-  - Deploying the RGS Panzer in your React project.
-
-- **[The Magnetar Way: One-Liner Power](chapters/03-the-magnetar-way.md)**
-  - Creating stores and hooks simultaneously. Types included.
-
-- **[Persistence and Safety](chapters/04-persistence-and-safety.md)**
-  - Never lose user data again (without localStorage headaches).
-  - Native immutability with Immer (Stellar Engine).
-
-- **[Ecosystem and Plugins](chapters/05-plugins-and-extensibility.md)**
-  - DevTools, Cross-Tab Sync, Analytics, and Typed Plugins.
-
-- **[Plugin SDK: Build Your Own Extensions](chapters/05-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/06-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/08-migration-guide.md)**
-  - Upgrading to latest version (Enterprise Isolation)
-  - Upgrading to previous version (`secure` → `encoded`)
-
-- **[Security Architecture & Hardening](chapters/09-security-architecture.md)**
-  - Advanced XSS prevention and deep cloning reliability.
-  - AES-256-GCM and RBAC.
-
-- **[Local-First Sync Engine](chapters/10-local-first-sync.md)**
-  - Offline-by-default with automatic background sync.
-  - Conflict resolution strategies (last-write-wins, merge, etc.).
-  - `useSyncedState` hook for React components.
-
----
-
-## Reference
-
-- **[API Reference](api.md)**
-  - Complete API documentation
-  - Type definitions
-  - Plugin hooks
-
----
-
-> *"Make things simple, but not simpler than necessary."* – RGS Team

package/docs/_config.yml

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