@biglogic/rgs 3.1.0 → 3.5.0

package/examples/README.md

@@ -1,41 +0,0 @@
-# 🌌 RGS Examples & Best Practices
-
-This folder contains functional and reusable examples of **React Globo State (RGS)** implementation.
-
-## 🏁 Overview: FE vs BE Recommendations
-
-| Example | Recommendation | Primary Use Case |
-| :--- | :--- | :--- |
-| **[Basic Counter](./basic-counter)** | **FE Only** | Local component state, UI toggles. |
-| **[Global Theme](./global-theme)** | **FE Only** | Dark mode, Layout settings, Persistence. |
-| **[Persistent Cart](./persistent-cart)** | **FE Preferred** | Shopping carts, Drafts, Offline-first apps. |
-| **[Secure Auth](./secure-auth)** | **FE / BE** | Session management, Tokens, User metadata. |
-| **[Undo/Redo Editor](./undo-redo-editor)** | **FE Only** | Rich text editors, Canvas tools, Form history. |
-| **[RBAC Dashboard](./rbac-dashboard)** | **BE / Admin FE** | Permission-based UI, Secure Admin panels. |
-| **[Async Data Fetch](./async-data-fetch)** | **FE Only** | API integration, Data hydration. |
-| **[Security Practices](./security-best-practices)** | **BE / Core FE** | Encryption, Audit logs, GDPR compliance. |
-| **[Big Data (IndexedDB)](./big-data-indexeddb)** | **FE Specific** | High-volume storage (GBs), Large payloads. |
-| **[Stress Tests](./stress-tests)** | **Validation** | Performance benchmarking & profiling. |
-
----
-
-## 🛡️ Security Guidelines
-
-### 1. Sensitive Data Handling
-**CRITICAL:** Never hardcode actual sensitive data (Credit Cards, Passwords, API Keys) in your JavaScript/TypeScript files.
-- **Frontend:** Collect from secure `<input type="password">` and pass to RGS at runtime.
-- **Backend:** Retrieve from environment variables (`process.env`) or Secret Managers.
-
-### 2. Encryption
-For PII (Personally Identifiable Information), always use the `encryptionKey` option in `StoreConfig`.
-RGS will use the Web Crypto API (or Node Crypto) to perform **AES-256-GCM** encryption before writing to storage.
-
-### 3. XSS Defense
-Enable `validateInput: true` in your store configuration to automatically sanitize strings. This is vital for any user-generated content displayed in the DOM.
-
-### 4. High-Volume Storage (IndexedDB)
-If your application needs to store more than 10MB (the typical localStorage limit), use the **IndexedDB Plugin**. It allows storing Gigabytes of data asynchronously without blocking the main UI thread.
-
-## 🛠️ Testing Environment
-All examples are validated using Jest in a `jsdom` environment.
-Refer to `tests/jest/tests/examples_v.test.ts` for automated verify suites.

package/examples/async-data-fetch/UserLoader.d.ts

@@ -1,12 +0,0 @@
-interface User {
-    id: number;
-    name: string;
-    email: string;
-}
-export declare const fetchUser: (args: {
-    id: string;
-}) => Promise<User>;
-export declare const useUser: import("../../advanced").IStore<Record<string, import("../../core/types").AsyncState<User>>> & {
-    execute: () => Promise<void>;
-};
-export {};

package/examples/async-data-fetch/UserLoader.js

@@ -1,10 +0,0 @@
-import { createAsyncStore } from '../../index';
-export const fetchUser = async (args) => {
-    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${args.id}`);
-    if (!response.ok)
-        throw new Error('User not found');
-    return response.json();
-};
-export const useUser = createAsyncStore(() => fetchUser({ id: '1' }), {
-    key: 'userData'
-});

package/examples/async-data-fetch/UserLoader.ts

@@ -1,30 +0,0 @@
-import { createAsyncStore } from '../../index'
-
-/**
- * Async Data Loader Utility
- * RECOMMENDED FOR: Frontend (FE)
- */
-
-interface User {
-  id: number
-  name: string
-  email: string
-}
-
-export const fetchUser = async (args: { id: string }) => {
-  const response = await fetch(`https://jsonplaceholder.typicode.com/users/${args.id}`)
-  if (!response.ok) throw new Error('User not found')
-  return response.json() as Promise<User>
-}
-
-// Basic Async Store for a specific user (Example)
-export const useUser = createAsyncStore<User>(() => fetchUser({ id: '1' }), {
-  key: 'userData'
-})
-
-/**
- * Usage in component:
- *
- * const [state, actions] = useUser()
- * useEffect(() => { actions.execute({ id: '1' }) }, [])
- */

