memorio 4.7.0 → 4.7.3

package/llms.txt

@@ -8,6 +8,8 @@
 npm i memorio
 ```
 
+> **For AI agents generating code against this library:** default `state` is a shared, global namespace unless a context is explicitly created with `memorio.createContext(id)`. Do not assume per-request or per-tab isolation is automatic - see [Session & Context Isolation](#session--context-isolation) before generating server-side code that handles more than one user/request.
+
 ## Core Concepts
 
 Memorio provides 6 storage modules plus utilities:
@@ -15,11 +17,11 @@ Memorio provides 6 storage modules plus utilities:
 | Module | Purpose | Persistence |
 |--------|---------|-------------|
 | `state` | Reactive, volatile state | In-memory (resets on refresh) |
-| `store` | localStorage persistence | Survives browser refresh |
-| `session` | sessionStorage | Dies with browser tab |
+| `store` | localStorage persistence | Survives browser refresh; falls back to non-durable in-memory `Map` in Node.js/Deno |
+| `session` | sessionStorage | Dies with browser tab; falls back to non-durable in-memory `Map` in Node.js/Deno |
 | `cache` | In-memory cache | Fastest read, no persistence |
-| `idb` | IndexedDB | Structured, async, persistent (browser-only) |
-| `observer` | Object watcher | Legacy |
+| `idb` | IndexedDB | Structured, async, persistent (browser-only - disabled in Node.js/Deno) |
+| `observer` | Object watcher | Legacy; string-based paths, not statically checked against `state`'s shape |
 | `useObserver` | React hook | Auto-discovery of state paths |
 
 ## Quick Start
@@ -40,7 +42,7 @@ useObserver(
 
 ## API Reference
 
-### `state` — Reactive State
+### `state` - Reactive State
 
 Global, Proxy-based, reactive state management.
 
@@ -61,21 +63,23 @@ state.remove('items')
 
 // Clear all
 state.removeAll()
-
-// Lock/unlock for frozen objects
-state.lock()    // freeze everything
-state.unlock()  // unfreeze
 ```
 
+**Locking - VERIFY BEFORE PUBLISHING:** this library's own documents currently disagree on scope.
+
+- One source describes **per-key** locking: `state.config.lock()` freezes only the `config` key; other keys remain writable.
+- Another source describes **global** locking: `state.lock()` / `state.unlock()` freezing the entire `state` object at once.
+
+These are materially different behaviors - confirm against the actual source which one (or both, with distinct method names) is implemented, then replace this note with the real signature(s). Do not ship a docs update, or generate code against this section, until this is resolved.
+
 **Features:**
 - Automatic path tracking via `__path` property
 - Nested proxy support
-- Lock/unlock per-key or globally
 - Auto-dispatches events on changes
 
-### `store` — localStorage Persistence
+### `store` - localStorage Persistence
 
-Persistent storage that survives browser refresh.
+Persistent storage that survives browser refresh. On Node.js/Deno this falls back to an in-memory `Map` that does **not** survive a process restart - treat it as a same-shape cache there, not durable storage.
 
 ```javascript
 // Set
@@ -89,15 +93,11 @@ store.list()  // { preferences: { theme: 'dark' } }
 
 // Remove
 store.remove('preferences')
-
-// Delete (alias for remove)
-store.delete('preferences')
+store.delete('preferences')  // alias
 
 // Clear all memorio items
 store.removeAll()
-
-// Clear all (alias for removeAll)
-store.clearAll()
+store.clearAll()  // alias
 
 // Check size
 console.debug(store.size(), 'chars stored')
@@ -105,13 +105,15 @@ console.debug(store.size(), 'chars stored')
 // Check if persistent (real localStorage vs memory fallback)
 console.debug(store.isPersistent)  // true → real localStorage
 
-// Estimate quota usage (returns [0, 0] for localStorage)
+// Estimate quota usage
 await store.quota()  // [usage, quota] in KB
 ```
 
