@biglogic/rgs 3.8.0 → 3.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biglogic/rgs",
-  "version": "3.8.0",
+  "version": "3.8.4",
   "license": "MIT",
   "description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
   "type": "module",
@@ -86,4 +86,4 @@
     "tslib": "^2.8.1",
     "typescript": "^5.9.3"
   }
-}
+}

package/docs/api.md

@@ -1,381 +0,0 @@
-# 📚 API Reference
-
-Complete API reference for RGS (Argis) - Reactive Global State.
-
----
-
-## Core Functions
-
-### `initState`
-
-Initializes a global store instance.
-
-```typescript
-function initState<S extends Record<string, unknown>>(
-  config?: StoreConfig<S>
-): IStore<S>
-```
-
-**Parameters:**
-- `config` - Optional store configuration
-
-**Returns:** `IStore<S>`
-
-**Example:**
-```typescript
-const store = initState({
-  namespace: 'myApp',
-  version: 1,
-  persistByDefault: true,
-  onError: (error, context) => {
-    console.error(`Error in ${context.operation}:`, error.message)
-  }
-})
-```
-
----
-
-### `useStore`
-
-React hook for reactive state.
-
-```typescript
-function useStore<T = unknown, S extends Record<string, unknown> = Record<string, unknown>>(
-  key: string,
-  store?: IStore<S>
-): readonly [T | undefined, (val: T | StateUpdater<T>, options?: PersistOptions) => boolean]
-```
-
-**Parameters:**
-- `key` - State key to subscribe to
-- `store` - Optional store instance
-
-**Returns:** Tuple of `[value, setter]`
-
----
-
-### `createStore`
-
-Creates a new store instance.
-
-```typescript
-function createStore<S extends Record<string, unknown>>(
-  config?: StoreConfig<S>
-): IStore<S>
-```
-
----
-
-### `getStore`
-
-Retrieves the currently active default store instance. Useful for accessing the store outside of React components or in utility functions.
-
-```typescript
-function getStore(): IStore<Record<string, unknown>> | null
-```
-
-**Returns:** The active `IStore` or `null` if no store was initialized via `initState`.
-
----
-
-## Store Interface (`IStore`)
-
-### State Operations
-
-#### `set`
-
-Sets a value in the store.
-
-```typescript
-store.set<T>(key: string, value: T | StateUpdater<T>, options?: PersistOptions): boolean
-```
-
-#### `get`
-
-Gets a value from the store.
-
-```typescript
-store.get<T>(key: string): T | null
-```
-
-#### `remove` / `delete`
-
-Removes a value from the store.
-
-```typescript
-store.remove(key: string): boolean
-store.delete(key: string): boolean
-```
-
-#### `deleteAll`
-
-Removes all values from the store.
-
-```typescript
-store.deleteAll(): void
-```
-
-#### `list`
-
-Returns all key-value pairs.
-
-```typescript
-store.list(): Record<string, unknown>
-```
-
----
-
-### Metadata Properties
-
-#### `namespace`
-
-The unique namespace of the store (read-only).
-
-```typescript
-store.namespace: string
-```
-
-#### `userId`
-
-The current user ID associated with the store for RBAC and audit logs (read-only).
-
-```typescript
-store.userId?: string
-```
-
----
-
-### Computed Values
-
-#### `compute`
-
-Creates or retrieves a computed (derived) value.
-
-```typescript
-store.compute<T>(key: string, selector: ComputedSelector<T>): T
-```
-
-**Example:**
-```typescript
-const fullName = store.compute('fullName', (get) => {
-  const first = get<string>('firstName')
-  const last = get<string>('lastName')
-  return `${first} ${last}`
-})
-```
-
-> **Note:** RGS supports **nested computed dependencies**. A computed value can reactively depend on other computed values in the same store.
-
----
-
-### Watching Changes
-
-#### `watch`
-
-Watches for changes on a specific key.
-
-```typescript
-store.watch<T>(key: string, callback: WatcherCallback<T>): () => void
-```
-
-**Returns:** Unsubscribe function
-
----
-
-### Transactions
-
-#### `transaction`
-
-Groups multiple operations into a single transaction.
-
-```typescript
-store.transaction(fn: () => void): void
-```
-
----
-
-### Middleware
-
-#### `use`
-
-Adds a middleware function.
-
-```typescript
-store.use(middleware: Middleware): void
-```
-
----
-
-### Lifecycle
-
-#### `destroy`
-
-Destroys the store and cleans up resources.
-
-```typescript
-store.destroy(): void
-```
-
----
-
-## Plugin API
-
-### `_addPlugin`
-
-Adds a plugin to the store.
-
-```typescript
-store._addPlugin(plugin: IPlugin): void
-```
-
-### `_removePlugin`
-
-Removes a plugin from the store.
-
-```typescript
-store._removePlugin(name: string): void
-```
-
-### `_registerMethod`
-
-Registers a custom method on the store.
-
-```typescript
-// New signature (recommended)
-store._registerMethod(pluginName: string, methodName: string, fn: (...args) => unknown): void
-```
-
----
-
-## Plugins Property
-
-Access plugin methods via `store.plugins`:
-
-```typescript
-store.plugins.undoRedo.undo()
-store.plugins.undoRedo.redo()
-store.plugins.counter.increment()
-store.plugins.cloudSync.sync()
-store.plugins.cloudSync.getStats()
-```
-
----
-
-## Configuration (`StoreConfig`)
-
-```typescript
-interface StoreConfig<S> {
-  /** Unique namespace for this store */
-  namespace?: string
-  /** Schema version */
-  version?: number
-  /** Suppress console warnings */
-  silent?: boolean
-  /** Debounce time for disk flush (default: 150ms) */
-  debounceTime?: number
-  /** Custom storage adapter */
-  storage?: CustomStorage | Storage
-  /** Migration function */
-  migrate?: (oldState: Record<string, unknown>, oldVersion: number) => S
-  /** Error handler */
-  onError?: (error: Error, context: { operation: string; key?: string }) => void
-  /** Max object size in bytes (default: 5MB) */
-  maxObjectSize?: number
-  /** Max total store size in bytes (default: 50MB) */
-  maxTotalSize?: number
-  /** AES-256-GCM encryption key */
-  encryptionKey?: EncryptionKey
-  /** Enable audit logging */
-  auditEnabled?: boolean
-  /** Current user ID for audit */
-  userId?: string
-  /** Enable input validation */
-  validateInput?: boolean
-  /** Access control rules */
-  accessRules?: Array<{
-    pattern: string | ((key: string, userId?: string) => boolean)
-    permissions: Permission[]
-  }>
-  /** Enable Immer (default: true) */
-  immer?: boolean
-}
-```
-
----
-
-## Persistence Options (`PersistOptions`)
-
-```typescript
-interface PersistOptions {
-  /** Persist to storage (default: localStorage) */
-  persist?: boolean
-  /** Base64 encode the value */
-  encoded?: boolean
-  /** AES-256-GCM encryption */
-  encrypted?: boolean
-  /** Time-to-live in milliseconds */
-  ttl?: number
-}
-```
-
----
-
-## Types
-
-### `StateUpdater`
-
-```typescript
-type StateUpdater<T> = (draft: T) => void | T
-```
-
-### `ComputedSelector`
-
-```typescript
-type ComputedSelector<T> = (get: <V>(key: string) => V | null) => T
-```
-
-### `WatcherCallback`
-
-```typescript
-type WatcherCallback<T> = (value: T | null) => void
-```
-
-### `Middleware`
-
-```typescript
-type Middleware<T = unknown> = (key: string, value: T, meta: StoreMetadata) => void
-```
-
----
-
-## Security Types
-
-### `Permission`
-
-```typescript
-type Permission = 'read' | 'write' | 'delete' | 'admin'
-```
-
-### `AccessRule`
-
-```typescript
-interface AccessRule {
-  pattern: string | ((key: string, userId?: string) => boolean)
-  permissions: Permission[]
-}
-```
-
----
-
-## Plugin Hooks
-
-| Hook | Description |
-|------|-------------|
-| `onInit` | Called when plugin is first initialized |
-| `onInstall` | Called when plugin is added to store |
-| `onBeforeSet` | Called before a value is set |
-| `onSet` | Called after a value is set |
-| `onGet` | Called when a value is retrieved |
-| `onRemove` | Called when a value is removed |
-| `onDestroy` | Called when store is destroyed |
-| `onTransaction` | Called during a transaction |

