memorio 4.8.0 → 4.9.5

package/markdown/DISPATCH.md

@@ -1,168 +0,0 @@
-# Dispatch - Memorio
-
-> ⚛️ **Vanilla JS**: This is for non-React applications. For React, use [`useObserver`](USEOBSERVER.md).
-
-`memorio.dispatch` is an event system for vanilla JavaScript applications. It enables pub/sub patterns without React hooks.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import 'memorio';
-```
-
----
-
-## Quick Examples
-
-### Example 1: Basic Event Listening
-
-```javascript
-// Listen for an event
-memorio.dispatch.listen('my:event', (event) => {
-  console.debug('Event triggered:', event.detail);
-});
-
-// Trigger the event
-memorio.dispatch.set('my:event', { detail: { data: 'Hello World' } });
-// Output: "Event triggered: { data: 'Hello World' }"
-```
-
-### Example 2: State Reactivity (Vanilla JS)
-
-```javascript
-// React to state changes without React
-memorio.dispatch.listen('state.counter', (event) => {
-  console.debug('Counter is now:', event.detail);
-});
-
-// Update state
-state.counter = 1;
-// Output: "Counter is now: 1"
-
-state.counter = 5;
-// Output: "Counter is now: 5"
-```
-
-### Example 3: Remove Listener
-
-```javascript
-// Remove a specific event listener
-memorio.dispatch.remove('my:event');
-
-// Or remove all listeners for state changes
-memorio.dispatch.remove('state.user');
-```
-
----
-
-## API Reference
-
-### memorio.dispatch.set(name, value)
-
-Dispatches a custom event with the specified name and value.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Event name (e.g., `'my:event'`, `'state.counter'`) |
-| `value` | `object` | Object with `detail` property (default: `{}`) |
-
-```javascript
-memorio.dispatch.set('custom:event', { detail: { data: 'value' } });
-```
-
-### memorio.dispatch.listen(name, callback)
-
-Listens for the specified event and executes the callback when triggered.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Event name to listen for |
-| `callback` | `function` | Function called with the event object |
-
-```javascript
-memorio.dispatch.listen('state.user', (event) => {
-  console.debug('User changed:', event.detail);
-});
-```
-
-### memorio.dispatch.remove(name)
-
-Removes the event listener for the specified event name.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Event name to stop listening |
-
-```javascript
-memorio.dispatch.remove('state.counter');
-```
-
----
-
-## Common Patterns
-
-### Form Validation
-
-```javascript
-memorio.dispatch.listen('state.form.email', (event) => {
-  const email = event.detail;
-  const isValid = email.includes('@');
-  state.form.isValid = isValid;
-});
-```
-
-### Analytics Tracking
-
-```javascript
-memorio.dispatch.listen('state.page', (event) => {
-  const page = event.detail;
-  analytics.track('page_view', { page });
-});
-```
-
-### Auto-save
-
-```javascript
-memorio.dispatch.listen('state.draft', (event) => {
-  const content = event.detail;
-  store.set('autosave', content);
-});
-```
-
-### Multiple Listeners
-
-```javascript
-// Listen for multiple state changes
-memorio.dispatch.listen('state.user', (e) => console.log('User:', e.detail));
-memorio.dispatch.listen('state.settings', (e) => console.log('Settings:', e.detail));
-```
-
----
-
-## Migration from observer()
-
-The `observer()` Replace it with `memorio.dispatch.listen()`:
-
-```javascript
-observer('state.counter', (newValue) => {
-  console.debug('Counter:', newValue);
-});
-
-// NEW (recommended for vanilla JS)
-memorio.dispatch.listen('state.counter', (event) => {
-  console.debug('Counter:', event.detail);
-});
-```
-
----
-
-## Best Practices
-
-1. Use specific event names: `'state.user.name'` not `'state'`
-2. Clean up listeners when no longer needed with `memorio.dispatch.remove()`
-3. Use `event.detail` to access the value
-4. For React applications, use [`useObserver`](USEOBSERVER.md) instead

package/markdown/HISTORY.md

@@ -1,192 +0,0 @@
-# History, Undo / Redo, Snapshot, Diff, Trace - Memorio
-
-> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
-
-Memorio provides a lightweight time-travel system for `state` mutations: snapshots, diffs, undo/redo, and a full mutation trace log.
-
-History tracking is **opt-in** — it is disabled by default to avoid overhead. Enable it when you need undo/redo or trace capabilities.
-
----
-
-## Enable History
-
-```javascript
-import 'memorio'
-
-memorio.enableHistory()    // enable tracking
-// ... mutate state ...
-memorio.state.user = { name: 'Sara' }
-memorio.state.counter = 42
-```
-
-> Without `enableHistory()`, mutations are not recorded and `undo()`/`redo()`/`trace()` return empty results.
-
----
-
-## Snapshot & Diff
-
-Snapshot captures the entire `state` tree at a point in time. Diff compares a snapshot against current state to see what changed.
-
-```javascript
-// Enable history (snapshots work regardless, but trace/undo need it)
-memorio.enableHistory()
-
-// Take a snapshot
-state.user = { name: 'Sara', age: 30 }
-const snap = memorio.snapshot()
-
-// Make changes
-state.user.name = 'Luigi'
-state.counter = 100
-state.items = ['a', 'b']
-
-// Diff against the snapshot
-const changes = memorio.diff(snap)
-console.debug(changes)
-// [
-//   { path: 'user.name', oldValue: 'Sara', newValue: 'Luigi' },
-//   { path: 'counter',   oldValue: undefined, newValue: 100 },
-//   { path: 'items',     oldValue: undefined, newValue: ['a', 'b'] }
-// ]
-```
-
-This is essential for AI agents: take a snapshot, make changes, inspect the diff, and decide whether to commit or rollback.
-
----
-
-## Undo / Redo
-
-```javascript
-state.user = { name: 'Sara' }
-state.counter = 100
-state.items = ['a', 'b']
-
-memorio.undo()   // removes state.items
-memorio.undo()   // counter → undefined
-memorio.redo()   // counter → 100 again
-
-memorio.canUndo()  // true
-memorio.canRedo()  // true (after above undo + redo cycle)
-```
-
-- `undo()`: Restores the previous state by inverting the most recent mutation.
-- `redo()`: Re-applies the most recently undone mutation.
-- `canUndo()` / `canRedo()`: Check availability before calling.
-
-### Max history depth
-
-```javascript
-memorio.setMaxHistory(50)   // keep at most 50 mutations per stack (default: 100)
-```
-
----
-
-## Rollback (full state restore)
-
-Unlike undo (which works one step at a time), `rollback` replaces the entire state from a snapshot:
-
-```javascript
-const snap = memorio.snapshot()
-
-state.experiment = { result: 'failed' }
-state.counter = 999
-
-// Discard everything and restore to snapshot
-memorio.rollback(snap)
-// state.experiment is now gone
-// state.counter is back to its snapshot value
-```
-
----
-
-## Trace (mutation log)
-
-The trace log records every mutation with timestamp, path, action, and before/after values:
-
-```javascript
-memorio.enableHistory()
-
-state.user.name = 'Sara'
-state.counter = 1
-state.counter = 2
-
-const log = memorio.trace()
-console.debug(log)
-// [
-//   { path: 'user.name', action: 'set', newValue: 'Sara', previousValue: undefined, timestamp: 1725... },
-//   { path: 'counter',   action: 'set', newValue: 1,      previousValue: undefined, timestamp: 1725... },
-//   { path: 'counter',   action: 'set', newValue: 2,      previousValue: 1,         timestamp: 1725... }
-// ]
-```
-
-This is useful for:
-- **AI debugging**: inspect what changed and when
-- **Event sourcing**: export the log and replay state from scratch
-- **Audit trails**: log all mutations for compliance
-
-### Export / import trace
-
-```javascript
-const log = memorio.trace()
-localStorage.setItem('memorio-trace', JSON.stringify(log))
-
-// Later, replay:
-const saved = JSON.parse(localStorage.getItem('memorio-trace'))
-for (const record of saved) {
-  if (record.action === 'set') {
-    state[record.path] = record.newValue
-  }
-}
-```
-
----
-
-## Clear History
-
-```javascript
-memorio.clearHistory()   // wipe undo/redo stacks + trace log
-memorio.clearRedo()      // clear only the redo stack (undo stack preserved)
-```
-
-> `clearHistory()` does NOT reset the current `state` — only the history tracking data.
-
----
-
-## Full API
-
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `memorio.snapshot()` | none | `Record<string, any>` | Deep clone of current state |
-| `memorio.diff(snap)` | `snap` | `DiffEntry[]` | Changed paths with old/new values |
-| `memorio.undo()` | none | `MutationRecord \| undefined` | Undo last mutation |
-| `memorio.redo()` | none | `MutationRecord \| undefined` | Redo last undone mutation |
-| `memorio.canUndo()` | none | `boolean` | Whether undo is available |
-| `memorio.canRedo()` | none | `boolean` | Whether redo is available |
-| `memorio.rollback(snap)` | `snap` | `void` | Restore full state from snapshot |
-| `memorio.trace()` | none | `MutationRecord[]` | List of all recorded mutations |
-| `memorio.enableHistory(enabled?)` | `boolean` | `void` | Enable/disable tracking |
-| `memorio.clearHistory()` | none | `void` | Clear all history stacks |
-| `memorio.clearRedo()` | none | `void` | Clear only redo stack |
-| `memorio.setMaxHistory(max)` | `number` | `void` | Set max stack depth |
-| `memorio.getMaxHistory()` | none | `number` | Get current max depth |
-
----
-
-## How It Works
-
-1. When `historyEnabled` is true, the state proxy's callback (`buildProxy` callback) fires on every `set`/`delete` trap, recording a `MutationRecord` with path, action, oldValue, newValue, and timestamp.
-2. Records are pushed to both a trace log (`mutations`) and an undo stack.
-3. Any new mutation clears the redo stack.
-4. `undo()` pops from the undo stack, pushes to the redo stack, and applies the inverse operation (restoring the previous value, or deleting if it was new).
-5. `redo()` pops from the redo stack, pushes back to the undo stack, and re-applies the original mutation.
-6. During undo/redo, history tracking is temporarily disabled to prevent recursive recording.
-7. `diff()` does a recursive key-by-key comparison between the snapshot and current `deepRaw(state)`.
-
----
-
-## Best Practices
-
-1. **Always snapshot before AI experimentation** — `const snap = memorio.snapshot()` gives you a safe rollback point.
-2. **Call `diff()` before `rollback()`** — inspect what changed first; sometimes you only need to revert one key.
-3. **Keep `maxHistory` reasonable** — the default (100) is fine for most apps. Lower it for memory-constrained environments.
-4. **Don't rely on trace for sensitive data** — the trace log records *all* values written, including tokens/PII. Clear it or disable tracing in production paths.

package/markdown/IDB.md

@@ -1,169 +0,0 @@
-# IDB - Memorio
-
-> 🖥️ **Browser Only**: Requires IndexedDB (not available in Node.js/Deno)
-
-IDB provides access to browser IndexedDB for large data storage. Unlike localStorage, IDB can store large amounts of structured data.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import 'memorio';
-```
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-// Create a database
-idb.db.create('myApp');
-
-// Add data
-idb.data.set('myApp', 'users', { id: 1, name: 'Mario' });
-
-// Get data
-const user = idb.data.get('myApp', 'users', 1);
-console.debug(user.name); // "Mario"
-```
-
-### Example 2: Intermediate
-
-```javascript
-// Create database with tables
-idb.db.create('store');
-idb.table.create('store', 'products');
-
-// Add multiple records
-idb.data.set('store', 'products', { id: 1, name: 'Apple', price: 1.5 });
-idb.data.set('store', 'products', { id: 2, name: 'Banana', price: 0.8 });
-
-// List databases
-const databases = idb.db.list();
-console.debug(databases); // ['myApp', 'store']
-```
-
-### Example 3: Advanced
-
-```javascript
-// Check database support
-if (idb.db.support()) {
-  // Use IDB
-}
-
-// Get database info
-const version = idb.db.version('store');
-const size = idb.db.size('store');
-
-// Delete database
-idb.db.delete('store');
-
-// Handle quota
-const quota = idb.db.quota();
-console.debug(`Using ${quota.used} of ${quota.total} bytes`);
-```
-
----
-
-## API Reference
-
-### Database Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `idb.db.create(name)` | `name: string` | `void` | Create database |
-| `idb.db.delete(name)` | `name: string` | `void` | Delete database |
-| `idb.db.list()` | none | `string[]` | List all databases |
-| `idb.db.exist(name)` | `name: string` | `boolean` | Check if exists |
-| `idb.db.size(name)` | `name: string` | `number` | Get database size |
-| `idb.db.version(name)` | `name: string` | `number` | Get version |
-| `idb.db.support()` | none | `boolean` | Check browser support |
-| `idb.db.quota()` | none | `object` | Get storage quota |
-
-### Table Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `idb.table.create(db, table)` | `db: string, table: string` | `void` | Create table |
-| `idb.table.size(db, table)` | `db: string, table: string` | `number` | Get table size |
-
-### Data Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `idb.data.get(db, table, id)` | `db, table, id` | `any` | Get single record |
-| `idb.data.set(db, table, data)` | `db, table, data` | `void` | Set record |
-| `idb.data.delete(db, table, id)` | `db, table, id` | `void` | Delete record |
-
----
-
-## Data Structure
-
-Each record needs an `id` field:
-
-```javascript
-idb.data.set('myDB', 'users', {
-  id: 1,           // Required!
-  name: 'Mario',
-  email: 'm@test.com'
-});
-```
-
----
-
-## Platform Support
-
-| Platform | Support | Notes |
-|----------|---------|-------|
-| Browser | ✅ Full | Full IndexedDB support |
-| Edge Worker | ⚠️ Limited | May not be available in all workers |
-| Node.js | ❌ Not available | Use store or session instead |
-| Deno | ❌ Not available | Use store or session instead |
-
----
-
-## Storage Limits
-
-- **Desktop browsers**: 50+ MB (often unlimited)
-- **Mobile browsers**: 50-100 MB
-- **More than localStorage**: Much higher limits
-
----
-
-## Best Practices
-
-1. Always include `id` in records
-2. Use for large data: images, caches, offline data
-3. Check support: `idb.db.support()`
-4. Clean up: `idb.db.delete('tempDB')`
-
----
-
-## Use Cases
-
-### Offline Data
-
-```javascript
-// Cache API response
-idb.data.set('cache', 'apiResponse', {
-  id: 'users',
-  data: usersArray,
-  timestamp: Date.now()
-});
-```
-
-### Large User Data
-
-```javascript
-// Store user-generated content
-idb.data.set('app', 'uploads', {
-  id: Date.now(),
-  file: fileData,
-  userId: currentUser.id
-});
-```

package/markdown/IMPORT.md

@@ -1,139 +0,0 @@
-# Classic `import` support
-
-Memorio supports two equivalent styles: the original global side-effect import,
-and the new named exports. Both share the same instances (one source of truth).
-
-```typescript
-// Global style (original)
-import 'memorio'
-state.user = { name: 'Sara' }
-
-// Classic import style (new)
-import { state } from 'memorio'
-state.user = { name: 'Sara' }
-```
-
-`state` in both examples is the exact same Proxy object.
-
----
-
-## Why two styles?
-
-| Style | When to use |
-|-------|-------------|
-| `import 'memorio'` | Zero-config, global access everywhere, legacy scripts |
-| `import { state } from 'memorio'` | Explicit dependencies, tree-shakeable bundles, TypeScript IntelliSense |
-
----
-
-## ESM named imports
-
-All modules are available as named exports:
-
-```typescript
-import {
-  state,
-  store,
-  session,
-  cache,
-  idb,
-  observer,
-  useObserver,
-  dispatch,
-  message,
-  devtools,
-  logger
-} from 'memorio'
-```
-
-Platform helpers:
-
-```typescript
-import {
-  isBrowser,
-  isNode,
-  isDeno,
-  isEdge,
-  getCapabilities,
-  createContext,
-  listContexts,
-  deleteContext
-} from 'memorio'
-```
-
-Internal utilities (for tests/debug):
-
-```typescript
-import internal, { propertyName } from 'memorio'
-import { setContext, getContext } from 'memorio'
-```
-
-Default export (the public `memorio` namespace):
-
-```typescript
-import memorio from 'memorio'
-memorio.help()
-```
-
----
-
-## CJS usage
-
-```javascript
-const { state, store, memorio } = require('memorio')
-```
-
----
-
-## React / useObserver
-
-`useObserver` works the same way via named import:
-
-```tsx
-import { useObserver, state } from 'memorio'
-
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-
-  useObserver(forceUpdate, [state.counter])
-
-  return <div>Count: {state.counter}</div>
-}
-```
-
----
-
-## Context isolation
-
-```typescript
-import { createContext, listContexts, deleteContext, isolate } from 'memorio'
-
-const ctx = createContext('tenant-123')
-ctx.state.user = { name: 'Isolated' }
-ctx.store.set('settings', { theme: 'dark' })
-
-listContexts() // ['tenant-123']
-deleteContext('tenant-123')
-```
-
----
-
-## Same-instance guarantee
-
-Named exports point to the same instances published on `globalThis` by
-`core/global` at bootstrap. Mutating via named export mutates the global,
-and vice versa.
-
-```typescript
-import { state } from 'memorio'
-
-state.importedFlag = true
-console.debug(globalThis.state.importedFlag) // true
-```
-
----
-
-## Migration from global-only
-
-No code changes required. Existing `import 'memorio'` + `state.foo = 1`
-continues to work unchanged. Named exports are additive.