-### `session` — sessionStorage
+> **`store.quota()` currently returns `[0, 0]` for the `localStorage` backend** - it is not a real usage reading for that backend, it's a placeholder. Don't use it to make capacity decisions until it's implemented for `localStorage`; it may be meaningful for other backends (e.g. `idb`), but confirm before relying on it there too.
+
+### `session` - sessionStorage
 
-Storage that dies when browser tab closes.
+Storage that dies when browser tab closes. Same Node.js/Deno `Map` fallback caveat as `store` applies here.
 
 ```javascript
 // Set
@@ -125,15 +127,11 @@ session.list()  // { token: 'user-abc-123' }
 
 // Remove
 session.remove('token')
-
-// Delete (alias for remove)
-session.delete('token')
+session.delete('token')  // alias
 
 // Clear all
 session.removeAll()
-
-// Clear all (alias for removeAll)
-session.clearAll()
+session.clearAll()  // alias
 
 // Check size
 console.debug(session.size(), 'chars stored')
@@ -142,7 +140,7 @@ console.debug(session.size(), 'chars stored')
 console.debug(session.isPersistent)
 ```
 
-### `cache` — In-Memory Cache
+### `cache` - In-Memory Cache
 
 Fastest possible read, data lost on refresh.
 
@@ -161,9 +159,7 @@ cache.remove('temp')
 
 // Clear all
 cache.clear()
-
-// Remove all (alias for clear)
-cache.removeAll()
+cache.removeAll()  // alias
 
 // Direct access (also works)
 cache['myKey'] = value
@@ -171,9 +167,9 @@ const value = cache['myKey']
 delete cache['myKey']
 ```
 
-### `idb` — IndexedDB
+### `idb` - IndexedDB
 
-Structured, persistent, async database (browser-only).
+Structured, persistent, async database (browser-only). **Disabled in Node.js/Deno** - calls will warn and no-op; use `store` or `session` there instead.
 
 ```javascript
 // Create database
@@ -200,24 +196,21 @@ const exists = await idb.db.exist('my-db')
 // Delete database
 await idb.db.delete('my-db')
 
-// Get database size
+// Get database / table size
 const size = await idb.db.size('my-db')
-
-// Get table size
 const tableSize = await idb.table.size('my-db', 'users')
 
-// Check support
-idb.db.support()  // true if IndexedDB available
-
-// Check quota
-const [usage, quota] = await idb.db.quota()
+// Check support before calling anything else
+if (idb.db.support()) {
+  const [usage, quota] = await idb.db.quota()
+}
 ```
 
-**Note:** In Node.js/Deno, `idb` is disabled with a warning. Use `store` or `session` instead.
+Always guard `idb` calls with `idb.db.support()` (or `memorio.getCapabilities().hasIndexedDB`) in code that might run outside a browser - don't rely on the no-op warning alone.
 
-### `observer` — Object Watcher
+### `observer` - Object Watcher
 
-Legacy observer API. Use `useObserver` instead.
+Legacy observer API. Prefer `useObserver` in React code.
 
 ```javascript
 // Listen to state changes
@@ -238,7 +231,9 @@ console.debug(observer.list)
 observer.removeAll()
 ```
 
-### `useObserver` — React Hook
+> Paths are plain strings and are not checked against `state`'s actual shape at compile time or at registration time. A typo or a later rename of the corresponding `state` key will fail silently - the observer simply never fires again.
+
+### `useObserver` - React Hook
 
 Primary way to observe state changes in React components.
 
@@ -266,67 +261,48 @@ function Counter() {
 
 **Features:**
 - Auto-discovery of state paths during render
-- Returns cleanup function to stop monitoring
+- Returns a cleanup function to stop monitoring
 - Supports both Proxy objects and string paths
 
-### `devtools` — Inspection Tools
+### `devtools` - Inspection Tools
 
-Inspect all memorio data in console.
+Browser-only (see [Cross-Platform Support](#cross-platform-support)); no-ops or unavailable in Node.js/Deno.
 
 ```javascript