package/examples/basic-counter/CounterComponent.d.ts

@@ -1,2 +0,0 @@
-import React from 'react';
-export declare const CounterComponent: React.FC;

package/examples/basic-counter/CounterComponent.js

@@ -1,7 +0,0 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { useCounter, increment, decrement } from './CounterStore';
-export const CounterComponent = () => {
-    const [count] = useCounter('count');
-    const [lastUpdated] = useCounter('lastUpdated');
-    return (_jsxs("div", { style: { padding: '20px', border: '1px solid #ccc' }, children: [_jsxs("h2", { children: ["Counter: ", String(count)] }), _jsx("p", { children: _jsxs("small", { children: ["Last updated: ", String(lastUpdated)] }) }), _jsx("button", { onClick: increment, children: "+" }), _jsx("button", { onClick: decrement, children: "-" }), _jsx("button", { onClick: () => useCounter.set('count', 0), children: "Reset" })] }));
-};

package/examples/basic-counter/CounterComponent.tsx

@@ -1,22 +0,0 @@
-import React from 'react'
-import { useCounter, increment, decrement } from './CounterStore'
-
-/**
- * Counter Component
- * Demonstrates the "Magnetar" pattern where the store IS the hook.
- */
-export const CounterComponent: React.FC = () => {
-  // Subscribe to specific keys for fine-grained re-renders
-  const [count] = useCounter('count')
-  const [lastUpdated] = useCounter('lastUpdated')
-
-  return (
-    <div style={{ padding: '20px', border: '1px solid #ccc' }}>
-      <h2>Counter: {String(count)}</h2>
-      <p><small>Last updated: {String(lastUpdated)}</small></p>
-      <button onClick={increment}>+</button>
-      <button onClick={decrement}>-</button>
-      <button onClick={() => useCounter.set('count', 0)}>Reset</button>
-    </div>
-  )
-}

package/examples/basic-counter/CounterStore.d.ts

@@ -1,7 +0,0 @@
-export interface CounterState extends Record<string, unknown> {
-    count: number;
-    lastUpdated: string;
-}
-export declare const useCounter: import("../../advanced").IStore<CounterState> & (<K extends keyof CounterState>(key: K) => readonly [CounterState[K] | undefined, (val: CounterState[K] | ((draft: CounterState[K]) => CounterState[K]), options?: unknown) => boolean]);
-export declare const increment: () => void;
-export declare const decrement: () => void;

package/examples/basic-counter/CounterStore.js

@@ -1,13 +0,0 @@
-import { gstate } from '../../index';
-export const useCounter = gstate({
-    count: 0,
-    lastUpdated: new Date().toISOString()
-});
-export const increment = () => {
-    useCounter.set('count', (d) => d + 1);
-    useCounter.set('lastUpdated', new Date().toISOString());
-};
-export const decrement = () => {
-    useCounter.set('count', (d) => d - 1);
-    useCounter.set('lastUpdated', new Date().toISOString());
-};

package/examples/basic-counter/CounterStore.ts

@@ -1,25 +0,0 @@
-import { gstate } from '../../index'
-
-export interface CounterState extends Record<string, unknown> {
-  count: number
-  lastUpdated: string
-}
-
-/**
- * Basic Counter Store
- * RECOMMENDED FOR: Frontend (FE)
- */
-export const useCounter = gstate<CounterState>({
-  count: 0,
-  lastUpdated: new Date().toISOString()
-})
-
-export const increment = () => {
-  useCounter.set('count', (d) => d + 1)
-  useCounter.set('lastUpdated', new Date().toISOString())
-}
-
-export const decrement = () => {
-  useCounter.set('count', (d) => d - 1)
-  useCounter.set('lastUpdated', new Date().toISOString())
-}

package/examples/big-data-indexeddb/BigDataStore.d.ts

