@biglogic/rgs 2.9.2 → 2.9.5

package/examples/persistent-cart/CartStore.ts

@@ -0,0 +1,48 @@
+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.transaction(() => {
+    const items = useCart.get('items') || []
+    const existingIndex = items.findIndex(item => item.id === product.id)
+
+    if (existingIndex > -1) {
+      const newItems = [...items]
+      const item = newItems[existingIndex]
+      if (item) {
+        newItems[existingIndex] = { ...item, quantity: item.quantity + 1 }
+        useCart.set('items', newItems)
+      }
+    } else {
+      useCart.set('items', [...items, { ...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

@@ -0,0 +1,47 @@
+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.ts

@@ -0,0 +1,46 @@
+import { gstate } from '../../index'
+
+/**
+ * RBAC Dashboard Store
+ * RECOMMENDED FOR: Backend (BE) / Admin Frontend (FE)
+ *
+ * Demonstrates Role-Based Access Control.
+ */
+export const useDashboard = gstate({
+  stats: { visitors: 100, revenue: 5000 },
+  settings: { allowPublicSignup: true },
+  logs: [] as string[]
+}, {
+  userId: 'manager-101',
+  accessRules: [
+    {
+      // Allow 'manager-101' read access to stats
+      pattern: (key, userId) => key === 'stats' && userId === 'manager-101',
+      permissions: ['read']
+    },
+    {
+      // Allow 'manager-101' full access to settings
+      pattern: (key, userId) => key === 'settings' && userId === 'manager-101',
+      permissions: ['read', 'write']
+    },
+    {
+      // ONLY 'admin-user' can access logs
+      pattern: (key, userId) => key === 'logs' && userId === 'admin-user',
+      permissions: ['admin']
+    }
+  ]
+})
+
+/**
+ * Attempt to add a log entry.
+ * Will fail if the current store userId is not 'admin-user'.
+ */
+export const addLog = (msg: string) => {
+  const success = useDashboard.set('logs', (draft: string[]) => {
+    draft.push(msg)
+  })
+  if (!success) {
+    console.warn(`[Security] Access Denied for user ${useDashboard.userId}: Insufficient permissions for 'logs'`)
+  }
+  return success
+}

package/examples/secure-auth/AuthStore.d.ts

@@ -0,0 +1,14 @@
+export interface AuthState extends Record<string, unknown> {
+    user: {
+        id: string;
+        email: string;
+    } | null;
+    token: string | null;
+    isAuthenticated: boolean;
+}
+export declare const useAuth: import("../../advanced").IStore<AuthState> & (<K extends keyof AuthState>(key: K) => readonly [AuthState[K] | undefined, (val: AuthState[K] | ((draft: AuthState[K]) => AuthState[K]), options?: unknown) => boolean]);
+export declare const login: (user: {
+    id: string;
+    email: string;
+}, token: string) => void;
+export declare const logout: () => void;

package/examples/secure-auth/AuthStore.ts

@@ -0,0 +1,36 @@
+import { gstate } from '../../index'
+
+export interface AuthState extends Record<string, unknown> {
+  user: { id: string, email: string } | null
+  token: string | null
+  isAuthenticated: boolean
+}
+
+/**
+ * Secure Authentication Store
+ * RECOMMENDED FOR: Frontend (FE) / Backend (BE)
+ *
+ * Demonstrates the 'encoded' option for basic obfuscation in localStorage.
+ * Notice: For industrial-grade security, use encryptionKey in config.
+ */
+export const useAuth = gstate<AuthState>({
+  user: null,
+  token: null,
+  isAuthenticated: false
+}, {
+  namespace: 'secure-auth',
+  encoded: true, // Base64 encodes data in localStorage
+  persist: true
+})
+
+export const login = (user: { id: string, email: string }, token: string) => {
+  useAuth.transaction(() => {
+    useAuth.set('user', user)
+    useAuth.set('token', token)
+    useAuth.set('isAuthenticated', true)
+  })
+}
+
+export const logout = () => {
+  useAuth.deleteAll() // Clears all state and storage for this namespace
+}

package/examples/security-best-practices/SecurityStore.d.ts

@@ -0,0 +1,21 @@
+export interface VaultState extends Record<string, unknown> {
+    encryptedData: string | null;
+}
+export declare const initSecureVault: () => Promise<import("../../advanced").IStore<VaultState> & (<K extends keyof VaultState>(key: K) => readonly [VaultState[K] | undefined, (val: VaultState[K] | ((draft: VaultState[K]) => VaultState[K]), options?: unknown) => boolean])>;
+export declare const useProfileStore: import("../../advanced").IStore<{
+    bio: string;
+    displayName: string;
+}> & (<K extends "bio" | "displayName">(key: K) => readonly [{
+    bio: string;
+    displayName: string;
+}[K] | undefined, (val: {
+    bio: string;
+    displayName: string;
+}[K] | ((draft: {
+    bio: string;
+    displayName: string;
+}[K]) => {
+    bio: string;
+    displayName: string;
+}[K]), options?: unknown) => boolean]);
+export declare const purgeUserData: (store: any, userId: string) => void;

package/examples/security-best-practices/SecurityStore.ts

@@ -0,0 +1,73 @@
+import { gstate, setAuditLogger, generateEncryptionKey } from '../../index'
+
+/**
+ * SECURITY BEST PRACTICES EXAMPLE
+ *
+ * RECOMMENDED FOR: Frontend (FE) and Backend (BE/Node)
+ *
+ * DESIGN PRINCIPLE:
+ * - NEVER hardcode sensitive data (PII, Credit Cards, Keys) in source code.
+ * - Use environment variables or secure user input at runtime.
+ */
+
+export interface VaultState extends Record<string, unknown> {
+  encryptedData: string | null
+}
+
+/**
+ * 1. AES-256-GCM Encryption (Enterprise Grade)
+ * This store demonstrates how to handle sensitive information securely.
+ */
+export const initSecureVault = async () => {
+  // At runtime, you would typically fetch the key from a secure vault or env
+  const masterKey = await generateEncryptionKey()
+
+  return gstate<VaultState>({
+    encryptedData: null
+  }, {
+    namespace: 'secure-vault',
+    persist: true,
+    encryptionKey: masterKey, // Real AES-256-GCM encryption
+    encoded: true
+  })
+}
+
+/**
+ * 2. Field-Level Sanitization (XSS Defense)
+ * RECOMMENDED FOR: Frontend (FE)
+ * Automatically strips <script> and other XSS vectors from input values.
+ */
+export const useProfileStore = gstate({
+  bio: '',
+  displayName: ''
+}, {
+  validateInput: true // Enables automatic sanitizeValue() on all .set() calls
+})
+
+/**
+ * 3. Audit Logging Integration
+ * RECOMMENDED FOR: Backend (BE) / Regulatory Compliance
+ * Tracks every 'set' or 'delete' operation for accountability.
+ */
+const auditBuffer: any[] = []
+setAuditLogger((entry) => {
+  // In a real BE scenario, send this to a logging service (Datadog, Elastic, etc.)
+  auditBuffer.push({
+    ...entry,
+    timestamp: new Date().toISOString()
+  })
+})
+
+/**
+ * 4. GDPR "Right to be Forgotten"
+ * RECOMMENDED FOR: Compliance
+ */
+export const purgeUserData = (store: any, userId: string) => {
+  // Wipe state and storage
+  store.deleteAll()
+
+  // Enterprise: Wipe GDPR consents and audit traces
+  store.deleteUserData(userId)
+
+  console.info(`[Security] Data purge requested for ${userId}`)
+}

package/examples/stress-tests/StressStore.d.ts

@@ -0,0 +1,41 @@
+export declare const useRapidStore: import("../../advanced").IStore<{
+    updates: number;
+    lastBatchTime: number;
+}> & (<K extends "updates" | "lastBatchTime">(key: K) => readonly [{
+    updates: number;
+    lastBatchTime: number;
+}[K] | undefined, (val: {
+    updates: number;
+    lastBatchTime: number;
+}[K] | ((draft: {
+    updates: number;
+    lastBatchTime: number;
+}[K]) => {
+    updates: number;
+    lastBatchTime: number;
+}[K]), options?: unknown) => boolean]);
+export declare const runRapidFire: (iterations?: number) => number;
+export declare const usePayloadStore: import("../../advanced").IStore<{
+    data: any;
+}> & (<K extends "data">(key: K) => readonly [{
+    data: any;
+}[K] | undefined, (val: {
+    data: any;
+}[K] | ((draft: {
+    data: any;
+}[K]) => {
+    data: any;
+}[K]), options?: unknown) => boolean]);
+export declare const generateBigPayload: (keys?: number) => number;
+export declare const useChainStore: import("../../advanced").IStore<{
+    base: number;
+}> & (<K extends "base">(key: K) => readonly [{
+    base: number;
+}[K] | undefined, (val: {
+    base: number;
+}[K] | ((draft: {
+    base: number;
+}[K]) => {
+    base: number;
+}[K]), options?: unknown) => boolean]);
+export declare const setupChain: () => void;

package/examples/stress-tests/StressStore.ts

@@ -0,0 +1,61 @@
+import { gstate } from '../../index'
+
+/**
+ * Rapid Fire Stress Test
+ * Tests RGS ability to handle massive bursts of updates.
+ */
+export const useRapidStore = gstate({
+  updates: 0,
+  lastBatchTime: 0
+})
+
+export const runRapidFire = (iterations: number = 1000) => {
+  const start = performance.now()
+  for (let i = 0; i < iterations; i++) {
+    useRapidStore.set('updates', i + 1)
+  }
+  const end = performance.now()
+  useRapidStore.set('lastBatchTime', end - start)
+  return end - start
+}
+
+/**
+ * Big Payload Stress Test
+ * Tests memory handling and cloning performance with large objects.
+ */
+export const usePayloadStore = gstate({
+  data: {} as any
+})
+
+export const generateBigPayload = (keys: number = 5000) => {
+  const bigObj: Record<string, any> = {}
+  for (let i = 0; i < keys; i++) {
+    bigObj[`key_${i}`] = {
+      id: i,
+      value: Math.random(),
+      meta: { timestamp: Date.now(), tags: ['test', 'stress', 'payload'] }
+    }
+  }
+
+  const start = performance.now()
+  usePayloadStore.set('data', bigObj)
+  const end = performance.now()
+  return end - start
+}
+
+/**
+ * Computed Chain Stress Test
+ * Tests dependency tracking and recursive updates.
+ */
+export const useChainStore = gstate({
+  base: 0
+})
+
+// Create a chain of 5 computed values
+export const setupChain = () => {
+  useChainStore.compute('level1', (get) => (get<number>('base') || 0) + 1)
+  useChainStore.compute('level2', (get) => (get<number>('level1') || 0) + 1)
+  useChainStore.compute('level3', (get) => (get<number>('level2') || 0) + 1)
+  useChainStore.compute('level4', (get) => (get<number>('level3') || 0) + 1)
+  useChainStore.compute('level5', (get) => (get<number>('level4') || 0) + 1)
+}

package/examples/undo-redo-editor/EditorStore.d.ts

@@ -0,0 +1,9 @@
+import { type IStore } from '../../index';
+export interface EditorState extends Record<string, unknown> {
+    content: string;
+    cursorPosition: number;
+}
+export declare const useEditor: IStore<EditorState> & (<K extends keyof EditorState>(key: K) => readonly [EditorState[K] | undefined, (val: EditorState[K] | ((draft: EditorState[K]) => EditorState[K]), options?: unknown) => boolean]);
+export declare const insertText: (text: string) => void;
+export declare const undo: () => any;
+export declare const redo: () => any;

package/examples/undo-redo-editor/EditorStore.ts

@@ -0,0 +1,29 @@
+import { gstate, undoRedoPlugin, type IStore } from '../../index'
+
+export interface EditorState extends Record<string, unknown> {
+  content: string
+  cursorPosition: number
+}
+
+/**
+ * Editor Store with History
+ * RECOMMENDED FOR: Frontend (FE)
+ */
+export const useEditor = gstate<EditorState>({
+  content: '',
+  cursorPosition: 0
+})
+
+// Add Plugin with safe type casting for demonstration
+useEditor._addPlugin(undoRedoPlugin({
+  limit: 50
+}) as any)
+
+export const insertText = (text: string) => {
+  const current = useEditor.get('content') || ''
+  useEditor.set('content', current + text)
+}
+
+// Plugin methods access
+export const undo = () => (useEditor.plugins as any).undoRedo?.undo()
+export const redo = () => (useEditor.plugins as any).undoRedo?.redo()

package/index.d.ts

@@ -2,9 +2,9 @@ import { createStore as baseCreateStore } from "./core/store";
 import { useStore as baseUseStore } from "./core/hooks";
 import * as Security from "./core/security";
 import type { IStore, StoreConfig } from "./core/types";
-export declare const gstate: <S extends Record<string, unknown>>(initialState: S, configOrNamespace?: string | StoreConfig<S>) => IStore<S> & ((key: string) => unknown);
+export declare const gstate: <S extends Record<string, unknown>>(initialState: S, configOrNamespace?: string | StoreConfig<S>) => IStore<S> & (<K extends keyof S>(key: K) => readonly [S[K] | undefined, (val: S[K] | ((draft: S[K]) => S[K]), options?: unknown) => boolean]);
 export { baseCreateStore as createStore };
-export { useStore, useIsStoreReady, initState, destroyState, useStore as useGState, useStore as useSimpleState } from "./core/hooks";
+export { useStore, useIsStoreReady, initState, getStore, destroyState, useStore as useGState, useStore as useSimpleState } from "./core/hooks";
 export { createAsyncStore } from "./core/async";
 export * from "./plugins/index";
 export { generateEncryptionKey, exportKey, importKey, isCryptoAvailable, setAuditLogger, logAudit, validateKey, sanitizeValue } from "./core/security";