@biglogic/rgs 3.9.7 → 3.9.9

package/SKILL.md

@@ -0,0 +1,148 @@
+---
+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:
+
+```typescript
+/**
+ * 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
+
+```typescript
+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
+
+```typescript
+import { isServerSide, hydrateOnClient } from '@biglogic/rgs'
+
+if (isServerSide()) {
+  // Server-side logic
+}
+
+hydrateOnClient(myStore)
+```
+
+### Security
+
+```typescript
+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

package/core/hooks.d.ts

@@ -15,3 +15,4 @@ export declare function useSyncedState<T = unknown>(key: string, store?: IStore<
 ];
 export declare const useSyncStatus: () => SyncState;
 export declare const triggerSync: (namespace?: string) => Promise<void>;
+export declare function useStoreSubscribe<S extends Record<string, unknown> = Record<string, unknown>>(store?: IStore<S>): readonly [boolean, () => void];

package/core/ssr.d.ts

@@ -0,0 +1,73 @@
+import type { IStore, StoreConfig } from "./types";
+export declare const isServerSide: () => boolean;
+export declare const isClientSide: () => boolean;
+export interface SSRStoreConfig<S extends Record<string, unknown>> extends StoreConfig<S> {
+    deferHydration?: boolean;
+    initialState?: S;
+    ssrSafe?: boolean;
+}
+export declare const createSSRStore: <S extends Record<string, unknown>>(config?: SSRStoreConfig<S>) => IStore<S> & {
+    hydrate: () => Promise<void>;
+    getSerializedState: () => string | null;
+    isHydrated: () => boolean;
+};
+export declare const hydrateOnClient: (store: IStore<Record<string, unknown>>) => Promise<void>;
+export declare const dehydrateStore: (store: IStore<Record<string, unknown>>) => string;
+export declare const rehydrateStore: (store: IStore<Record<string, unknown>>, serializedState: string) => void;
+export declare const useHydrated: () => boolean;
+export declare const useHydrationStatus: () => {
+    isHydrated: boolean;
+    isHydrating: boolean;
+};
+export declare const useDeferredStore: <S extends Record<string, unknown>>(store: IStore<S> & {
+    isHydrated?: () => boolean;
+}) => IStore<S>;
+export declare const createNextStore: <S extends Record<string, unknown>>(config?: SSRStoreConfig<S>) => IStore<S> & {
+    hydrate: () => Promise<void>;
+    getSerializedState: () => string | null;
+    isHydrated: () => boolean;
+} & {
+    useHydrated: () => boolean;
+    useHydrationStatus: () => {
+        isHydrated: boolean;
+        isHydrating: boolean;
+    };
+    useDeferredStore: <K extends keyof S>(key: K) => unknown;
+};
+export declare const getSSRInitialState: (store: IStore<Record<string, unknown>>) => Record<string, unknown>;
+export declare const initializeFromSSR: (store: IStore<Record<string, unknown>>, initialState: Record<string, unknown>) => void;
+declare const _default: {
+    isServerSide: () => boolean;
+    isClientSide: () => boolean;
+    createSSRStore: <S extends Record<string, unknown>>(config?: SSRStoreConfig<S>) => IStore<S> & {
+        hydrate: () => Promise<void>;
+        getSerializedState: () => string | null;
+        isHydrated: () => boolean;
+    };
+    hydrateOnClient: (store: IStore<Record<string, unknown>>) => Promise<void>;
+    dehydrateStore: (store: IStore<Record<string, unknown>>) => string;
+    rehydrateStore: (store: IStore<Record<string, unknown>>, serializedState: string) => void;
+    useHydrated: () => boolean;
+    useHydrationStatus: () => {
+        isHydrated: boolean;
+        isHydrating: boolean;
+    };
+    useDeferredStore: <S extends Record<string, unknown>>(store: IStore<S> & {
+        isHydrated?: () => boolean;
+    }) => IStore<S>;
+    createNextStore: <S extends Record<string, unknown>>(config?: SSRStoreConfig<S>) => IStore<S> & {
+        hydrate: () => Promise<void>;
+        getSerializedState: () => string | null;
+        isHydrated: () => boolean;
+    } & {
+        useHydrated: () => boolean;
+        useHydrationStatus: () => {
+            isHydrated: boolean;
+            isHydrating: boolean;
+        };
+        useDeferredStore: <K extends keyof S>(key: K) => unknown;
+    };
+    getSSRInitialState: (store: IStore<Record<string, unknown>>) => Record<string, unknown>;
+    initializeFromSSR: (store: IStore<Record<string, unknown>>, initialState: Record<string, unknown>) => void;
+};
+export default _default;

package/core/thunk.d.ts

@@ -0,0 +1,75 @@
+import type { IStore } from "./types";
+export type ThunkAction<R = void, S extends Record<string, unknown> = Record<string, unknown>> = (dispatch: ThunkDispatch<S>, getState: () => S, extraArgument?: unknown) => Promise<R> | R;
+export type ThunkDispatch<S extends Record<string, unknown> = Record<string, unknown>> = <R>(action: ThunkAction<R, S> | ThunkActionPayload<S>) => Promise<R>;
+export interface ThunkActionPayload<_S extends Record<string, unknown> = Record<string, unknown>> {
+    type: string;
+    payload?: unknown;
+    meta?: Record<string, unknown>;
+}
+export interface ThunkMiddlewareConfig {
+    extraArgument?: unknown;
+    dispatchKey?: string;
+}
+export declare const createThunkStore: <S extends Record<string, unknown>>(store: IStore<S>, config?: ThunkMiddlewareConfig) => IStore<S> & {
+    dispatch: ThunkDispatch<S>;
+};
+export declare const createActions: <S extends Record<string, unknown>, T extends Record<string, unknown>>(store: IStore<S>, creators: T) => T & {
+    dispatch: ThunkDispatch<S>;
+};
+export declare const createAsyncAction: <T>(key: string, fetcher: () => Promise<T>) => ThunkAction<T, Record<string, {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}>>;
+export declare const createAsyncActions: <S extends Record<string, unknown>>(store: IStore<S>, actions: Record<string, () => Promise<unknown>>) => Record<string, ThunkAction<unknown, S>>;
+export type Effect = {
+    type: 'call';
+    fn: () => Promise<unknown>;
+    args?: unknown[];
+} | {
+    type: 'put';
+    action: ThunkActionPayload<Record<string, unknown>>;
+} | {
+    type: 'select';
+    selector: (state: Record<string, unknown>) => unknown;
+} | {
+    type: 'take';
+    pattern: string | ((action: ThunkActionPayload) => boolean);
+} | {
+    type: 'all';
+    effects: Effect[];
+} | {
+    type: 'race';
+    effects: Record<string, Effect>;
+};
+export declare const call: (fn: () => Promise<unknown>, ...args: unknown[]) => Effect;
+export declare const put: (action: ThunkActionPayload<Record<string, unknown>>) => Effect;
+export declare const select: (selector: (state: Record<string, unknown>) => unknown) => Effect;
+export declare const take: (pattern: string | ((action: ThunkActionPayload) => boolean)) => Effect;
+export declare const all: (effects: Effect[]) => Effect;
+export declare const race: (effects: Record<string, Effect>) => Effect;
+export declare const createSaga: <S extends Record<string, unknown>>(generator: Generator<Effect, void, unknown>) => ((dispatch: ThunkDispatch<S>, getState: () => S, extraArgument?: unknown) => Promise<void>);
+export declare const runSaga: <S extends Record<string, unknown>>(store: IStore<S>, saga: ThunkAction<void, S>) => (() => void);
+declare const _default: {
+    createThunkStore: <S extends Record<string, unknown>>(store: IStore<S>, config?: ThunkMiddlewareConfig) => IStore<S> & {
+        dispatch: ThunkDispatch<S>;
+    };
+    createActions: <S extends Record<string, unknown>, T extends Record<string, unknown>>(store: IStore<S>, creators: T) => T & {
+        dispatch: ThunkDispatch<S>;
+    };
+    createAsyncAction: <T>(key: string, fetcher: () => Promise<T>) => ThunkAction<T, Record<string, {
+        data: T | null;
+        loading: boolean;
+        error: Error | null;
+    }>>;
+    createAsyncActions: <S extends Record<string, unknown>>(store: IStore<S>, actions: Record<string, () => Promise<unknown>>) => Record<string, ThunkAction<unknown, S>>;
+    call: (fn: () => Promise<unknown>, ...args: unknown[]) => Effect;
+    put: (action: ThunkActionPayload<Record<string, unknown>>) => Effect;
+    select: (selector: (state: Record<string, unknown>) => unknown) => Effect;
+    take: (pattern: string | ((action: ThunkActionPayload) => boolean)) => Effect;
+    all: (effects: Effect[]) => Effect;
+    race: (effects: Record<string, Effect>) => Effect;
+    createSaga: <S extends Record<string, unknown>>(generator: Generator<Effect, void, unknown>) => ((dispatch: ThunkDispatch<S>, getState: () => S, extraArgument?: unknown) => Promise<void>);
+    runSaga: <S extends Record<string, unknown>>(store: IStore<S>, saga: ThunkAction<void, S>) => (() => void);
+};
+export default _default;

package/docs/SKILL.md

@@ -0,0 +1,148 @@
+---
+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:
+
+```typescript
+/**
+ * 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
+
+```typescript
+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
+
+```typescript
+import { isServerSide, hydrateOnClient } from '@biglogic/rgs'
+
+if (isServerSide()) {
+  // Server-side logic
+}
+
+hydrateOnClient(myStore)
+```
+
+### Security
+
+```typescript
+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

package/docs/markdown/api.md

@@ -6,6 +6,38 @@ Complete API reference for RGS (Argis) - Reactive Global State.
 
 ## Core Functions
 
+### `gstate`
+
+Creates a reactive store with a built-in typed hook in one line.
+
+```typescript
+function gstate<S extends Record<string, unknown>>(
+  initialState: S,
+  configOrNamespace?: string | StoreConfig<S>
+): (<K extends keyof S>(key: K) => readonly [S[K] | undefined, (val: S[K] | StateUpdater<S[K]>, options?: PersistOptions) => boolean]) & IStore<S>
+```
+
+**Parameters:**
+- `initialState` - Initial state object
+- `configOrNamespace` - Optional namespace string or full StoreConfig
+
+**Returns:** A callable function that returns typed hooks when called with a key, plus the full store interface.
+
+**Example:**
+```typescript
+const useCounter = gstate({ count: 0, name: 'John' })
+
+// Get typed hook for specific key
+const [count, setCount] = useCounter('count')
+const [name, setName] = useCounter('name')
+
+// Or use store methods directly
+useCounter.set('count', 5)
+useCounter.get('count')
+```
+
+---
+
 ### `initState`
 
 Initializes a global store instance.

package/docs/markdown/getting-started.md

@@ -7,62 +7,56 @@ Stop wasting time on boilerplate. Here is how you deploy the RGS Panzer in your
 The engine is lightweight but armored.
 
 ```bash
-npm install rgs
+npm install @biglogic/rgs
 ```
 
-## 2. Initialization: The "Big Bang"
+## 2. Quick Start: The Zen Way (Recommended)
 
-In your main entry file (e.g., `main.tsx` or `App.tsx`), wake up the engine once.
+The simplest way to use RGS - one line creates both store and typed hook.
 
 ```typescript
-import { initState, useStore } from '@biglogic/rgs';
+import { gstate } from '@biglogic/rgs';
 
-// Initialize with optional settings
-initState({
-  namespace: 'my-awesome-app',
-  persistence: true // Optional: Saves everything to localStorage automatically
-});
-```
-
-## 3. Usage: Instant Reactions
-
-Use the `useStore` hook. No providers, no wrappers. Just raw, atomic power.
-
-```tsx
-import { useStore } from '@biglogic/rgs';
+// ONE line creates a typed store + hook
+const useCounter = gstate({ count: 0, name: 'John' })
 
 function Counter() {
-  // If 'count' doesn't exist yet, it defaults to undefined. Easy.
-  const [count, setCount] = useStore<number>('count');
+  // Get typed hook for specific keys
+  const [count, setCount] = useCounter('count')
+  const [name, setName] = useCounter('name')
 
   return (
-    <div className="card">
-      <h1>Power Level: {count ?? 0}</h1>
-      <button onClick={() => setCount((prev) => (prev || 0) + 1)}>
-        Boost Power 💥
+    <div>
+      <p>Hello, {name}!</p>
+      <p>Count: {count}</p>
+      <button onClick={() =u003e setCount(count + 1)}>
+        +1
       </button>
     </div>
-  );
+  )
 }
 ```
 
-## 🧐 What just happened?
-
-- **Reactive Subscription**: `useStore('count')` tells React to watch the 'count' key. Surgical updates only.
-- **Global Scope**: `setCount` updates the value everywhere in the app, instantly.
-- **Resilient Nature**: If you access a key that hasn't been set yet, RGS returns `undefined` gracefully instead of throwing a tantrum.
+Or use store methods directly:
+```typescript
+useCounter.set('count', 5)
+useCounter.get('count')
+```
 
-## 🚨 Pro Tip: Direct Store Access
+## 3. Classic Way (Global Store)
 
-Need to access state outside of React components? Simple.
+If you prefer a global store approach:
 
 ```typescript
-import { getStore } from '@biglogic/rgs';
-
-const value = getStore()?.get('count');
-getStore()?.set('count', 9001);
-```
+import { initState, useStore } from '@biglogic/rgs';
 
----
+// Initialize once at app root
+initState({
+  namespace: 'my-awesome-app',
+  persistence: true
+});
 
-**Next step:** [The Magnetar Way: One-Liner Power](the-magnetar-way.md)
+// Use anywhere in your app
+const [count, setCount] = useStore('count')
+const [user, setUser] = useStore('user')
+```