-// Pretty-print state, store, session, cache
-memorio.devtools.inspect()
-
-// Get stats
-memorio.devtools.stats()  // { stateKeys, storeKeys, sessionKeys, ... }
-
-// Clear specific module
+memorio.devtools.inspect()      // pretty-print state, store, session, cache
+memorio.devtools.stats()        // { stateKeys, storeKeys, sessionKeys, ... }
 memorio.devtools.clear('state')
-
-// Clear all modules
 memorio.devtools.clearAll()
-
-// Export all data as JSON
 memorio.devtools.exportData()
-
-// Import data from JSON
 memorio.devtools.importData(jsonString)
-
-// Show help
 memorio.devtools.help()
 
 // Console shortcuts
-$state    // same as globalThis.state
-$store    // same as globalThis.store
-$session  // same as globalThis.session
-$cache    // same as globalThis.cache
+$state    // globalThis.state
+$store    // globalThis.store
+$session  // globalThis.session
+$cache    // globalThis.cache
 ```
 
-### `logger` — Change Tracking
+### `logger` - Change Tracking
 
-Track every state change with timestamps.
+Records every write it's configured to track, with timestamps - including whatever values you pass in.
 
 ```javascript
-// Configure logger
 memorio.logger.configure({
   enabled: true,
   logToConsole: true,
   modules: ['state', 'store', 'session', 'cache', 'idb']
 })
 
-// Get history
-memorio.logger.getHistory()  // [{ timestamp, module, action, path, value }, ...]
-
-// Get stats
-memorio.logger.getStats()    // { total, state, store, session, cache, idb, set, get, ... }
-
-// Clear history
+memorio.logger.getHistory()   // [{ timestamp, module, action, path, value }, ...]
+memorio.logger.getStats()     // { total, state, store, session, cache, idb, set, get, ... }
 memorio.logger.clearHistory()
-
-// Export logs
-memorio.logger.exportLogs()  // JSON string of all history
+memorio.logger.exportLogs()   // JSON string of all history
 ```
 
+> The `value` field in each history entry is whatever was written - tokens, PII, anything. Don't enable `logger` unconditionally in production paths that handle sensitive data, and don't wire `exportLogs()` output anywhere it could leak (analytics, error reporters, support tooling) without redaction.
+
 ## Platform Detection
 
 Access via `memorio.*` after `import 'memorio'`:
@@ -339,14 +315,10 @@ memorio.isEdge()          // true in Cloudflare Workers, Vercel Edge
 
 const caps = memorio.getCapabilities()
 // { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, sessionId: 'uuid', ... }
-
-// Create isolated context
-memorio.createContext('tenant-name')
-memorio.listContexts()
-memorio.deleteContext('context-id')
-memorio.isolate('tenant-name')  // alias for createContext
 ```
 
+Prefer checking `getCapabilities()` over assuming a platform from context - especially before calling `idb` or relying on `store`/`session` durability.
+
 ## Cross-Platform Support
 
 | Module | Browser | Node.js | Deno | Edge/Workers |
@@ -354,32 +326,135 @@ memorio.isolate('tenant-name')  // alias for createContext
 | `state` | ✅ | ✅ | ✅ | ✅ |
 | `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
 | `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ localStorage | ⚠️ memory | ⚠️ memory | ✅ localStorage |
-| `session` | ✅ sessionStorage | ⚠️ memory | ⚠️ memory | ✅ sessionStorage |
-| `idb` | ✅ IndexedDB | ❌ | ❌ | ⚠️ |
+| `store` | ✅ `localStorage` | ⚠️ `Map`, not durable | ⚠️ `Map`, not durable | ✅ `localStorage` where available, else `Map` |
+| `session` | ✅ `sessionStorage` | ⚠️ `Map`, not durable | ⚠️ `Map`, not durable | ✅ `sessionStorage` where available, else `Map` |
+| `idb` | ✅ `IndexedDB` | ❌ disabled | ❌ disabled | ⚠️ check `getCapabilities()` |
 | `devtools` | ✅ | ❌ | ❌ | ⚠️ |
 
