---

name: biglogic-rgs description: Reactive global state management library for React - simple, secure, scalable

@biglogic/rgs - Reactive Global State

Overview

RGS (Argis) is a reactive global state management library for React. Simple, secure, and scalable. It provides typed state management with built-in persistence, security, and sync capabilities.

Instructions

Constraints

1. TypeScript Strict: Always use strict typing - avoid any unless absolutely necessary
2. No console.log: Use console.debug for debugging, or console.warn/console.error for warnings/errors
3. Build before commit: Always run npm run build successfully before any commit
4. Test TypeScript: Run npx tsc --noEmit to verify no type errors
5. No console.log debugging: Never leave console.log statements in production code
6. Use arrow functions: Prefer arrow functions over function declarations

Workflow

1. For new features:

   • Create in core/ folder
   • Export from index.ts if public API
   • Add types to core/types.ts
   • Run build and type-check

2. For bug fixes:

   • Run npx tsc --noEmit to identify issues
   • Fix type errors first
   • Verify build succeeds

3. For testing:

   • Run npm run build or npm run test
   • Config is in tests/ folder

Output Format

When adding new hooks or functions:

/**
 * Description of what the hook does.
 * @param param - Description of parameter
 * @returns Description of return value
 */
export const myHook = (param: string): boolean => {
  // Implementation
}

Usage Examples

Basic Store Creation

import { gstate } from '@biglogic/rgs'

// Create store with typed hook
const store = gstate({ count: 0, name: 'John' })

// Use typed hook for specific keys
const [count, setCount] = store('count')
const [name, setName] = store('name')

// Or use store directly
store.set('count', 5)
store.get('count')

SSR Support

import { isServerSide, hydrateOnClient } from '@biglogic/rgs'

if (isServerSide()) {
  // Server-side logic
}

hydrateOnClient(myStore)

Security

import { generateEncryptionKey, validateKey } from '@biglogic/rgs'

// Generate encryption key for secure persistence
const key = generateEncryptionKey()

// Validate keys to prevent XSS
if (validateKey(userInput)) {
  store.set(userInput, value)
}

API Quick Reference

Core

| Function | Description | |----------|-------------| | gstate(initialState, config?) | Creates store + returns typed hook | | useStore(key, store?) | React hook for state subscription | | createStore(config?) | Creates store instance | | initState(config?) | Initializes global store | | getStore() | Gets current default store |

SSR

| Function | Description | |----------|-------------| | isServerSide() | Check if running on server | | isClientSide() | Check if running on client | | hydrateOnClient(store) | Hydrate store on client |

Security

| Function | Description | |----------|-------------| | generateEncryptionKey() | Generate AES-256 key | | validateKey(key) | Validate key format (XSS prevention) | | sanitizeValue(value) | Sanitize value |

Project Structure

core/
├── hooks.ts       # React hooks (useStore, useSyncedState)
├── store.ts       # Core store implementation
├── types.ts       # TypeScript types
├── security.ts    # Security utilities
├── persistence.ts # Storage persistence
├── sync.ts        # Sync engine
└── ssr.ts        # SSR support

Dependencies

• peerDependencies: react, react-dom (>=16.8.0)
• devDependencies: typescript, tsup, terser

License

MIT - Copyright Dario Passariello