@@ -1,10 +0,0 @@
-export interface BigDataState extends Record<string, unknown> {
-    largeCollection: any[];
-    metaInfo: {
-        totalItems: number;
-        lastSync: number;
-    };
-}
-export declare const useBigData: import("../../advanced").IStore<BigDataState> & (<K extends keyof BigDataState>(key: K) => readonly [BigDataState[K] | undefined, (val: BigDataState[K] | ((draft: BigDataState[K]) => BigDataState[K]), options?: unknown) => boolean]);
-export declare const populateData: (count?: number) => void;
-export declare const clearBigData: () => Promise<void>;

package/examples/big-data-indexeddb/BigDataStore.js

@@ -1,32 +0,0 @@
-import { gstate } from '../../index';
-import { indexedDBPlugin } from '../../plugins/official/indexeddb.plugin';
-const initialState = {
-    largeCollection: [],
-    metaInfo: { totalItems: 0, lastSync: Date.now() }
-};
-export const useBigData = gstate(initialState, {
-    namespace: 'big-data-vault',
-    persist: false
-});
-useBigData._addPlugin(indexedDBPlugin({
-    dbName: 'UserLargeStorage',
-    storeName: 'appStates'
-}));
-export const populateData = (count = 1000) => {
-    const data = [];
-    for (let i = 0; i < count; i++) {
-        data.push({
-            id: `item_${i}`,
-            payload: 'X'.repeat(1024),
-            timestamp: Date.now()
-        });
-    }
-    useBigData.transaction(() => {
-        useBigData.set('largeCollection', data);
-        useBigData.set('metaInfo', { totalItems: count, lastSync: Date.now() });
-    });
-};
-export const clearBigData = async () => {
-    await useBigData.plugins.indexedDB.clear();
-    useBigData.set('largeCollection', []);
-};

package/examples/big-data-indexeddb/BigDataStore.ts

@@ -1,60 +0,0 @@
-import { gstate } from '../../index'
-import { indexedDBPlugin } from '../../plugins/official/indexeddb.plugin'
-
-/**
- * Big Data Store using IndexedDB
- * RECOMMENDED FOR: Frontend (FE)
- *
- * Demonstrates how to handle massive datasets (GBs) that would exceed
- * the standard 5MB-10MB limit of localStorage.
- */
-
-export interface BigDataState extends Record<string, unknown> {
-  largeCollection: any[]
-  metaInfo: { totalItems: number, lastSync: number }
-}
-
-const initialState: BigDataState = {
-  largeCollection: [],
-  metaInfo: { totalItems: 0, lastSync: Date.now() }
-}
-
-// 1. Define the store
-export const useBigData = gstate<BigDataState>(initialState, {
-  namespace: 'big-data-vault',
-  persist: false // Disable standard persistence to use IndexedDB exclusively
-})
-
-// 2. Add the IndexedDB Plugin
-useBigData._addPlugin(indexedDBPlugin({
-  dbName: 'UserLargeStorage',
-  storeName: 'appStates'
-}))
-
-/**
- * Action to simulate adding a large amount of data.
- */
-export const populateData = (count: number = 1000) => {
-  const data: Array<{ id: string, payload: string, timestamp: number }> = []
-  for (let i = 0; i < count; i++) {
-    data.push({
-      id: `item_${i}`,
-      payload: 'X'.repeat(1024), // 1KB per item
-      timestamp: Date.now()
-    })
-  }
-
-  useBigData.transaction(() => {
-    useBigData.set('largeCollection', data)
-    useBigData.set('metaInfo', { totalItems: count, lastSync: Date.now() })
-  })
-}
-
-/**
- * Clear the database
- */
-export const clearBigData = async () => {
-  // Access plugin methods registered on the store
-  await (useBigData as any).plugins.indexedDB.clear()
-  useBigData.set('largeCollection', [])
-}

package/examples/global-theme/ThemeManager.d.ts

@@ -1,7 +0,0 @@
-export interface ThemeState extends Record<string, unknown> {
-    mode: 'light' | 'dark';
-    accent: string;
-}
-export declare const useTheme: import("../../advanced").IStore<ThemeState> & (<K extends keyof ThemeState>(key: K) => readonly [ThemeState[K] | undefined, (val: ThemeState[K] | ((draft: ThemeState[K]) => ThemeState[K]), options?: unknown) => boolean]);
-export declare const initTheme: () => import("../../advanced").IStore<ThemeState> & (<K extends keyof ThemeState>(key: K) => readonly [ThemeState[K] | undefined, (val: ThemeState[K] | ((draft: ThemeState[K]) => ThemeState[K]), options?: unknown) => boolean]);
-export declare const toggleTheme: () => void;