package/docs/chapters/05-plugin-sdk.md

@@ -1,290 +0,0 @@
-# 🔧 Plugin SDK: Build Your Own Extensions
-
-This guide shows you how to create custom plugins for RGS (Argis) - Reactive Global State. Plugins are the way to extend the store with custom functionality.
-
----
-
-## 📦 What is a Plugin?
-
-A plugin is a module that:
-
-1. Adds **lifecycle hooks** to react to store events
-2. Exposes **custom methods** via `store.plugins.yourPlugin.method()`
-3. Can **validate**, **transform**, or **track** data
-
----
-
-## 🏗️ Plugin Structure
-
-Every plugin implements the `IPlugin` interface:
-
-```typescript
-import type { IPlugin, PluginContext } from '@biglogic/rgs'
-
-interface IPlugin {
-  name: string
-  hooks: {
-    onInit?: (ctx: PluginContext) => void | Promise<void>
-    onInstall?: (ctx: PluginContext) => void | Promise<void>
-    onSet?: (ctx: PluginContext) => void | Promise<void>
-    onGet?: (ctx: PluginContext) => void | Promise<void>
-    onRemove?: (ctx: PluginContext) => void | Promise<void>
-    onDestroy?: (ctx: PluginContext) => void | Promise<void>
-    onTransaction?: (ctx: PluginContext) => void | Promise<void>
-    onBeforeSet?: (ctx: PluginContext) => void | Promise<void>
-    onAfterSet?: (ctx: PluginContext) => void | Promise<void>
-  }
-}
-```
-
----
-
-## 🎯 Creating Your First Plugin
-
-### Example: A Simple Logger Plugin
-
-```typescript
-import type { IPlugin, PluginContext } from '@biglogic/rgs'
-
-export const loggerPlugin = (): IPlugin => {
-  return {
-    name: 'my-logger',
-    hooks: {
-      onSet: ({ key, value }: PluginContext) => {
-        console.log(`[Logger] Set "${key}" to:`, value)
-      },
-      onGet: ({ key, value }: PluginContext) => {
-        console.log(`[Logger] Got "${key}":`, value)
-      },
-      onRemove: ({ key }: PluginContext) => {
-        console.log(`[Logger] Removed "${key}"`)
-      }
-    }
-  }
-}
-
-// Usage
-store._addPlugin(loggerPlugin())
-```
-
----
-
-## 🔌 Registering Custom Methods
-
-Plugins can expose methods accessible via `store.plugins.pluginName.methodName()`:
-
-```typescript
-import type { IPlugin, PluginContext } from '@biglogic/rgs'
-
-export const counterPlugin = (): IPlugin => {
-  let _count = 0
-
-  return {
-    name: 'counter',
-    hooks: {
-      onInstall: ({ store }) => {
-        // Register methods with explicit plugin namespace
-        store._registerMethod('counter', 'increment', () => {
-          _count++
-          return _count
-        })
-
-        store._registerMethod('counter', 'decrement', () => {
-          _count--
-          return _count
-        })
-
-        store._registerMethod('counter', 'getCount', () => _count)
-
-        store._registerMethod('counter', 'reset', () => {
-          _count = 0
-          return _count
-        })
-      }
-    }
-  }
-}
-
-// Usage
-store._addPlugin(counterPlugin())
-
-store.plugins.counter.increment()   // returns 1
-store.plugins.counter.increment()  // returns 2
-store.plugins.counter.getCount()  // returns 2
-store.plugins.counter.decrement()  // returns 1
-store.plugins.counter.reset()      // returns 0
-```
-
----
-
-## ⚙️ Plugin Configuration
-
-Plugins can accept configuration options:
-
-```typescript
-interface ValidationConfig {
-  email?: (value: string) => boolean | string
-  username?: (value: string) => boolean | string
-  maxLength?: number
-}
-
-export const validationPlugin = (config: ValidationConfig): IPlugin => {
-  return {
-    name: 'validation',
-    hooks: {
-      onBeforeSet: ({ key, value }) => {
-        const validator = config[key as keyof ValidationConfig]
-        if (validator && typeof value === 'string') {
-          const result = validator(value)
-          if (result !== true) {
-            throw new Error(`Validation failed for "${key}": ${result}`)
-          }
-        }
-
-        // Check maxLength
-        if (config.maxLength && typeof value === 'string' && value.length > config.maxLength) {
-          throw new Error(`"${key}" exceeds max length of ${config.maxLength}`)
-        }
-      }
-    }
-  }
-}
-
-// Usage
-store._addPlugin(validationPlugin({
-  email: (v) => v.includes('@') ? true : 'Invalid email',
-  username: (v) => v.length >= 3 ? true : 'Too short',
-  maxLength: 100
-}))
-```
-
----
-
-## 🔄 Using Store Internals
-
-Plugins have access to internal store methods:
-
-```typescript
-export const auditPlugin = (): IPlugin => {
-  return {
-    name: 'audit',
-    hooks: {
-      onSet: ({ store, key, value, version }) => {
-        // Read other keys
-        const currentUser = store.get('currentUser')
-
-        // Set silently (without triggering hooks)
-        store._setSilently('_auditLog', [
-          ...(store.get('_auditLog') || []),
-          { action: 'set', key, timestamp: Date.now() }
-        ])
-
-        // Get version
-        const ver = store._getVersion(key)
-      }
-    }
-  }
-}
-```
-
-### Available Internal Methods
-
-| Method | Description |
-|--------|-------------|
-| `store.get(key)` | Get a value |
-| `store.set(key, value)` | Set a value |
-| `store._setSilently(key, value)` | Set without triggering hooks |
-| `store.list()` | Get all key-value pairs |
-| `store._getVersion(key)` | Get version number |
-| `store._subscribe(callback)` | Subscribe to changes |
-
----
-
-## 🧪 Full Example: Persistence Plugin
-
-Here's a complete plugin that auto-saves to a custom backend:
-
-```typescript
-import type { IPlugin, PluginContext } from '@biglogic/rgs'
-
-interface AutoSaveConfig {
-  endpoint: string
-  debounceMs?: number
-  keys?: string[]  // Which keys to save
-}
-
-export const autoSavePlugin = (config: AutoSaveConfig): IPlugin => {
-  const { endpoint, debounceMs = 1000, keys } = config
-  let _saveTimeout: ReturnType<typeof setTimeout> | null = null
-
-  const save = async (store: any) => {
-    const data = keys
-      ? Object.fromEntries(keys.map(k => [k, store.get(k)]))
-      : store.list()
-
-    try {
-      await fetch(endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(data)
-      })
-      console.log('[AutoSave] Saved to', endpoint)
-    } catch (err) {
-      console.error('[AutoSave] Failed:', err)
-    }
-  }
-
-  return {
-    name: 'auto-save',
-    hooks: {
-      onInstall: async ({ store }) => {
-        // Load initial data
-        try {
-          const res = await fetch(endpoint)
-          const data = await res.json()
-          Object.entries(data).forEach(([k, v]) => {
-            store._setSilently(k, v)
-          })
-        } catch {
-          // Ignore load errors
-        }
-      },
-      onSet: ({ store }) => {
-        // Debounced save
-        if (_saveTimeout) clearTimeout(_saveTimeout)
-        _saveTimeout = setTimeout(() => save(store), debounceMs)
-      },
-      onDestroy: ({ store }) => {
-        // Save immediately on destroy
-        if (_saveTimeout) clearTimeout(_saveTimeout)
-        save(store)
-      }
-    }
-  }
-}
-
-// Usage
-store._addPlugin(autoSavePlugin({
-  endpoint: '/api/save',
-  debounceMs: 2000,
-  keys: ['user', 'settings', 'preferences']
-}))
-```
-
----
-
-## 📋 Plugin Best Practices
-
-1. **Use Namespaced Methods** - Always use `store._registerMethod('pluginName', 'methodName', fn)`
-2. **Clean Up Resources** - Use `onDestroy` to clean up timers, listeners, etc.
-3. **Handle Errors** - Wrap async operations in try/catch
-4. **Document Configuration** - Provide clear TypeScript interfaces
-5. **Test Hooks** - Test each hook independently
-
----
-
-## 📚 Related
-
-- [Plugin API Reference](../api/plugins.md)
-- [Chapter 5: Ecosystem and Plugins](05-plugins-and-extensibility.md)
-- [Case Studies](06-case-studies.md)