# 🚀 ARGIS (RGS) - Reactive Global State

> **"Atomic Precision. Immutable Safety. Zen Simplicity."**
> The state management engine that **won't let you fail**.

[![npm version](https://img.shields.io/npm/v/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
[![npm downloads](https://img.shields.io/npm/dm/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-19+-61DAFB.svg)](https://react.dev/)

[![Powered by Immer](https://img.shields.io/badge/Powered%20by-Immer-2ECC71.svg)](https://github.com/immerjs/immer)
[![Typed with TypeScript](https://img.shields.io/badge/Typed%20with-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)

![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
[![E2E with Playwright](https://img.shields.io/badge/E2E%20with-Playwright-2ECC71.svg)](https://playwright.dev/)

> **🔐 Security Compliance**: This project is fully compliant with **NIST SP 800-132** standards for password-based key derivation, featuring AES-256-GCM encryption, PBKDF2 with 600k iterations, and 32-byte salts.

---

## ⚡ TL;DR

>Why ARGIS (RGS) Will Change How You Code Forever

```tsx
// One line. Zero boilerplate. Enterprise-grade power.
const useUser = gstate({
  name: 'Alice',
  cart: [],
  preferences: { theme: 'dark' }
})

// That's it. Use it anywhere:
const name = useUser(s => s.name)
const theme = useUser(s => s.preferences.theme)

// Mutations? Just write it. Immer handles immutability automatically.
useUser(s => {
  s.cart.push({ id: 1, item: 'Coffee Machine', price: 99 })
})
```

**Stop fighting your state management. Start building.**

---

## 🚀 Installation

```bash
# The fastest way to upgrade your React app
npm install @biglogic/rgs
```

```bash
# Or with pnpm
pnpm add @biglogic/rgs

# Or with yarn
yarn add @biglogic/rgs
```

---

## 🎯 Why ARGIS (RGS)

| Feature | Other Libraries | 🔥 ARGIS (RGS) |
|---------|----------------|--------------|
| **API Complexity** | 10+ functions, providers, reducers | **1 function** - `gstate()` |
| **Immutability** | Manual spreads, Redux boilerplate | **Automatic** - Powered by Immer |
| **Security** | None | **AES-256 + RBAC + GDPR** built-in |
| **Persistence** | Manual localStorage/sessionStorage | **First-class** - Auto-save anywhere |
| **Offline/Cloud Sync** | Non-existent | **Local-First + Cloud Sync** included |
| **Type Safety** | Partial | **100% TypeScript** out of the box |

### 🔥 The Truth About State Management

Most libraries make you **choose** between:
- ✗ Simplicity vs Power
- ✗ Security vs Speed
- ✗ Offline vs Cloud

**ARGIS (RGS) gives you ALL of it.**

---

## 🏆 RGS vs The Competition

| Feature | **RGS (Argis)** | Zustand | Redux Toolkit | Recoil | Jotai |
|---------|:---:|:---:|:---:|:---:|:---:|
| **Philosophy** | Zen State | Minimalist | Enterprise Flux | Atomic | Atomic |
| **API Surface** | **1 Function** | Simple | Complex | Complex | Simple |
| **Mutations** | **Magic (Immer)** | Manual | Magic | Manual | Manual |
| **Security** | 🛡️ **AES-256 + RBAC** | ❌ | ❌ | ❌ | ❌ |
| **Persistence** | 💾 **First-class** | 🔌 | 🔌 | 🔌 | 🔌 |
| **Local-First Sync** | ✅ **Built-in** | ❌ | ❌ | ❌ | ❌ |

> **RGS is the ONLY library treating Security and Persistence as first-class citizens.**

---

## 🎮 Quick Start - 30 Seconds to Glory

### The Zen Way (Recommended)

```tsx
import { gstate } from '@biglogic/rgs'

// ONE line creates a typed store hook
const useStore = gstate({
  count: 0,
  user: { name: 'Alice', email: 'alice@example.com' }
})

function Counter() {
  // Type-safe selectors - the React way
  const count = useStore(s => s.count)
  const userName = useStore(s => s.user.name)

  // Direct mutations - just write JavaScript
  const increment = () => useStore(s => { s.count++ })

  return (
    <div>
      <h1>Hello, {userName}!</h1>
      <p>Count: {count}</p>
      <button onClick={increment}>+1</button>
    </div>
  )
}
```

### The Classic Way (Global Store)

```tsx
import { initState, useStore } from '@biglogic/rgs'

// Initialize once at app root
initState({ namespace: 'myapp' })

// Use anywhere in your app
const [user, setUser] = useStore('user')
const [theme, setTheme] = useStore('theme')
```

---

## 🛡️ Enterprise-Grade Security (No Extra Code)

### AES-256-GCM Encryption

```tsx
// Your sensitive data is encrypted automatically
const useAuth = gstate({
  token: 'jwt-token-here',
  refreshToken: 'refresh-token'
}, { encoded: true })  // 🔐 AES-256-GCM encryption enabled
```

### RBAC (Role-Based Access Control)

```tsx
const store = gstate({
  adminPanel: { users: [], settings: {} },
  userProfile: {}
}, {
  rbac: {
    admin: ['adminPanel', 'userProfile'],
    user: ['userProfile'],
    guest: []
  }
})

// Only admins can touch adminPanel
store.set('adminPanel', { users: ['new'] }) // ✅ Works for admins
```

### GDPR Compliance

```tsx
// Export all user data (GDPR requirement)
store.exportData()  // Returns JSON of all stored data

// Delete all user data (GDPR "right to be forgotten")
store.deleteData()
```

---

## 💾 Persistence That Just Works

### Built-in Storage Adapters

```tsx
// localStorage (default) - survives browser restart
const useSettings = gstate({ theme: 'dark' }, { persist: true })

// sessionStorage - survives page refresh but not tab close
const useSession = gstate({ temporary: 'data' }, { storage: 'session' })

// Memory only - for ephemeral data
const useMemory = gstate({ cache: [] }, { storage: 'memory' })

// IndexedDB - for GB-scale data
const useBigData = gstate({ dataset: [] })
store._addPlugin(indexedDBPlugin({ dbName: 'my-app-db' }))
```

---

## 🔌 Plugins Ecosystem - Extend Without Limits

RGS comes with **11+ official plugins** ready to supercharge your app:

| Plugin | Purpose | One-Liner |
|--------|---------|-----------|
| `undoRedoPlugin` | Time travel through state | `store.undo()` / `store.redo()` |
| `syncPlugin` | Cross-tab sync (no server) | `store._addPlugin(syncPlugin(...))` |
| `indexedDBPlugin` | GB-scale storage | `store._addPlugin(indexedDBPlugin(...))` |
| `cloudSyncPlugin` | Cloud backup & sync | `store.plugins.cloudSync.sync()` |
| `devToolsPlugin` | Redux DevTools | `store._addPlugin(devToolsPlugin(...))` |
| `immerPlugin` | Mutable-style updates | `store.setWithProduce('key', fn)` |
| `snapshotPlugin` | Save/restore checkpoints | `store.takeSnapshot('backup')` |
| `schemaPlugin` | Runtime validation | `store._addPlugin(schemaPlugin(...))` |
| `guardPlugin` | Transform on set | `store._addPlugin(guardPlugin(...))` |
| `analyticsPlugin` | Track changes | `store._addPlugin(analyticsPlugin(...))` |
| `debugPlugin` | Console access (DEV) | `window.gstate.list()` |

### Undo/Redo - Never Lose Work

```tsx
import { undoRedoPlugin } from '@biglogic/rgs'

const store = gstate({ text: '' })
store._addPlugin(undoRedoPlugin({ limit: 50 }))

// User makes changes...
store.set('text', 'Hello World')
store.set('text', 'Hello Universe')

// Oops! Let's go back
store.undo()  // Returns to 'Hello World'
store.redo()   // Returns to 'Hello Universe'
```

### Cross-Tab Sync - Real-Time Everywhere

```tsx
import { syncPlugin } from '@biglogic/rgs/advanced'

const store = gstate({ theme: 'light' })
store._addPlugin(syncPlugin({ channelName: 'my-app' }))

// Change in Tab 1 → Instantly updates Tab 2, Tab 3, etc.
// ZERO server calls. Pure browser magic.
```

### Cloud Sync - Your Data, Everywhere

```tsx
import { cloudSyncPlugin, createMongoAdapter } from '@biglogic/rgs/advanced'

const adapter = createMongoAdapter(
  'https://data.mongodb-api.com/...',
  'your-api-key'
)

const store = gstate({ todos: [] })
store._addPlugin(cloudSyncPlugin({
  adapter,
  autoSyncInterval: 30000  // Every 30 seconds
}))

// Manual sync when needed
await store.plugins.cloudSync.sync()
```

---

## ☁️ Local-First Sync - Offline by Default

The **killer feature** that makes RGS unique:

```tsx
import { gstate, useSyncedState } from '@biglogic/rgs'

// Create store with automatic offline-first sync
const store = gstate({
  todos: [],
  user: null
}, {
  namespace: 'myapp',
  sync: {
    endpoint: 'https://api.example.com/sync',
    authToken: () => localStorage.getItem('auth_token'),
    autoSyncInterval: 30000,
    syncOnReconnect: true,
    strategy: 'last-write-wins'
  }
})

// Works offline. Automatically syncs when online.
function TodoList() {
  const [todos, setTodos] = useSyncedState('todos')

  const addTodo = (text) => {
    setTodos([...todos, { id: Date.now(), text }])
    // Synced automatically! ✨
  }

  return <ul>{todos.map(t => <li>{t.text}</li>)}</ul>
}
```

---

## ⚡ Advanced Superpowers

### Computed Values (Derived State)

```tsx
const store = gstate({
  firstName: 'John',
  lastName: 'Doe'
})

// Auto-calculated derived state
store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)

const fullName = store.get('fullName') // "John Doe"
```

### Error Handling

```tsx
const store = gstate({ data: null }, {
  onError: (error, context) => {
    console.error(`Error in ${context.operation}:`, error.message)
    // Send to Sentry, Datadog, etc.
  }
})
```

### Size Limits (Memory Protection)

```tsx
const store = gstate({ data: {} }, {
  maxObjectSize: 5 * 1024 * 1024,  // Warn if single value > 5MB
  maxTotalSize: 50 * 1024 * 1024    // Warn if total > 50MB
})
```

## 🧪 Testing - Rock-Solid Reliability

```bash
# Run unit tests
npm run test

# Run E2E tests (Playwright)
npm run test:e2e
```

- ✅ **E2E Tests** (Playwright) - Real browser, cross-tab sync
- ✅ **Concurrency Testing** - Race condition verification
- ✅ **Security Tests** - AES-256, RBAC, GDPR

---

## 🏗️ 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 |

---

## ✨ VScode extension

- [rgs.vsix](extension/rgs.vsix)

RGS (Reactive Global State) is a powerful Visual Studio Code extension that provides comprehensive IntelliSense, diagnostics, and a State Explorer sidebar for the RGS state management library.

### Key Features:
- Intelligent IntelliSense - Full API autocomplete for createStore, initState, useStore, useSyncedState, and more
- Hover Documentation - Inline documentation on hover for all RGS functions and types
- Code Snippets - Pre-built templates for common patterns
- Go to Definition - Navigate directly to store definitions

### Real-Time Diagnostics

Automatically detects issues in RGS code:

- ⚠️ Warnings: Undefined values, missing namespaces
- 💡 Hints: Type safety suggestions
- 🔒 Security: Detection of dangerous key assignments

### State Explorer Sidebar
Four powerful views:

1. Welcome - Quick access to extension features
2. State Explorer - Visual tree of all stores in your project
3. State Properties - Detailed view with types, defaults, and attributes (persisted, encrypted, readonly)
4. Information - Documentation and help resources

### Supported Languages

TypeScript (.ts, .tsx)
JavaScript (.js, .jsx)

---

## 📚 Documentation

- [SKILL](SKILL.md)
- [SUMMARY](SUMMARY.md)

### Core Concepts

- [Getting Started](markdown/getting-started.md)
- [Philosophy](markdown/philosophy.md)
- [The Magnetar Way](markdown/the-magnetar-way.md)

### Features & Architecture

- [Security Architecture](markdown/security-architecture.md)
- [Persistence and Safety](markdown/persistence-and-safety.md)
- [Local-First Sync](markdown/local-first-sync.md)
- [Plugins and Extensibility](markdown/plugins-and-extensibility.md)

### Development

- [Plugin SDK](markdown/plugin-sdk.md)
- [API Reference](markdown/api.md)
- [Migration Guide](markdown/migration-guide.md)

---

## 📄 License

**MIT** © [Dario Passariello](https://github.com/passariello)

---

**Made with ❤️ and a lot of caffè espresso!**

[⬆ Back to top](#-argis-rgs---reactive-global-state)