memorio 2.8.0 → 2.9.1

package/docs/markdown/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Changelog - Memorio
+
+All notable changes to this project will be documented in this file.
+
+---
+
+## v2.7.0 (Current) - Cross-Platform & Security Update
+
+### 🚀 New Features
+
+#### 1. Platform Compatibility Layer
+- **Auto-detection**: Automatically detects Browser, Node.js, Deno, Edge Workers
+- **Polyfills**: Automatic fallback for server environments
+- **New exports**:
+  - `memorio.isBrowser()` - Check if running in browser
+  - `memorio.isNode()` - Check if running in Node.js
+  - `memorio.isDeno()` - Check if running in Deno
+  - `memorio.isEdge()` - Check if running in Edge Worker
+  - `memorio.getCapabilities()` - Get platform capabilities
+
+#### 2. Session Isolation
+- **Unique Session IDs**: Each import/session gets unique ID via `crypto.randomUUID()`
+- **Namespaced Storage**: Keys prefixed with session ID to prevent cross-contamination
+- **Format**: `memorio_store_[session-uuid]_keyname`
+
+#### 3. Context Isolation (Multi-Tenant Support)
+- **New API**:
+  - `memorio.createContext(name?)` - Create isolated context
+  - `memorio.listContexts()` - List all contexts
+  - `memorio.deleteContext(id)` - Delete context
+  - `memorio.isolate(name?)` - Alias for createContext
+
+#### 4. Persistence Detection
+- **New Properties**:
+  - `store.isPersistent` - Check if using real localStorage
+  - `session.isPersistent` - Check if using real sessionStorage
+
+### 🔒 Security Improvements
+
+| Feature | Before v2.7.0 | After v2.7.0 |
+|---------|---------------|--------------|
+| Session ID | `Math.random()` | `crypto.randomUUID()` |
+| Key Validation | None | Max 512 chars + whitelist |
+| Server Isolation | None | Context system |
+| Fallback Security | Basic | `crypto.getRandomValues()` |
+
+### 📝 Documentation Updates
+
+- **New Documents**:
+  - [`PLATFORM.md`](PLATFORM.md) - Platform compatibility guide
+  - [`SECURITY.md`](SECURITY.md) - Security documentation
+
+- **Updated Documents**:
+  - All module docs now have platform labels (✅ Universal, 🖥️ Browser, ⚛️ React)
+  - Platform comparison tables added
+  - Client vs Server usage clarified
+
+### 🔧 Examples
+
+- **New Examples**:
+  - [`examples/platform.ts`](../examples/platform.ts) - Platform detection + Context demo
+
+- **Updated Examples**:
+  - [`examples/basic.ts`](../examples/basic.ts) - Platform detection added
+  - [`examples/store-advanced.ts`](../examples/store-advanced.ts) - isPersistent check
+  - [`examples/session-advanced.ts`](../examples/session-advanced.ts) - isPersistent check
+
+### ⚠️ Breaking Changes
+
+| Change | Impact | Migration |
+|--------|--------|-----------|
+| Key validation | Low | Invalid keys now rejected with debug message |
+| Storage key format | Low | Keys now prefixed with session ID |
+
+### 🏗️ Internal Changes
+
+- **New files**:
+  - `config/platform.ts` - Platform detection + Context system
+
+- **Modified files**:
+  - `config/global.ts` - Added context exports
+  - `functions/store/index.ts` - Added validation + isPersistent
+  - `functions/session/index.ts` - Added validation + isPersistent
+
+---
+
+## v2.6.x - Previous Versions
+
+*(Documentation for versions prior to v2.7.0 is not included in this changelog)*
+
+### Typical v2.6.x Features:
+- State management with Proxy
+- Observer pattern
+- useObserver React hook
+- Store (localStorage wrapper)
+- Session (sessionStorage wrapper)
+- Cache (in-memory)
+- IDB (IndexedDB wrapper)
+- DevTools
+- Logger
+
+---
+
+## Migration Guide: v2.6.x → v2.7.0
+
+### 1. Platform Detection (Optional)
+
+```typescript
+// NEW: Check platform
+if (memorio.isNode()) {
+  console.log('Running on server')
+}
+```
+
+### 2. Persistence Check (Optional)
+
+```typescript
+// NEW: Check if data persists
+if (!store.isPersistent) {
+  console.warn('Data will be lost on restart!')
+}
+```
+
+### 3. Server-Side Isolation (Recommended for Node.js)
+
+```typescript
+// NEW: Create isolated context per request
+app.use((req, res, next) => {
+  req.ctx = memorio.createContext(`req-${req.id}`)
+  next()
+})
+
+app.get('/data', (req, res) => {
+  req.ctx.state.user = getUser()
+  // Each request has isolated state
+})
+```
+
+### 4. Key Validation (Automatic)
+
+```typescript
+// Keys are now validated - invalid keys rejected
+store.set('valid-key', 'value')     // ✅ Works
+store.set('key with spaces', 'x')    // ❌ Rejected (debug message)
+store.set('key>1000chars', 'x')     // ❌ Rejected if >512 chars
+```
+
+---
+
+## Comparison Table: v2.6.x vs v2.7.0
+
+| Feature | v2.6.x | v2.7.0 |
+|---------|--------|--------|
+| **Platform Support** | | |
+| Browser | ✅ | ✅ |
+| Node.js | ⚠️ Partial | ✅ Full |
+| Deno | ❌ | ✅ Full |
+| Edge Workers | ❌ | ✅ |
+| **Security** | | |
+| Secure Random | ❌ | ✅ |
+| Key Validation | ❌ | ✅ |
+| Session Isolation | ❌ | ✅ |
+| Context Isolation | ❌ | ✅ |
+| **API** | | |
+| isPersistent | ❌ | ✅ |
+| createContext | ❌ | ✅ |
+| Platform APIs | ❌ | ✅ |
+| **Documentation** | | |
+| Platform Guide | ❌ | ✅ |
+| Security Docs | ❌ | ✅ |
+| Platform Tables | ❌ | ✅ |
+
+---
+
+## Deprecations
+
+| Feature | Status | Alternative |
+|---------|--------|---------|
+| `observer()` | ⚠️ Deprecated | Use `useObserver()` in React |
+| Global state in Node.js | ⚡ Discouraged | Use `memorio.createContext()` |
+
+---
+
+*For older versions, please refer to the git history or npm package versions.*

package/docs/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.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/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.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'
+});
+```
+
+---
+
+## 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/docs/markdown/LOGGER.md

@@ -0,0 +1,147 @@
+# Memorio Logger
+
+> 🖥️ **Browser Only**: This feature is only available in browser console
+
+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())
+```