memorio 4.9.35 → 5.0.0

package/markdown/OBSERVER.md

@@ -0,0 +1,209 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **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,271 @@
+# 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 | Deno | Edge |
+|--------|--------|---------|------|------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
+| `devtools` | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## 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' | '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.isDeno()      // true in Deno
+memorio.isEdge()      // true in Edge Workers
+
+// Get capabilities
+const caps = memorio.getCapabilities();
+// caps.platform, caps.hasSessionStorage, caps.hasLocalStorage, 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'`.