memorio 4.6.8 → 4.7.0

package/markdown/DEVTOOLS.md

@@ -0,0 +1,122 @@
+# Memorio DevTools
+
+> 🖥️ **Browser Only**: This feature is only available in browser console
+
+Browser console debugging tools for inspecting and managing Memorio state.
+
+## Quick Start
+
+```javascript
+// Load memorio first
+import 'memorio'
+```
+
+## Available Methods
+
+### inspect()
+
+Inspect all Memorio modules in the console.
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### stats()
+
+Get statistics about all modules.
+
+```javascript
+memorio.devtools.stats()
+// Returns: { stateKeys, storeKeys, sessionKeys, cacheKeys, idbDatabases, lastUpdate }
+```
+
+### clear(module)
+
+Clear data from a specific module.
+
+```javascript
+memorio.devtools.clear('state')
+memorio.devtools.clear('store')
+memorio.devtools.clear('session')
+memorio.devtools.clear('cache')
+```
+
+### clearAll()
+
+Clear all Memorio data.
+
+```javascript
+memorio.devtools.clearAll()
+```
+
+### watch(module, path)
+
+Watch a specific path for changes.
+
+```javascript
+memorio.devtools.watch('state', 'user.name')
+```
+
+### exportData()
+
+Export all data as JSON.
+
+```javascript
+const json = memorio.devtools.exportData()
+console.debug(json)
+```
+
+### importData(jsonString)
+
+Import data from JSON.
+
+```javascript
+memorio.devtools.importData('{"state":{"key":"value"}}')
+```
+
+### help()
+
+Show help information.
+
+```javascript
+memorio.devtools.help()
+```
+
+## Console Shortcuts
+
+Memorio provides global shortcuts for quick access:
+
+```javascript
+$state    // globalThis.state
+$store    // globalThis.store
+$session  // globalThis.session
+$cache    // globalThis.cache
+```
+
+## Examples
+
+### Inspect current state
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### Export and restore state
+
+```javascript
+// Export
+const backup = memorio.devtools.exportData()
+
+// Later... import
+memorio.devtools.importData(backup)
+```
+
+### Monitor changes
+
+```javascript
+// Watch a specific path
+memorio.devtools.watch('state', 'counter')
+
+// Now changes will be logged to console
+state.counter = 42 // Console shows: 👁 Change: state.counter = 42
+```

package/markdown/DISPATCH.md

@@ -0,0 +1,168 @@
+# 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/IDB.md

@@ -0,0 +1,169 @@
+# 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

@@ -0,0 +1,139 @@
+# 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.