-**Note:** `store` and `session` fall back to in-memory `Map` in Node.js/Deno.
+## Session & Context Isolation
 
-## Session Isolation
+By default, `state` is a **shared global namespace** - a value set in one place is visible everywhere else that reads `state` in the same process. There is no automatic per-tab or per-request isolation of `state` itself.
 
-Each browser tab and server request gets an isolated namespace automatically via session IDs.
+To isolate a slice of state (e.g. per tenant, per request), create an explicit context:
 
 ```javascript
-// Create isolated context
-memorio.createContext('tenant-name')
+const ctx = memorio.createContext('tenant-name')
+ctx.state.user = { name: 'Isolated' }
+
+console.debug(state.user) // undefined - separate namespace from ctx.state
+
 memorio.listContexts()
 memorio.deleteContext('context-id')
 memorio.isolate('tenant-name')  // alias for createContext
 ```
 
+Isolation is implemented as a **key-prefix convention** inside the same underlying storage, not a hard memory or process boundary. In a shared Node.js process or an edge isolate that may be reused across requests:
+
+- generate context IDs from trusted server-side data, never directly from client-controlled input, to prevent collisions or spoofing;
+- don't treat this as your only isolation layer for data that must not cross tenants - enforce that at the process/request level as well.
+
+`getCapabilities().sessionId` provides a per-session identifier for browser contexts but is not itself an isolation mechanism - use `createContext` for that.
+
+### `memorio.typed<T>()` - Typed Store (compile-time safety)
+
+Returns the global `state` proxy cast to type `T`. The same Proxy instance — no overhead. Use for TypeScript autocomplete and static type checking.
+
+```javascript
+const app = memorio.typed<AppState>()
+app.user = { name: 'Sara', age: 30 }  // type-checked
+app.user = { name: 42 }               // ❌ compile error
+```
+
+### `memorio.registerSchema()` - Schema Validation (runtime safety)
+
+Register validators for state paths. Writes that violate a schema are rejected before being stored.
+
+```javascript
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
+  }
+})
+
+state.user = { name: 'Sara' }  // rejected: missing 'email'
+state.user = { name: 'Sara', email: 'sara@test.com' }  // accepted
+```
+
+Custom validators:
+
+```javascript
+memorio.registerSchema('theme', (val) =>
+  val === 'light' || val === 'dark' ? true : 'must be light or dark'
+)
+```
+
+Manual validation and management:
+
+```javascript
+memorio.validate('user', value)     // { valid: true } or { valid: false, errors: [...] }
+memorio.listSchemas()               // ['user', 'theme']
+memorio.unregisterSchema('theme')   // removes validator
+```
+
+Combine `typed<T>()` + `registerSchema()` for both compile-time and runtime safety.
+
+### `memorio.snapshot()` / `memorio.diff()` - Time Travel
+
+```javascript
+memorio.enableHistory()
+
+const snap = memorio.snapshot()
+state.user.name = 'Luigi'
+state.counter = 100
+
+const changes = memorio.diff(snap)
+// [{ path: 'user.name', oldValue: 'Sara', newValue: 'Luigi' }, ...]
+
+memorio.rollback(snap)  // restore to snapshot
+```
+
+### `memorio.undo()` / `memorio.redo()` - Undo/Redo
+
+```javascript
+state.a = 1; state.b = 2; state.c = 3
+memorio.undo()   // removes state.c
+memorio.undo()   // removes state.b
+memorio.redo()   // restores state.b
+memorio.canUndo() // true
+memorio.canRedo() // true
+```
+
+### `memorio.trace()` - Mutation Log
+
+```javascript
+memorio.trace()
+// [{ path, action, newValue, previousValue, timestamp }, ...]
+memorio.clearHistory()
+```
+
+### `memorio.stateKeys()` / `memorio.pathExists()` / `memorio.stateSchema()` - Introspection
+
+```javascript
+memorio.stateKeys()      // ['user', 'counter']
+memorio.pathExists('user.name')  // true or false
+memorio.stateType('user.name')   // 'string'
+memorio.stateSchema()    // [{ path, type, defined }, ...] - full tree report
+```
+
+---
+
 ## Security
 