package/examples/global-theme/ThemeManager.js

@@ -1,13 +0,0 @@
-import { gstate } from '../../index';
-export const useTheme = gstate({
-    mode: 'light',
-    accent: '#007bff'
-}, {
-    namespace: 'theme-store',
-    persist: true
-});
-export const initTheme = () => useTheme;
-export const toggleTheme = () => {
-    const current = useTheme.get('mode');
-    useTheme.set('mode', current === 'light' ? 'dark' : 'light');
-};

package/examples/global-theme/ThemeManager.ts

@@ -1,32 +0,0 @@
-import { gstate, getStore } from '../../index'
-
-// Define the shape of our theme state
-export interface ThemeState extends Record<string, unknown> {
-  mode: 'light' | 'dark'
-  accent: string
-}
-
-/**
- * Global Theme Manager
- * RECOMMENDED FOR: Frontend (FE)
- *
- * Demonstrates global state using a dedicated store instance.
- */
-export const useTheme = gstate<ThemeState>({
-  mode: 'light',
-  accent: '#007bff'
-}, {
-  namespace: 'theme-store',
-  persist: true
-})
-
-/**
- * Helper to initialize the theme (useful for SSR or specific init logic)
- */
-export const initTheme = () => useTheme
-
-// Reusable action to toggle theme
-export const toggleTheme = () => {
-  const current = useTheme.get('mode')
-  useTheme.set('mode', current === 'light' ? 'dark' : 'light')
-}

package/examples/hybrid-cloud-sync/HybridStore.d.ts

@@ -1,19 +0,0 @@
-export interface AppState extends Record<string, unknown> {
-    userProfile: {
-        name: string;
-        preferences: any;
-    };
-    projects: Array<{
-        id: string;
-        content: string;
-    }>;
-}
-export declare const useHybridStore: import("../../advanced").IStore<AppState> & (<K extends keyof AppState>(key: K) => readonly [AppState[K] | undefined, (val: AppState[K] | ((draft: AppState[K]) => AppState[K]), options?: unknown) => boolean]);
-export declare const syncNow: () => Promise<void>;
-export declare const getSyncReport: () => {
-    lastSync: string;
-    count: any;
-    errors: any;
-    averageKeysPerSync: number;
-};
-export declare const updateName: (newName: string) => void;

package/examples/hybrid-cloud-sync/HybridStore.js

@@ -1,44 +0,0 @@
-import { gstate } from '../../index';
-import { indexedDBPlugin } from '../../plugins/official/indexeddb.plugin';
-import { cloudSyncPlugin, createMongoAdapter } from '../../plugins/official/cloud-sync.plugin';
-const initialState = {
-    userProfile: { name: 'Dario', preferences: { theme: 'dark' } },
-    projects: []
-};
-export const useHybridStore = gstate(initialState, {
-    namespace: 'hybrid-app-vault',
-    persist: false
-});
-useHybridStore._addPlugin(indexedDBPlugin({
-    dbName: 'LocalCacheDB'
-}));
-useHybridStore._addPlugin(cloudSyncPlugin({
-    adapter: createMongoAdapter('https://api.mongodb.com/v1', 'YOUR_SECRET_API_KEY'),
-    autoSyncInterval: 300000,
-    onSync: (stats) => {
-        console.info(`[CloudSync] Success! Keys: ${stats.totalKeysSynced}, Total Bytes: ${stats.totalBytesSynced}`);
-    }
-}));
-export const syncNow = async () => {
-    const result = await useHybridStore.plugins.cloudSync.sync();
-    if (result.status === 'success') {
-        alert(`Sync completed! ${result.stats.totalKeysSynced} items pushed to cloud.`);
-    }
-    else if (result.status === 'no-change') {
-        console.log('No new changes to sync.');
-    }
-};
-export const getSyncReport = () => {
-    const stats = useHybridStore.plugins.cloudSync.getStats();
-    return {
-        lastSync: stats.lastSyncTimestamp ? new Date(stats.lastSyncTimestamp).toLocaleString() : 'Never',
-        count: stats.syncCount,
-        errors: stats.errors,
-        averageKeysPerSync: stats.syncCount > 0 ? stats.totalKeysSynced / stats.syncCount : 0
-    };
-};
-export const updateName = (newName) => {
-    useHybridStore.set('userProfile', (draft) => {
-        draft.name = newName;
-    });
-};

