@biglogic/rgs 3.9.8 → 3.9.10

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/index.cjs

@@ -315,20 +315,20 @@ function f(e, ...t) {
 var g = Object, h = g.getPrototypeOf, m = "constructor", S = "prototype", _ = "configurable", w = "enumerable", b = "writable", v = "value", E = e => !!e && !!e[y];
 
 function k(e) {
-    return !!e && (C(e) || j(e) || !!e[d] || !!e[m]?.[d] || T(e) || I(e));
+    return !!e && (O(e) || j(e) || !!e[d] || !!e[m]?.[d] || T(e) || I(e));
 }
 
-var x = g[S][m].toString(), O = new WeakMap;
+var x = g[S][m].toString(), C = new WeakMap;
 
-function C(e) {
+function O(e) {
     if (!e || !z(e)) return !1;
     const t = h(e);
     if (null === t || t === g[S]) return !0;
     const n = g.hasOwnProperty.call(t, m) && t[m];
     if (n === Object) return !0;
     if (!V(n)) return !1;
-    let r = O.get(n);
-    return void 0 === r && (r = Function.toString.call(n), O.set(n, r)), r === x;
+    let r = C.get(n);
+    return void 0 === r && (r = Function.toString.call(n), C.set(n, r)), r === x;
 }
 
 function A(e, t, n = !0) {
@@ -356,7 +356,7 @@ function L(e, t) {
     if (T(e)) return new Map(e);
     if (I(e)) return new Set(e);
     if (j(e)) return Array[S].slice.call(e);
-    const n = C(e);
+    const n = O(e);
     if (!0 === t || "class_only" === t && !n) {
         const t = g.getOwnPropertyDescriptors(e);
         delete t[y];
@@ -791,8 +791,8 @@ var we = (new class {
         iv: r
     }, t.key, s);
     return JSON.parse((new TextDecoder).decode(o));
-}, Oe = null, Ce = e => {
-    Oe && Oe(e);
+}, Ce = null, Oe = e => {
+    Ce && Ce(e);
 }, Ae = (e, t, n) => {
     e.set(t instanceof RegExp ? t.source : t, n);
 }, De = (e, t, n, r) => {
@@ -831,7 +831,7 @@ var we = (new class {
         granted: r,
         timestamp: Date.now()
     }, o = e.get(t) || [];
-    return o.push(s), e.set(t, o), Ce({
+    return o.push(s), e.set(t, o), Oe({
         timestamp: Date.now(),
         action: "set",
         key: `consent:${n}`,
@@ -866,7 +866,7 @@ var Te = () => {
         }
     };
 }, Ve = n => {
-    const r = new Map, s = new Map, o = new Map, a = new Set, i = new Map, u = new Set, d = new Map, y = new Map, p = new Map, f = new Map, g = new Map, h = new Map, m = new Map, S = new Map, _ = n?.namespace || "gstate", w = n?.silent ?? !1, b = n?.debounceTime ?? 150, v = n?.version ?? 0, E = n?.storage || Ie(), k = n?.onError, x = n?.maxObjectSize ?? 0, O = n?.maxTotalSize ?? 0, C = n?.encryptionKey ?? null, A = n?.validateInput ?? !0, D = n?.auditEnabled ?? !0, M = n?.userId, P = n?.immer ?? !0, R = n?.persistByDefault ?? n?.persistence ?? n?.persist ?? !1;
+    const r = new Map, s = new Map, o = new Map, a = new Set, i = new Map, u = new Set, d = new Map, y = new Map, p = new Map, f = new Map, g = new Map, h = new Map, m = new Map, S = new Map, _ = n?.namespace || "gstate", w = n?.silent ?? !1, b = n?.debounceTime ?? 150, v = n?.version ?? 0, E = n?.storage || Ie(), k = n?.onError, x = n?.maxObjectSize ?? 0, C = n?.maxTotalSize ?? 0, O = n?.encryptionKey ?? null, A = n?.validateInput ?? !0, D = n?.auditEnabled ?? !0, M = n?.userId, P = n?.immer ?? !0, R = n?.persistByDefault ?? n?.persistence ?? n?.persist ?? !1;
     n?.accessRules && n.accessRules.forEach(e => Ae(m, e.pattern, e.permissions));
     let j, T = !1, I = !1, z = !1, V = 0, $ = null, N = null;
     const U = new Promise(e => {
@@ -879,7 +879,7 @@ var Te = () => {
         storage: E,
         config: n || {},
         diskQueue: g,
-        encryptionKey: C,
+        encryptionKey: O,
         audit: q,
         onError: k,
         silent: w,
@@ -924,7 +924,7 @@ var Te = () => {
             }
         })(B(), e, t);
     }, q = (e, t, n, r) => {
-        D && null !== Oe && Ce && Ce({
+        D && null !== Ce && Oe && Oe({
             timestamp: Date.now(),
             action: e,
             key: t,
@@ -1038,7 +1038,7 @@ var Te = () => {
         })(K());
     }, X = {}, Z = {
         _setSilently: (t, n) => {
-            const a = o.get(t) || 0, i = P && null !== n && "object" == typeof n ? F(e(n), !0) : n, c = (x > 0 || O > 0) && !Te() ? J(i) : 0;
+            const a = o.get(t) || 0, i = P && null !== n && "object" == typeof n ? F(e(n), !0) : n, c = (x > 0 || C > 0) && !Te() ? J(i) : 0;
             V = V - a + c, o.set(t, c), r.set(t, i), s.set(t, (s.get(t) || 0) + 1), N = null;
         },
         _registerMethod: (e, t, n) => {
@@ -1058,7 +1058,7 @@ var Te = () => {
             });
             const p = P && null !== d && "object" == typeof d ? F(e(d), !0) : d;
             if (!t(l, p)) {
-                const e = (x > 0 || O > 0) && !Te() ? J(p) : 0;
+                const e = (x > 0 || C > 0) && !Te() ? J(p) : 0;
                 if (x > 0 && e > x) {
                     const t = new Error(`Object size (${e} bytes) exceeds maxObjectSize (${x} bytes)`);
                     return k && k(t, {
@@ -1066,10 +1066,10 @@ var Te = () => {
                         key: a
                     }), !1;
                 }
-                if (O > 0) {
+                if (C > 0) {
                     const t = V - y + e;
-                    if (t > O) {
-                        const e = new Error(`Total store size (${t} bytes) exceeds limit (${O} bytes)`);
+                    if (t > C) {
+                        const e = new Error(`Total store size (${t} bytes) exceeds limit (${C} bytes)`);
                         return k && k(e, {
                             operation: "set"
                         }), !1;
@@ -1291,7 +1291,7 @@ var Te = () => {
                 operation: "hydration"
             });
         }
-    })(K(), e => (x > 0 || O > 0) && !Te() ? J(e) : 0, () => {
+    })(K(), e => (x > 0 || C > 0) && !Te() ? J(e) : 0, () => {
         z = !0, N = null, j(), Q();
     }).then(() => {}) : (z = !0, j()), n?.sync) {
         const e = n.sync, t = async () => {
@@ -1871,8 +1871,9 @@ exports.getStore = Ne, exports.gstate = (e, t) => {
     e && Object.entries(e).forEach(([e, t]) => {
         null === n.get(e) && n._setSilently(e, t);
     });
-    return "undefined" == typeof window || Te() || (window.gstate = n, window.gState = n, 
-    window.rgs = n), Object.assign(e => Ue(e, n), n);
+    const r = e => Ue(e, n);
+    return "undefined" == typeof window || Te() || (window.gstate = r, window.gState = n, 
+    window.rgs = n), Object.assign(r, n);
 }, exports.guardPlugin = e => ({
     name: "gstate-guard",
     hooks: {
@@ -1982,7 +1983,7 @@ exports.hydrateOnClient = async e => {
         e._setSilently(t, n);
     });
 }, exports.isClientSide = Qe, exports.isCryptoAvailable = Ee, exports.isServerSide = He, 
-exports.logAudit = Ce, exports.loggerPlugin = e => ({
+exports.logAudit = Oe, exports.loggerPlugin = e => ({
     name: "gstate-logger",
     hooks: {
         onSet: ({key: e, value: t, version: n}) => {
@@ -2025,7 +2026,7 @@ exports.logAudit = Ce, exports.loggerPlugin = e => ({
     type: "select",
     selector: e
 }), exports.setAuditLogger = e => {
-    Oe = e;
+    Ce = e;
 }, exports.snapshotPlugin = () => {
     const e = new Map;
     return {
@@ -2120,7 +2121,12 @@ exports.logAudit = Ce, exports.loggerPlugin = e => ({
 exports.useHydrationStatus = Ye, exports.useIsStoreReady = e => {
     const t = e || $e, r = n.useMemo(() => e => t ? t._subscribe(e) : () => {}, [ t ]);
     return n.useSyncExternalStore(r, () => !!t && t.isReady, () => !0);
-}, exports.useSimpleState = Ue, exports.useStore = Ue, exports.useSyncStatus = () => {
+}, exports.useSimpleState = Ue, exports.useStore = Ue, exports.useStoreSubscribe = function(e) {
+    const t = n.useMemo(() => e || $e, [ e ]), r = n.useCallback(e => t ? t._subscribe(e) : () => {}, [ t ]), s = n.useCallback(() => !0, []), o = n.useCallback(() => !0, []);
+    n.useSyncExternalStore(r, s, o);
+    const [, a] = n.useState(0);
+    return [ !0, n.useCallback(() => a(e => e + 1), []) ];
+}, exports.useSyncStatus = () => {
     const [e, t] = n.useState({
         isOnline: !0,
         isSyncing: !1,

package/index.d.ts

@@ -2,7 +2,7 @@ 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> & (<K extends keyof S>(key: K) => readonly [S[K] | undefined, (val: S[K] | ((draft: S[K]) => S[K]), options?: unknown) => boolean]);
+export declare const 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] | import(".").StateUpdater<S[K]>, options?: import("./advanced").PersistOptions) => boolean]) & IStore<S>;
 export { baseCreateStore as createStore };
 export { useStore, useIsStoreReady, initState, getStore, destroyState, useStore as useGState, useStore as useSimpleState } from "./core/hooks";
 export { createAsyncStore } from "./core/async";
@@ -12,7 +12,7 @@ export { createThunkStore, createActions, createAsyncAction, createAsyncActions,
 export type { ThunkAction, ThunkDispatch, ThunkActionPayload, Effect } from "./core/thunk";
 export { SyncEngine, createSyncEngine } from "./core/sync";
 export type { SyncConfig, SyncState, SyncResult, SyncStrategy, ConflictInfo, ConflictResolution } from "./core/sync";
-export { initSync, destroySync, useSyncedState, useSyncStatus, triggerSync } from "./core/hooks";
+export { initSync, destroySync, useSyncedState, useSyncStatus, triggerSync, useStoreSubscribe } from "./core/hooks";
 export * from "./plugins/index";
 export { generateEncryptionKey, exportKey, importKey, isCryptoAvailable, setAuditLogger, logAudit, validateKey, sanitizeValue, deriveKeyFromPassword, generateSalt } from "./core/security";
 export declare const addAccessRule: (pattern: string | ((key: string, userId?: string) => boolean), perms: Security.Permission[]) => void | undefined;