-- Zero production dependencies
-- NIST & NSA aligned security standards
-- No `eval`, no obfuscation, no hardcoded secrets
-- All inputs validated, keys sanitized
-- Secure random session IDs via `crypto.randomUUID`
+- Zero production dependencies.
+- No `eval`, no dynamic code execution, no obfuscation, no hardcoded secrets.
+- Inputs validated, keys sanitized before use.
+- Secure random session IDs via `crypto.randomUUID`.
+- Data in `store`, `session`, and `idb` is **not encrypted** - these are thin wrappers over browser storage APIs that persist data in the clear on the user's device. Add your own encryption layer before storing tokens, secrets, or regulated personal data there.
+
+Engineering practices are informed by recognized guidance (e.g. NIST SP 800-53 practices) as a design input - this is a statement about how the library is built, not a compliance certification, and no third-party audit has been performed. Report security issues privately (see `SECURITY.md`) rather than in a public issue.
 
 ## License
 
@@ -387,9 +462,9 @@ MIT © Dario Passariello (BigLogic Inc Canada)
 
 ## Utilities
 
-### `memorio.dispatch` — Event Dispatch System
+### `memorio.dispatch` - Event Dispatch System
 
-Internal event system used by state changes.
+Internal event system used by state changes; also usable directly for custom events.
 
 ```javascript
 // Dispatch a custom event

package/markdown/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-## v4.6.1 (Security Patch) - 2026-08-14 — CRITICAL Security Fix
+## v4.6.1 (Security Patch) - 2026-08-14 - CRITICAL Security Fix
 
 ### 🔐 Security NOTICE (v4.6.0)
 
@@ -32,7 +32,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 — Refactoring & Documentation
+## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 - Refactoring & Documentation
 
 **⚠️ WARNING**: This version had a hardcoded PAT token that was later remediated in v4.6.1**
 
@@ -75,7 +75,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v3.0.2 (Current) - 2026-05-19 — Bug Fix, Security & API Expansion
+## v3.0.2 (Current) - 2026-05-19 - Bug Fix, Security & API Expansion
 
 ### 🐛 Bug Fixes
 
@@ -98,9 +98,9 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 - Added JSDoc to `observerFunction` in `functions/observer/index.ts`
 - Added JSDoc to `cache` global in `functions/cache/index.ts`
-- `lint` and `tsc` pass clean — 0 vulnerabilities from `npm audit`
+- `lint` and `tsc` pass clean - 0 vulnerabilities from `npm audit`
 
-### 🆕 API — New in 3.0.2
+### 🆕 API - New in 3.0.2
 
 | Function | Description |
 |----------|-------------|
@@ -136,10 +136,10 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v2.9.0 — 2026-05-13
+## v2.9.0 - 2026-05-13
 
 ### Added
-- DevTools — `memorio.devtools.inspect()`, `stats()`, `exportData()`
+- DevTools - `memorio.devtools.inspect()`, `stats()`, `exportData()`
 - Logger with full history, stats and export
 - Platform detection (`isBrowser`, `isNode`, `isDeno`, `isEdge`, `getCapabilities`)
 - Session isolation via `crypto.randomUUID()`
@@ -154,7 +154,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v2.5.0 — 2026-02-17
+## v2.5.0 - 2026-02-17
 
 - Initial release of memorio (state, store, session, cache, idb)
 - Observer pattern (`observer`)