package/examples/hybrid-cloud-sync/HybridStore.ts

@@ -1,78 +0,0 @@
-import { gstate } from '../../index'
-import { indexedDBPlugin } from '../../plugins/official/indexeddb.plugin'
-import { cloudSyncPlugin, createMongoAdapter } from '../../plugins/official/cloud-sync.plugin'
-
-/**
- * Hybrid Cloud Sync Store
- * RECOMMENDED FOR: Frontend (FE) with Cloud Backup
- *
- * Demonstrates a multi-layer storage strategy:
- * 1. Cache: Memory (fast)
- * 2. Persistent Local: IndexedDB (large capacity)
- * 3. remote: MongoDB Cloud (On-demand/Scheduled backup)
- */
-
-export interface AppState extends Record<string, unknown> {
-  userProfile: { name: string; preferences: any }
-  projects: Array<{ id: string; content: string }>
-}
-
-const initialState: AppState = {
-  userProfile: { name: 'Dario', preferences: { theme: 'dark' } },
-  projects: []
-}
-
-// 1. Initialize the store
-export const useHybridStore = gstate<AppState>(initialState, {
-  namespace: 'hybrid-app-vault',
-  persist: false // We use plugins for persistence
-})
-
-// 2. Add IndexedDB for local persistence (up to GBs)
-useHybridStore._addPlugin(indexedDBPlugin({
-  dbName: 'LocalCacheDB'
-}))
-
-// 3. Add Cloud Sync for remote backup
-// Configured to automatically sync every 5 minutes (300000ms)
-useHybridStore._addPlugin(cloudSyncPlugin({
-  adapter: createMongoAdapter('https://api.mongodb.com/v1', 'YOUR_SECRET_API_KEY'),
-  autoSyncInterval: 300000,
-  onSync: (stats) => {
-    console.info(`[CloudSync] Success! Keys: ${stats.totalKeysSynced}, Total Bytes: ${stats.totalBytesSynced}`)
-  }
-}))
-
-/**
- * Manual Trigger for Cloud Sync
- */
-export const syncNow = async () => {
-  const result = await (useHybridStore as any).plugins.cloudSync.sync()
-  if (result.status === 'success') {
-    alert(`Sync completed! ${result.stats.totalKeysSynced} items pushed to cloud.`)
-  } else if (result.status === 'no-change') {
-    console.log('No new changes to sync.')
-  }
-}
-
-/**
- * Get synchronization diagnostics
- */
-export const getSyncReport = () => {
-  const stats = (useHybridStore as any).plugins.cloudSync.getStats()
-  return {
-    lastSync: stats.lastSyncTimestamp ? new Date(stats.lastSyncTimestamp).toLocaleString() : 'Never',
-    count: stats.syncCount,
-    errors: stats.errors,
-    averageKeysPerSync: stats.syncCount > 0 ? stats.totalKeysSynced / stats.syncCount : 0
-  }
-}
-
-/**
- * Action to update profile
- */
-export const updateName = (newName: string) => {
-  useHybridStore.set('userProfile', (draft) => {
-    draft.name = newName
-  })
-}

package/examples/persistent-cart/CartStore.d.ts

@@ -1,13 +0,0 @@
-export interface CartItem {
-    id: string;
-    name: string;
-    price: number;
-    quantity: number;
-}
-export interface CartState extends Record<string, unknown> {
-    items: CartItem[];
-    coupon: string | null;
-}
-export declare const useCart: import("../../advanced").IStore<CartState> & (<K extends keyof CartState>(key: K) => readonly [CartState[K] | undefined, (val: CartState[K] | ((draft: CartState[K]) => CartState[K]), options?: unknown) => boolean]);
-export declare const addToCart: (product: Omit<CartItem, "quantity">) => void;
-export declare const getCartTotal: () => number;

