memorio 4.9.35 → 5.1.0

package/markdown/OBSERVER.md

@@ -0,0 +1,208 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Observer - Memorio
+
+Observer lets you react to state changes. When a state key changes, your callback function runs.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { observer } from 'memorio';
+```
+
+> **Global API**: `import 'memorio/global'` is the opt-in entrypoint that also exposes `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+observer('state.counter', (newValue) => {
+  console.debug('Counter is now:', newValue);
+});
+
+state.counter = 1;
+// Output: "Counter is now: 1"
+
+state.counter = 5;
+// Output: "Counter is now: 5"
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Observer with old value
+observer('state.user', (newValue, oldValue) => {
+  console.debug(`User changed from ${oldValue?.name} to ${newValue?.name}`);
+});
+
+state.user = { name: 'Mario' };
+// Output: "User changed from undefined to Mario"
+
+state.user = { name: 'Luigi' };
+// Output: "User changed from Mario to Luigi"
+```
+
+### Example 3: Advanced
+
+```javascript
+// Multiple callbacks for same path
+observer('state.data', [handler1, handler2]);
+
+// List all observers
+console.debug(observer.list);
+// Output: [{ name: 'state.data', id: '...' }, ...]
+
+// Remove specific observer
+observer.remove('state.data');
+
+// Remove all observers
+observer.removeAll();
+
+// Check if observer exists
+if (observer.has('state.counter')) {
+  console.debug('Observer exists for counter');
+}
+```
+
+---
+
+## Direct Values (Vanilla JS)
+
+Observer supports direct state values, not just string paths:
+
+```javascript
+// Direct value - no string needed!
+observer(state.counter, (newValue) => {
+  console.debug('Counter:', newValue);
+});
+
+// Works with objects too
+observer(state.user, (newValue) => {
+  console.debug('User:', newValue?.name);
+});
+
+// Multiple callbacks as array
+observer('state.data', [cb1, cb2, cb3]);
+```
+
+---
+
+## API Reference
+
+### observer(path, callback, option)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string \| object` | State path (e.g., `'state.counter'`) or direct state value |
+| `callback` | `function \| array` | Function(s) called on change. Can be a single function or array of functions |
+| `option` | `boolean` | Listen continuously (default: `true`) |
+
+### Callback Parameters
+
+```javascript
+observer('state.key', (newValue, oldValue) => {
+  // newValue: the new value
+  // oldValue: the previous value
+});
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `observer.list` | `Array` | Get all active observers |
+
+### Methods
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `observer.remove(name)` | `string` | Remove observer for specific path |
+| `observer.removeAll()` | none | Remove all observers |
+| `observer.has(name)` | `string` | Check if observer exists for path (returns boolean) |
+
+---
+
+## React Integration
+
+### With useState
+
+```javascript
+const [count, setCount] = useState(0);
+
+observer('state.counter', () => {
+  setCount(state.counter);
+});
+```
+
+### With useEffect
+
+```javascript
+useEffect(() => {
+  const handleChange = (newVal) => {
+    console.debug('Changed:', newVal);
+  };
+
+  observer('state.data', handleChange);
+
+  // Cleanup
+  return () => observer.remove('state.data');
+}, []);
+```
+
+---
+
+## How It Works
+
+Observer subscribes to state changes via the Proxy's set trap. When `state.key = value` is called:
+1. The Proxy intercepts the set
+2. Fires all callbacks registered for that path
+3. Callbacks receive newValue and oldValue
+
+---
+
+## Best Practices
+
+1. Clean up observers in React `useEffect` return
+2. Use specific paths: `'state.user.name'` not `'state'`
+3. Remove observers when components unmount
+4. Use `observer.removeAll()` on page navigation
+
+---
+
+## Common Patterns
+
+### Form Validation
+
+```javascript
+observer('state.form.email', (email) => {
+  const isValid = email.includes('@');
+  state.form.isValid = isValid;
+});
+```
+
+### Analytics
+
+```javascript
+observer('state.page', (page) => {
+  analytics.track('page_view', { page });
+});
+```
+
+### Auto-save
+
+```javascript
+observer('state.draft', (content) => {
+  store.set('autosave', content);
+});
+```

package/markdown/PLATFORM.md

@@ -0,0 +1,277 @@
+# Platform & Context Isolation - Memorio
+
+> ℹ️ **New in v2.7.0, expanded in v3.0.2**: Context isolation system for multi-tenant server-side applications
+
+Memorio automatically detects the runtime environment and adapts its behavior accordingly. This document explains platform compatibility, session isolation, and the new context system.
+
+---
+
+## Quick Reference: Client vs Server
+
+### Which Module to Use?
+
+| Scenario | Recommended Module | Persistence |
+|----------|-------------------|-------------|
+| UI State (React/components) | `state` | Memory |
+| Temporary computed data | `cache` | Memory |
+| User preferences | `store` | Browser localStorage |
+| Auth tokens | `session` | Browser sessionStorage |
+| Large offline data | `idb` | IndexedDB |
+| Server request isolation | `memorio.createContext()` | Memory |
+
+### Module Availability
+
+| Module | Browser | Node.js | Bun | Deno | Edge |
+|--------|--------|---------|-----|------|------|
+| `state` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ✅* | ⚠️ (memory) | ✅ |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
+| `idb` | ✅ | ❌ | ❌ | ❌ | ⚠️ |
+| `sqlite` | ✅ (sql.js) | ❌ | ✅ (native `bun:sqlite`) | ❌ | ⚠️ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ |
+| `devtools` | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+*Bun: `store` uses `localStorage` when available (Bun 1.x+), falls back to memory otherwise.
+
+> ⚠️ **Bun row added from project notes, not verified against source for this document.** Confirm against `core/platform.ts` before publishing.
+
+---
+
+## Platform Detection
+
+Memorio automatically detects the environment on import:
+
+```javascript
+import { memorio, store } from 'memorio';
+
+// Check current platform
+console.debug(memorio.getCapabilities().platform); // 'browser' | 'node' | 'bun' | 'deno' | 'edge'
+console.debug(store.isPersistent); // true if using real localStorage
+```
+
+### Available Platform APIs
+
+```javascript
+// Check platform
+memorio.isBrowser()    // true in browser
+memorio.isNode()      // true in Node.js
+memorio.isBun()       // true in Bun
+memorio.isDeno()      // true in Deno
+memorio.isEdge()      // true in Edge Workers
+
+// Get capabilities
+const caps = memorio.getCapabilities();
+// caps.platform, caps.hasSessionStorage, caps.hasLocalStorage, caps.hasBunSqlite, etc.
+```
+
+---
+
+## Platform Compatibility Matrix
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|--------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ React only | ⚠️ React only | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+---
+
+## Client vs Server Usage
+
+### 🖥️ Client-Side (Browser)
+
+All features work with real browser storage:
+
+```javascript
+import { store, session, idb } from 'memorio'
+
+// Store - persistent localStorage
+store.set('preferences', { theme: 'dark' });
+store.isPersistent; // true
+
+// Session - temporary sessionStorage
+session.set('token', 'jwt-token');
+session.isPersistent; // true (survives refresh)
+
+// IDB - large data storage
+idb.db.create('myApp');
+```
+
+### 🖥️ Server-Side (Node.js/Deno)
+
+Use `state` and `cache` for in-memory data. Store/session fall back to memory:
+
+```javascript
+import { state, store, session, cache } from 'memorio'
+
+// State - in-memory global state
+state.user = { name: 'Server User' };
+
+// Cache - in-memory temporary cache
+cache.set('apiResponse', data);
+
+// Store - in-memory fallback (not persistent)
+store.set('temp', data);
+store.isPersistent; // false - data lost on restart
+
+// Session - in-memory fallback
+session.set('requestData', data);
+session.isPersistent; // false - data lost on restart
+```
+
+---
+
+## Session Isolation
+
+Each instance/session gets unique storage keys to prevent conflicts:
+
+```javascript
+// Without context: "memorio_store_[sessionId]_key"
+// With context: "[contextName]-key"
+```
+
+This ensures:
+- Multiple browser tabs don't share session data
+- Server-side requests are isolated
+
+---
+
+## Context Isolation (Server-Side Multi-Tenancy)
+
+> ⚠️ **Server-Side Only**: This feature is designed for multi-tenant server environments (Node.js, Deno). Not needed for client-side applications.
+
+For server-side applications handling multiple tenants (e.g., different users/requests), use **contexts** to isolate data:
+
+### Creating a Context
+
+```javascript
+import { memorio, state } from 'memorio'
+
+// Create isolated context for a user/session
+const ctx = memorio.isolate('user-123');
+
+// Keys in store/session are prefixed with context name
+// store: "user-123-key"
+// session: "user-123-key"
+
+// Use context's isolated storage
+ctx.state.user = { name: 'Isolated User' };
+ctx.store.set('settings', { theme: 'dark' });
+ctx.session.set('token', 'abc123');
+ctx.cache.set('temp', data);
+
+// Context is completely isolated from global state
+console.debug(state.user); // undefined - global state is separate
+```
+
+### Managing Contexts
+
+```javascript
+// List all contexts
+const contexts = memorio.listContexts();
+console.debug(contexts); // ['user-123', 'user-456', ...]
+
+// Delete a context (cleanup)
+memorio.deleteContext('user-123');
+```
+
+> **Note**: `memorio.isolate('name')` is a shorthand alias for creating isolated contexts.
+
+### Context Use Cases
+
+#### 1. Per-Request Isolation (Express/Fastify)
+
+```javascript
+// Middleware to isolate each request
+app.use((req, res, next) => {
+  const ctx = memorio.createContext(`req-${req.id}`);
+  req.memorioContext = ctx;
+  next();
+});
+
+// In route handler
+app.get('/user', (req, res) => {
+  const ctx = req.memorioContext;
+  ctx.state.user = getUserData();
+  // Each request has isolated state
+});
+```
+
+#### 2. Multi-Tenant SaaS
+
+```javascript
+// Each tenant gets isolated storage
+function handleTenant(tenantId) {
+  const ctx = memorio.createContext(tenantId);
+
+  ctx.state.config = getTenantConfig(tenantId);
+  ctx.store.set('data', tenantData);
+
+  return ctx;
+}
+```
+
+---
+
+## Best Practices
+
+### Client-Side (Browser)
+
+1. Use `store` for persistent data (preferences, user settings)
+2. Use `session` for temporary data (auth tokens)
+3. Use `cache` for computed values
+4. Use `state` for reactive UI state
+
+### Server-Side (Node.js/Deno)
+
+1. Use `memorio.createContext()` for each request/tenant
+2. Don't use global `state`/`store`/`session` across requests
+3. Use `cache` for request-scoped caching
+4. Check `store.isPersistent` / `session.isPersistent` if persistence matters
+
+### Edge Workers
+
+Same as browser - localStorage and sessionStorage are available.
+
+---
+
+## API Reference
+
+### Global Functions
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `memorio.isBrowser()` | `boolean` | Check if running in browser |
+| `memorio.isNode()` | `boolean` | Check if running in Node.js |
+| `memorio.isDeno()` | `boolean` | Check if running in Deno |
+| `memorio.isEdge()` | `boolean` | Check if running in Edge |
+| `memorio.getCapabilities()` | `object` | Get platform capabilities |
+
+### Context Management
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `memorio.isolate(name?)` | `Context` | Create isolated context |
+| `memorio.listContexts()` | `string[]` | List all context IDs |
+| `memorio.deleteContext(id)` | `boolean` | Delete a context |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `memorio.version` | `string` | Memorio version |
+| `memorio.getCapabilities().platform` | `string` | Current platform |
+| `memorio.isBrowser()` / `isNode()` / `isDeno()` / `isEdge()` | `boolean` | Platform checks |
+| `memorio._sessionId` | `string` | Unique session identifier |
+
+> **Classic `import`**: context APIs are also named exports.
+> `import { createContext, listContexts, deleteContext, isolate } from 'memorio'`.

package/markdown/REDUX.md

@@ -0,0 +1,54 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Redux and other state managers - Memorio
+
+> Skip this unless you already use Redux.
+
+> **Your state manager owns application state. Memorio owns memory.**
+
+```ts
+import { createMemorioReduxBridge } from 'memorio/redux'
+
+const memorioRedux = createMemorioReduxBridge<AppState>({
+  mappings: {
+    'user.preferences': {
+      selector: state => state.user.preferences,
+      type: 'preference',
+      scope: 'local',
+      tags: ['app', 'user']
+    },
+    'user.name': state => state.user.name
+  },
+  whitelist: ['user/preferencesChanged', 'user/nameChanged'],
+  debug: true
+})
+
+const store = createStore(reducer, applyMiddleware(memorioRedux.middleware))
+
+await memorioRedux.hydrate(store, {
+  onHydration(values) { store.dispatch(restorePreferences(values)) }
+})
+```
+
+```text
+Redux ─────────────→ memorio        memorio ───────────→ Redux
+application state    durable memory                     bootstrap hydration (one-shot)
+```
+
+The bridge persists only mapped selectors, never mirrors the full tree, coalesces bursts, and never breaks Redux dispatch if Memorio fails.
+
+| | Redux | Memorio |
+|---|---|---|
+| Core model | single store | independent runtime layers |
+| State changes | actions + reducers | direct reactive mutation |
+| Persistence | external integration | built in |
+| Structured memory | - | native |
+| Offline memory sync | - | supported |
+| Time-travel debugging | mature | State Intelligence (in progress) |
+| Production dependencies | ecosystem-dependent | zero in core |
+
+Use Redux when you need its action-pipeline discipline and ecosystem. Use Memorio when you want state, persistence, and structured memory under one runtime. You can use both.

package/markdown/SCHEMA.md

@@ -0,0 +1,175 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Schema Validation - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Schema validation guards your `state` against invalid writes. It runs inside the state proxy's `set` trap, so any `state.somePath = value` that violates a registered schema is rejected at runtime - before the value is ever stored.
+
+Schema validation is **opt-in** and **zero-dependency**.
+
+---
+
+## Quick Start
+
+```javascript
+import { memorio, state } from 'memorio'
+
+// Register a validator for a top-level state key
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+// Valid write - accepted
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }
+
+// Invalid write - rejected, returns false
+state.user = { name: 'Sara' }           // missing 'email'
+state.user = { name: 42, email: 'x' }   // wrong type for 'name'
+state.user = { age: -5 }                // out of range
+```
+
+---
+
+## Schema Definition
+
+A `Schema` object supports the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'string' \| 'number' \| 'boolean' \| 'object' \| 'array' \| 'any'` | Runtime type check |
+| `required` | `string[]` | Property names that must exist (objects only) |
+| `properties` | `Record<string, Schema>` | Nested property schemas (validated recursively) |
+| `min` | `number` | Number: minimum value. String: minimum length |
+| `max` | `number` | Number: maximum value. String: maximum length |
+| `pattern` | `RegExp` | Regex the string value must match |
+| `enum` | `any[]` | Whitelist of allowed values |
+| `validator` | `(value) => boolean \| string` | Custom validator function |
+
+### Custom validator functions
+
+For logic that's hard to express declaratively, pass a function instead of a schema object:
+
+```javascript
+memorio.registerSchema('counter', (value) => {
+  if (typeof value !== 'number') return 'counter must be a number'
+  if (value < 0) return 'counter must be >= 0'
+  return true
+})
+```
+
+A custom validator receives the raw value. Return `true` to accept, or a **string** describing the error to reject.
+
+---
+
+## Path-based registration
+
+Schemas are keyed by their **state path**, relative to `state`:
+
+| API call | Catches |
+|----------|---------|
+| `registerSchema('user', schema)` | `state.user = value` |
+| `registerSchema('user.age', schema)` | `state.user.age = value` |
+| `registerSchema('items', schema)` | `state.items = value` |
+
+The full dotted path is constructed from the proxy's tree depth. Nested sets propagate the full path automatically.
+
+---
+
+## Manual validation
+
+You can validate a value without writing it to state:
+
+```javascript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
+```
+
+When no schema is registered for a path, `validate` returns `{ valid: true }`.
+
+---
+
+## Schema management
+
+```javascript
+memorio.listSchemas()           // ['user', 'theme', 'items', 'counter']
+memorio.unregisterSchema('counter')  // removes the schema
+```
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.registerSchema(path, schema)` | `string`, `Schema \| fn` | `void` | Register a validator |
+| `memorio.validate(path, value)` | `string`, `any` | `{ valid, errors? }` | Manually validate a value |
+| `memorio.unregisterSchema(path)` | `string` | `boolean` | Remove a registered schema |
+| `memorio.listSchemas()` | none | `string[]` | List all registered paths |
+| `memorio.registerSchema()` is also importable | `registerSchema` | named export | same function |
+
+---
+
+## Combine with Typed Stores
+
+Schema validation gives you **runtime** safety; typed stores give you **compile-time** safety. Use both for full coverage:
+
+```typescript
+import { memorio, state } from 'memorio'
+
+interface AppState {
+  user: { name: string; email: string; age: number }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+app.user = { name: '', email: 'bad' }   // ❌ TypeScript: age missing
+                                         // ❌ Runtime: missing required fields
+app.user = { name: 'Sara', email: 'ok', age: 30 } // ✅ both checks pass
+```
+
+See [Typed Stores](TYPED.md) for compile-time type safety.
+
+---
+
+## How it works
+
+1. When you call `registerSchema(path, schema)`, the schema is stored in an internal `Map`.
+2. On every `state.set` operation, the proxy's `set` trap computes the full path (e.g. `'user.name'`).
+3. If a schema is registered for that path, the value is validated.
+4. If validation fails, the write is rejected (`return false`), and an error is logged via `console.error` (when `memorio.debug = true`) or `console.debug` (via the internal `message` helper).
+5. If no schema is registered, the write proceeds normally.
+
+The validation adds negligible overhead when no schemas are registered (a single `Map` lookup that returns `undefined`).
+
+---
+
+## Limitations
+
+- Schema validation hooks into the `state` proxy only. `store`, `session`, and `cache` are not validated (they use separate storage). Use `validate()` before writing to other modules.
+- Path matching is **exact**: `registerSchema('user')` guards `state.user = ...`, but does **not** recursively validate `state.user.name = 'new'`. Register schemas at each path you need to guard.
+- The schema system is not a replacement for server-side validation. It protects against accidental misuse and provides defense-in-depth in the browser.