@biglogic/rgs 3.9.13 → 3.9.20

package/markdown/api.md

@@ -115,6 +115,61 @@ function getStore(): IStore<Record<string, unknown>> | null
 
 ---
 
+### `getStoreByNamespace`
+
+Retrieves a store by its namespace.
+
+```typescript
+function getStoreByNamespace(namespace: string): IStore<Record<string, unknown>> | null
+```
+
+**Returns:** The `IStore` for the given namespace or `null`.
+
+---
+
+### `registerStore`
+
+Registers a store in the global registry for HMR cleanup. Used internally by `gstate()`.
+
+```typescript
+function registerStore(namespace: string, store: IStore<Record<string, unknown>>): void
+```
+
+---
+
+### `unregisterStore`
+
+Unregisters a store from the global registry.
+
+```typescript
+function unregisterStore(namespace: string): void
+```
+
+---
+
+### `destroyState`
+
+Destroys a store by namespace. Safe to call multiple times.
+
+```typescript
+function destroyState(namespace?: string): void
+```
+
+**Parameters:**
+- `namespace` - Optional namespace to destroy. If not provided, destroys the default store.
+
+---
+
+### `destroyAllStores`
+
+Destroys all registered stores. Useful for HMR, testing, and micro-frontend teardown.
+
+```typescript
+function destroyAllStores(): void
+```
+
+---
+
 ## Store Interface (`IStore`)
 
 ### State Operations
@@ -416,3 +471,123 @@ interface AccessRule {
 | `onRemove` | Called when a value is removed |
 | `onDestroy` | Called when store is destroyed |
 | `onTransaction` | Called during a transaction |
+
+---
+
+## SSR Hooks
+
+### `useHydrated`
+
+Returns `true` when the app is hydrated on the client.
+
+```typescript
+function useHydrated(): boolean
+```
+
+### `useHydrationStatus`
+
+Returns detailed hydration status.
+
+```typescript
+function useHydrationStatus(): { isHydrated: boolean; isHydrating: boolean }
+```
+
+### `useDeferredStore`
+
+Returns a store proxy that returns defaults until hydrated.
+
+```typescript
+function useDeferredStore<S>(store: IStore<S> & { isHydrated?: () => boolean }): IStore<S>
+```
+
+### `createSSRStore`
+
+Creates an SSR-safe store with hydration methods.
+
+```typescript
+function createSSRStore<S>(config?: SSRStoreConfig<S>): IStore<S> & {
+  hydrate: () => Promise<void>
+  getSerializedState: () => string | null
+  isHydrated: () => boolean
+}
+```
+
+### `createNextStore`
+
+Creates a Next.js App Router compatible store.
+
+```typescript
+function createNextStore<S>(config?: SSRStoreConfig<S>)
+```
+
+---
+
+## Sync API
+
+### `initSync`
+
+Initializes the sync engine for a store.
+
+```typescript
+function initSync(
+  store: IStore<Record<string, unknown>>,
+  config: SyncConfig
+): SyncEngine<Record<string, unknown>>
+```
+
+### `destroySync`
+
+Destroys the sync engine for a namespace.
+
+```typescript
+function destroySync(namespace: string): void
+```
+
+### `useSyncedState`
+
+Hook for offline-first synchronized state.
+
+```typescript
+function useSyncedState<T>(
+  key: string,
+  store?: IStore<Record<string, unknown>>
+): readonly [
+  T | undefined,
+  (val: T | StateUpdater<T>, options?: PersistOptions) => boolean,
+  SyncState
+]
+```
+
+### `useSyncStatus`
+
+Hook for global sync status.
+
+```typescript
+function useSyncStatus(): SyncState
+```
+
+### `triggerSync`
+
+Manually triggers sync for a namespace.
+
+```typescript
+function triggerSync(namespace?: string): Promise<void>
+```
+
+---
+
+## Changelog (v3.9.20)
+
+### New APIs
+- `registerStore()` / `unregisterStore()` - Store registry management
+- `getStoreByNamespace()` - Get store by namespace
+- `destroyAllStores()` - Destroy all registered stores
+- `destroyState(namespace?)` - Destroy store by namespace
+
+### Improvements
+- `gstate()` now auto-registers stores for HMR cleanup
+- `isEqual()` now supports Date, Map, Set, RegExp, TypedArray, ArrayBuffer
+- `getServerSnapshot()` uses safe Proxy for SSR selectors
+- `initState()` warnings only shown in development mode
+- `useSyncedState()` warns if `initSync()` not called
+- `safeBtoa()` / `safeAtob()` for SSR Node.js compatibility

package/markdown/getting-started.md

@@ -53,10 +53,41 @@ import { initState, useStore } from '@biglogic/rgs';
 // Initialize once at app root
 initState({
   namespace: 'my-awesome-app',
-  persistence: true
+  persistByDefault: true
 });
 
 // Use anywhere in your app
 const [count, setCount] = useStore('count')
 const [user, setUser] = useStore('user')
 ```
+
+## 4. Multi-Store Pattern (Recommended for Large Apps)
+
+For micro-frontends or large applications, use separate namespaces:
+
+```typescript
+import { gstate } from '@biglogic/rgs';
+
+// Cart store
+export const useCart = gstate({ items: [] }, { namespace: 'cart' })
+
+// User store
+export const useUser = gstate({ profile: null }, { namespace: 'user' })
+
+// Theme store
+export const useTheme = gstate({ mode: 'light' }, { namespace: 'theme' })
+```
+
+## 5. Cleanup (HMR / Testing)
+
+For Hot Module Replacement or test cleanup:
+
+```typescript
+import { destroyState, destroyAllStores } from '@biglogic/rgs';
+
+// Destroy specific store
+destroyState('cart')
+
+// Destroy all stores (useful for HMR)
+destroyAllStores()
+```

package/markdown/security-architecture.md

@@ -48,3 +48,9 @@ For real-world implementations, refer to the `examples/security-best-practices`
 - **Storage Key Validation**: Keys validated before persistence to prevent injection.
 - **Production Safety**: Global window access only enabled in development mode (`NODE_ENV !== 'production'`).
 - **PBKDF2 Key Derivation**: New `deriveKeyFromPassword()` and `generateSalt()` functions for secure password-based encryption (NIST SP 800-132 compliant - 600k iterations, 32-byte salt).
+
+## Summary of 3.9.20 Enhancements
+- **Safe Base64 for SSR**: `safeBtoa()` and `safeAtob()` functions with Node.js Buffer fallback for server-side rendering compatibility.
+- **Deep Equality Enhancement**: `isEqual()` now properly compares Date, Map, Set, RegExp, TypedArray, and ArrayBuffer objects.
+- **Development-Only Warnings**: `initState()` duplicate store warnings now only appear in development mode, preventing console spam in production.
+- **SSR Selector Safety**: `getServerSnapshot()` now uses a safe Proxy that returns `undefined` for any property access, preventing crashes when selectors access nested properties on empty state.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@biglogic/rgs",
   "code": "argis",
-  "version": "3.9.13",
+  "version": "3.9.20",
   "description": "Argis (RGS) - Reactive Global State: A react state everywhere made easy",
   "main": "./index.cjs",
   "browser": "./index.cjs",