package/examples/persistent-cart/CartStore.js

@@ -1,23 +0,0 @@
-import { gstate } from '../../index';
-export const useCart = gstate({
-    items: [],
-    coupon: null
-}, {
-    namespace: 'shopping-cart',
-    persist: true
-});
-export const addToCart = (product) => {
-    useCart.set('items', (items) => {
-        const existing = items.find(item => item.id === product.id);
-        if (existing) {
-            existing.quantity++;
-        }
-        else {
-            items.push({ ...product, quantity: 1 });
-        }
-    });
-};
-export const getCartTotal = () => useCart.compute('totalPrice', (get) => {
-    const items = get('items') || [];
-    return items.reduce((total, item) => total + (item.price * item.quantity), 0);
-});

package/examples/persistent-cart/CartStore.ts

@@ -1,41 +0,0 @@
-import { gstate } from '../../index'
-
-export interface CartItem {
-  id: string
-  name: string
-  price: number
-  quantity: number
-}
-
-export interface CartState extends Record<string, unknown> {
-  items: CartItem[]
-  coupon: string | null
-}
-
-/**
- * Persistent Cart Store
- * RECOMMENDED FOR: Frontend (FE)
- */
-export const useCart = gstate<CartState>({
-  items: [],
-  coupon: null
-}, {
-  namespace: 'shopping-cart',
-  persist: true
-})
-
-export const addToCart = (product: Omit<CartItem, 'quantity'>) => {
-  useCart.set('items', (items) => {
-    const existing = items.find(item => item.id === product.id)
-    if (existing) {
-      existing.quantity++
-    } else {
-      items.push({ ...product, quantity: 1 })
-    }
-  })
-}
-
-export const getCartTotal = () => useCart.compute('totalPrice', (get) => {
-  const items = get<CartItem[]>('items') || []
-  return items.reduce((total, item) => total + (item.price * item.quantity), 0)
-})

package/examples/rbac-dashboard/DashboardStore.d.ts

@@ -1,47 +0,0 @@
-export declare const useDashboard: import("../../advanced").IStore<{
-    stats: {
-        visitors: number;
-        revenue: number;
-    };
-    settings: {
-        allowPublicSignup: boolean;
-    };
-    logs: string[];
-}> & (<K extends "stats" | "settings" | "logs">(key: K) => readonly [{
-    stats: {
-        visitors: number;
-        revenue: number;
-    };
-    settings: {
-        allowPublicSignup: boolean;
-    };
-    logs: string[];
-}[K] | undefined, (val: {
-    stats: {
-        visitors: number;
-        revenue: number;
-    };
-    settings: {
-        allowPublicSignup: boolean;
-    };
-    logs: string[];
-}[K] | ((draft: {
-    stats: {
-        visitors: number;
-        revenue: number;
-    };
-    settings: {
-        allowPublicSignup: boolean;
-    };
-    logs: string[];
-}[K]) => {
-    stats: {
-        visitors: number;
-        revenue: number;
-    };
-    settings: {
-        allowPublicSignup: boolean;
-    };
-    logs: string[];
-}[K]), options?: unknown) => boolean]);
-export declare const addLog: (msg: string) => boolean;

package/examples/rbac-dashboard/DashboardStore.js

@@ -1,31 +0,0 @@
-import { gstate } from '../../index';
-export const useDashboard = gstate({
-    stats: { visitors: 100, revenue: 5000 },
-    settings: { allowPublicSignup: true },
-    logs: []
-}, {
-    userId: 'manager-101',
-    accessRules: [
-        {
-            pattern: (key, userId) => key === 'stats' && userId === 'manager-101',
-            permissions: ['read']
-        },
-        {
-            pattern: (key, userId) => key === 'settings' && userId === 'manager-101',
-            permissions: ['read', 'write']
-        },
-        {
-            pattern: (key, userId) => key === 'logs' && userId === 'admin-user',
-            permissions: ['admin']
-        }
-    ]
-});
-export const addLog = (msg) => {
-    const success = useDashboard.set('logs', (draft) => {
-        draft.push(msg);
-    });
-    if (!success) {
-        console.warn(`[Security] Access Denied for user ${useDashboard.userId}: Insufficient permissions for 'logs'`);
-    }
-    return success;
-};