memorio 2.5.1 → 2.5.3

package/docs/CACHE.md

@@ -0,0 +1,77 @@
+# Cache - Memorio
+
+Cache provides in-memory storage with a simple API. Data is lost on page refresh.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+cache.set('username', 'Mario');
+cache.set('score', 1500);
+
+// Read data
+console.log(cache.get('username')); // "Mario"
+console.log(cache.get('score'));    // 1500
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+cache.set('user', { name: 'Luigi', level: 5 });
+const user = cache.get('user');
+console.log(user.name); // "Luigi"
+
+// Remove single item
+cache.remove('username');
+
+// Clear all cache
+cache.removeAll();
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `cache.get(name)` | `name: string` | `any` | Get value from cache |
+| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
+| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
+
+---
+
+## Storage Comparison
+
+| Feature | Cache | Store | Session | IDB |
+|---------|-------|-------|---------|-----|
+| Storage | Memory | localStorage | sessionStorage | IndexedDB |
+| Lifetime | Until refresh | Forever | Until tab closes | Forever |
+| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
+| Use case | Temporary data | User preferences | Auth tokens | Large data |
+
+---
+
+## Best Practices
+
+1. Use for temporary data that doesn't need persistence
+2. Great for computed values or API response caching
+3. Data is lost on page refresh - don't use for important data
+4. Clear with `cache.removeAll()` when no longer needed

package/docs/DEVTOOLS.md

@@ -0,0 +1,120 @@
+# Memorio DevTools
+
+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.log(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/docs/IDB.md

@@ -0,0 +1,156 @@
+# IDB - Memorio
+
+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.log(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.log(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.log(`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'
+});
+```
+
+---
+
+## 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/docs/LOGGER.md

@@ -0,0 +1,145 @@
+# Memorio Logger
+
+Automatic logging middleware for tracking all state changes in Memorio.
+
+## Overview
+
+The logger automatically tracks all operations (set, delete, clear) across all modules:
+- State
+- Store
+- Session
+- Cache
+
+## Configuration
+
+### configure(options)
+
+Configure the logger.
+
+```javascript
+memorio.logger.configure({
+  enabled: true,           // Enable/disable logging
+  logToConsole: true,     // Log to browser console
+  customHandler: function(entry) { ... }, // Custom handler
+  modules: ['state', 'store', 'session', 'cache'], // Modules to log
+  maxEntries: 1000        // Maximum log history size
+})
+```
+
+### enable()
+
+Enable logging.
+
+```javascript
+memorio.logger.enable()
+```
+
+### disable()
+
+Disable logging.
+
+```javascript
+memorio.logger.disable()
+```
+
+## Methods
+
+### getHistory()
+
+Get all log entries.
+
+```javascript
+const history = memorio.logger.getHistory()
+// Returns array of LogEntry objects
+```
+
+### getStats()
+
+Get statistics about logged operations.
+
+```javascript
+const stats = memorio.logger.getStats()
+// Returns: { total, state, store, session, cache, set, get, delete, clear }
+```
+
+### clearHistory()
+
+Clear log history.
+
+```javascript
+memorio.logger.clearHistory()
+```
+
+### exportLogs()
+
+Export logs as JSON string.
+
+```javascript
+const json = memorio.logger.exportLogs()
+```
+
+## Log Entry Structure
+
+```javascript
+{
+  timestamp: "2026-02-18T12:00:00.000Z",
+  module: "state",
+  action: "set",
+  path: "user.name",
+  value: "John",
+  previousValue: "Jane"
+}
+```
+
+## Examples
+
+### Basic usage
+
+```javascript
+// Logging is enabled by default
+state.user = { name: 'John' }
+// Console: [Memorio:STATE] set user → value: { name: 'John' }
+```
+
+### Get statistics
+
+```javascript
+const stats = memorio.logger.getStats()
+console.log(stats)
+// { total: 15, state: 5, store: 3, session: 2, cache: 5, set: 10, get: 0, delete: 3, clear: 2 }
+```
+
+### Disable specific modules
+
+```javascript
+memorio.logger.configure({
+  modules: ['state'] // Only log state changes
+})
+```
+
+### Custom handler
+
+```javascript
+memorio.logger.configure({
+  customHandler: (entry) => {
+    // Send to analytics
+    analytics.track('memorio_change', entry)
+  }
+})
+```
+
+### Export and analyze
+
+```javascript
+// Get all logs
+const logs = memorio.logger.getHistory()
+
+// Filter by module
+const stateLogs = logs.filter(l => l.module === 'state')
+
+// Filter by action
+const setOperations = logs.filter(l => l.action === 'set')
+
+// Export for debugging
+console.log(memorio.logger.exportLogs())
+```

package/docs/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);
+});
+```