memorio 2.8.0 → 2.9.0

package/docs/markdown/OBSERVER.md

@@ -0,0 +1,180 @@
+# Observer - Memorio
+
+> ⚠️ **DEPRECATED**: This function is deprecated and will be removed in future versions. Please use [`useObserver`](USEOBSERVER.md) instead.
+
+Observer lets you react to state changes. When a state key changes, your callback function runs.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Simple observer (DEPRECATED - use useObserver instead)
+console.warn('observer() is deprecated. Please use useObserver() for React or memorio.dispatch for vanilla JS.');
+
+observer('state.counter', (newValue) => {
+  console.log('Counter is now:', newValue);
+});
+
+state.counter = 1;
+// Output: "Counter is now: 1"
+
+state.counter = 5;
+// Output: "Counter is now: 5"
+```
+
+> **Note**: For new projects, use [`useObserver`](USEOBSERVER.md) for React or [`memorio.dispatch`](SUMMARY.md) for vanilla JS.
+
+### Example 2: Intermediate
+
+```javascript
+// Observer with old value
+observer('state.user', (newValue, oldValue) => {
+  console.log(`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 observers
+const obs1 = observer('state.data', handler1);
+const obs2 = observer('state.data', handler2);
+
+// List all observers
+console.log(observer.list);
+// Output: [{ name: 'state.data', id: '...' }, ...]
+
+// Remove specific observer
+observer.remove('state.data');
+
+// Remove all observers
+observer.removeAll();
+```
+
+---
+
+## API Reference
+
+### observer(path, callback)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | State path to watch (e.g., `'state.counter'`) |
+| `callback` | `function` | Function called on change |
+
+### 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 |
+
+---
+
+## React Integration
+
+### With useState
+
+```javascript
+const [count, setCount] = useState(0);
+
+observer('state.counter', () => {
+  setCount(state.counter);
+});
+```
+
+### With useEffect
+
+```javascript
+useEffect(() => {
+  const handleChange = (newVal) => {
+    console.log('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/docs/markdown/PLATFORM.md

@@ -0,0 +1,260 @@
+# Platform & Context Isolation - Memorio
+
+> ℹ️ **New in v2.7.0**: 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';
+
+// Check current platform
+console.log(memorio.platform);   // 'browser' | 'node' | 'deno' | 'edge'
+console.log(memorio.isPersistent); // true if using real storage
+```
+
+### 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
+// 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
+// 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
+// Keys are prefixed with session ID
+// store: "memorio_store_[sessionId]_key"
+// session: "memorio_session_[sessionId]_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
+// Create isolated context for a user/session
+const ctx = memorio.createContext('user-123');
+
+// 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.log(state.user); // undefined - global state is separate
+```
+
+### Managing Contexts
+
+```javascript
+// List all contexts
+const contexts = memorio.listContexts();
+console.log(contexts); // ['user-123', 'user-456', ...]
+
+// Delete a context (cleanup)
+memorio.deleteContext('user-123');
+
+// Shorthand for createContext
+const ctx2 = memorio.isolate('tenant-A');
+```
+
+### 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.createContext(name?)` | `Context` | Create isolated context |
+| `memorio.listContexts()` | `string[]` | List all context IDs |
+| `memorio.deleteContext(id)` | `boolean` | Delete a context |
+| `memorio.isolate(name?)` | `Context` | Alias for createContext |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `memorio.version` | `string` | Memorio version |
+| `memorio.platform` | `string` | Current platform |
+| `memorio._sessionId` | `string` | Unique session identifier |