memorio 2.6.6 → 2.7.0

package/README.md

@@ -39,6 +39,8 @@
 - [Testing](#testing)
 - [Security](#security)
 - [License](#license)
+- [Cross-Platform Support](#cross-platform-support)
+  - [Platform & Context Isolation](docs/markdown/PLATFORM.md)
 
 ## Features
 
@@ -48,6 +50,9 @@
 - Type-safe with full TypeScript support
 - Comprehensive test coverage
 - Easy debugging with proxy-based state
+- **Cross-platform**: Works in Browser, Node.js, Deno, and Edge Workers
+- **Session Isolation**: Each session/request gets isolated state namespace
+- **Context System**: Multi-tenant server-side isolation with `memorio.createContext()`
 
 ## ⚠️ Enterprise Use
 
@@ -311,3 +316,100 @@ Security scans and reports are available at:
 MIT License
 
 Copyrigth (c) [Dario Passariello](https://dario.passariello.ca/)
+
+---
+
+## Cross-Platform Support
+
+Memorio is designed to work across multiple JavaScript environments:
+
+### Platform Compatibility
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|---------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+### Session Isolation
+
+Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
+
+- **Unique Session IDs**: Each import gets a unique session identifier
+- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
+- **State Isolation**: `state` is isolated per-instance
+
+This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
+
+### Best Practices
+
+1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
+2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
+3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
+
+### Checking Platform
+
+```javascript
+// Platform detection is available via the internal module
+// Note: Public API coming in future versions
+```
+
+---
+
+## Cross-Platform Support
+
+Memorio is designed to work across multiple JavaScript environments:
+
+### Platform Compatibility
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|---------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+### Session Isolation
+
+Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
+
+- **Unique Session IDs**: Each import gets a unique session identifier
+- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
+- **State Isolation**: `state` is isolated per-instance
+
+This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
+
+### Best Practices
+
+1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
+2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
+3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
+
+### Checking Platform
+
+```javascript
+import { isBrowser, isNode, isDeno, getCapabilities } from 'memorio';
+
+console.log('Browser:', isBrowser());      // true in browser
+console.log('Node.js:', isNode());          // true in Node.js
+console.log('Deno:', isDeno());             // true in Deno
+
+const caps = getCapabilities();
+console.log('Platform:', caps.platform);    // 'browser' | 'node' | 'deno' | 'edge'
+console.log('Persistent:', store.isPersistent); // true if using real storage
+```

package/examples/basic.ts

@@ -5,16 +5,46 @@
  * - State management
  * - Store (localStorage)
  * - Session storage
+ * - Platform detection
  *
  * Run: npx ts-node examples/basic.ts
  */
 
 import '../index'
 
+// ============================================
+// PLATFORM DETECTION
+// ============================================
+
+console.log('=== Platform Detection ===')
+console.log('Memorio version:', memorio.version)
+
+// Check platform
+if (memorio.isBrowser()) {
+  console.log('Platform: Browser')
+} else if (memorio.isNode()) {
+  console.log('Platform: Node.js')
+} else if (memorio.isDeno()) {
+  console.log('Platform: Deno')
+} else if (memorio.isEdge()) {
+  console.log('Platform: Edge Worker')
+}
+
+// Get capabilities
+const caps = memorio.getCapabilities()
+console.log('Capabilities:', {
+  platform: caps.platform,
+  hasLocalStorage: caps.hasLocalStorage,
+  hasSessionStorage: caps.hasSessionStorage,
+  hasIndexedDB: caps.hasIndexedDB
+})
+
 // ============================================
 // STATE - In-memory reactive state
 // ============================================
 
+console.log('\n=== State Management ===')
+
 // Set some state values
 state.name = 'Mario'
 state.age = 30
@@ -36,6 +66,11 @@ console.log('All states:', state.list)
 // STORE - Persistent localStorage
 // ============================================
 
+console.log('\n=== Store (Persistent Storage) ===')
+
+// Check persistence
+console.log('Is persistent:', store.isPersistent) // true in browser, false in Node.js/Deno
+
 // Save to localStorage
 store.set('username', 'mario')
 store.set('preferences', { theme: 'dark', language: 'en' })
@@ -52,6 +87,11 @@ console.log('Storage size:', store.size(), 'bytes')
 // SESSION - Temporary session storage
 // ============================================
 
+console.log('\n=== Session (Temporary Storage) ===')
+
+// Check persistence
+console.log('Is persistent:', session.isPersistent) // true in browser, false in Node.js/Deno
+
 // Save session data (cleared when tab closes)
 session.set('token', 'abc123xyz')
 session.set('userId', 42)
@@ -72,4 +112,4 @@ session.remove('token')
 store.removeAll()
 session.removeAll()
 
-console.log('Example complete!')
+console.log('\nExample complete!')

package/examples/browser-vanilla.html

@@ -0,0 +1,358 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Memorio Vanilla JS Example</title>
+  <style>
+    /* Simple CSS */
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+      background: #f5f5f5;
+    }
+
+    .card {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      margin-bottom: 20px;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    h1 {
+      color: #333;
+    }
+
+    h2 {
+      color: #666;
+      margin-top: 0;
+    }
+
+    button {
+      background: #007bff;
+      color: white;
+      border: none;
+      padding: 10px 20px;
+      border-radius: 4px;
+      cursor: pointer;
+      margin: 5px;
+    }
+
+    button:hover {
+      background: #0056b3;
+    }
+
+    button.danger {
+      background: #dc3545;
+    }
+
+    button.danger:hover {
+      background: #c82333;
+    }
+
+    button.success {
+      background: #28a745;
+    }
+
+    button.success:hover {
+      background: #218838;
+    }
+
+    input,
+    select {
+      padding: 8px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      margin: 5px;
+    }
+
+    pre {
+      background: #f8f9fa;
+      padding: 10px;
+      border-radius: 4px;
+      overflow-x: auto;
+    }
+
+    .output {
+      background: #e9ecef;
+      padding: 10px;
+      border-radius: 4px;
+      font-family: monospace;
+      white-space: pre-wrap;
+    }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 10px;
+    }
+
+    .stat {
+      background: #e7f3ff;
+      padding: 10px;
+      border-radius: 4px;
+      text-align: center;
+    }
+
+    .stat-value {
+      font-size: 24px;
+      font-weight: bold;
+      color: #007bff;
+    }
+
+    .stat-label {
+      font-size: 12px;
+      color: #666;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>🧠 Memorio Vanilla JS Demo</h1>
+
+  <!-- State Section -->
+  <div class="card">
+    <h2>1. State (Reactive)</h2>
+    <p>Global reactive state - changes trigger UI updates automatically</p>
+
+    <div class="grid">
+      <div class="stat">
+        <div class="stat-value" id="counter">0</div>
+        <div class="stat-label">Counter</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="username">-</div>
+        <div class="stat-label">Username</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="theme">light</div>
+        <div class="stat-label">Theme</div>
+      </div>
+    </div>
+
+    <br>
+    <button onclick="state.counter++">Increment Counter</button>
+    <button onclick="state.counter--">Decrement</button>
+    <button onclick="state.counter = 0">Reset</button>
+
+    <h3>Set Username:</h3>
+    <input type="text" id="nameInput" placeholder="Enter name">
+    <button onclick="state.username = document.getElementById('nameInput').value">Set</button>
+
+    <h3>Theme:</h3>
+    <button onclick="state.theme = 'light'">Light</button>
+    <button onclick="state.theme = 'dark'">Dark</button>
+
+    <h3>All State:</h3>
+    <pre id="stateOutput" class="output"></pre>
+  </div>
+
+  <!-- Store Section -->
+  <div class="card">
+    <h2>2. Store (localStorage)</h2>
+    <p>Permanent storage - survives page refresh</p>
+    <p>Persistent: <span id="storePersistent">checking...</span></p>
+
+    <input type="text" id="storeKey" placeholder="Key">
+    <input type="text" id="storeValue" placeholder="Value">
+    <button
+      onclick="store.set(document.getElementById('storeKey').value, document.getElementById('storeValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('storeOutput').textContent = JSON.stringify(store.get(document.getElementById('storeKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="store.remove(document.getElementById('storeKey').value)">Delete</button>
+
+    <h3>All Store Data:</h3>
+    <pre id="storeOutput" class="output"></pre>
+  </div>
+
+  <!-- Session Section -->
+  <div class="card">
+    <h2>3. Session (sessionStorage)</h2>
+    <p>Temporary storage - cleared when tab closes</p>
+    <p>Persistent: <span id="sessionPersistent">checking...</span></p>
+
+    <input type="text" id="sessionKey" placeholder="Key">
+    <input type="text" id="sessionValue" placeholder="Value">
+    <button
+      onclick="session.set(document.getElementById('sessionKey').value, document.getElementById('sessionValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('sessionOutput').textContent = JSON.stringify(session.get(document.getElementById('sessionKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="session.remove(document.getElementById('sessionKey').value)">Delete</button>
+
+    <h3>All Session Data:</h3>
+    <pre id="sessionOutput" class="output"></pre>
+  </div>
+
+  <!-- Cache Section -->
+  <div class="card">
+    <h2>4. Cache (In-Memory)</h2>
+    <p>Temporary cache - cleared on refresh</p>
+
+    <input type="text" id="cacheKey" placeholder="Key">
+    <input type="text" id="cacheValue" placeholder="Value">
+    <button
+      onclick="cache.set(document.getElementById('cacheKey').value, document.getElementById('cacheValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('cacheOutput').textContent = JSON.stringify(cache.get(document.getElementById('cacheKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="cache.remove(document.getElementById('cacheKey').value)">Delete</button>
+
+    <h3>All Cache Data:</h3>
+    <pre id="cacheOutput" class="output"></pre>
+  </div>
+
+  <!-- Observer Section -->
+  <div class="card">
+    <h2>5. Observer (Auto-Reactive)</h2>
+    <p>Watch for state changes automatically</p>
+
+    <button class="success" id="startObserver">Start Observer</button>
+    <button class="danger" id="stopObserver">Stop Observer</button>
+    <button onclick="state.testValue = Math.random()">Trigger Change</button>
+
+    <h3>Observer Log:</h3>
+    <pre id="observerLog" class="output"></pre>
+  </div>
+
+  <!-- Platform Info -->
+  <div class="card">
+    <h2>6. Platform Info</h2>
+    <div id="platformInfo" class="output"></div>
+  </div>
+
+  <!-- Load Memorio -->
+  <script src="https://cdn.jsdelivr.net/npm/memorio/dist/index.cjs"></script>
+
+  <script>
+    // ============================================
+    // MEMORIO VANILLA JS EXAMPLE
+    // ============================================
+
+    // 1. REACTIVE STATE
+    // -----------------
+
+    // Initialize state
+    state.counter = 0
+    state.username = 'Guest'
+    state.theme = 'light'
+    state.testValue = 0
+
+    // Update UI when state changes
+    function updateStateUI() {
+      document.getElementById('counter').textContent = state.counter
+      document.getElementById('username').textContent = state.username
+      document.getElementById('theme').textContent = state.theme
+      document.getElementById('stateOutput').textContent = JSON.stringify({
+        counter: state.counter,
+        username: state.username,
+        theme: state.theme,
+        testValue: state.testValue
+      }, null, 2)
+    }
+
+    // Use observer to react to changes
+    useObserver(() => {
+      updateStateUI()
+      document.body.className = state.theme
+    }, [state.counter, state.username, state.theme, state.testValue])
+
+    // 2. PERSISTENT STORE
+    // -------------------
+
+    // Check persistence
+    document.getElementById('storePersistent').textContent = store.isPersistent ? '✅ Yes (localStorage)' : '❌ No (memory)'
+
+    // Save sample data
+    store.set('visits', '0')
+    store.set('lastVisit', new Date().toISOString())
+
+    function updateStoreUI() {
+      document.getElementById('storeOutput').textContent = 'Visits: ' + store.get('visits') + '\nLast Visit: ' + store.get('lastVisit')
+    }
+    updateStoreUI()
+
+    // Increment visits
+    let visits = parseInt(store.get('visits') || '0')
+    store.set('visits', (visits + 1).toString())
+
+    // 3. SESSION STORAGE
+    // ------------------
+
+    document.getElementById('sessionPersistent').textContent = session.isPersistent ? '✅ Yes (sessionStorage)' : '❌ No (memory)'
+
+    session.set('pageViews', '0')
+
+    function updateSessionUI() {
+      document.getElementById('sessionOutput').textContent = 'Page Views: ' + session.get('pageViews')
+    }
+    updateSessionUI()
+
+    // Increment page views
+    let pageViews = parseInt(session.get('pageViews') || '0')
+    session.set('pageViews', (pageViews + 1).toString())
+
+    // 4. CACHE (In-Memory)
+    // --------------------
+
+    cache.set('tempData', { computed: true, timestamp: Date.now() })
+
+    function updateCacheUI() {
+      document.getElementById('cacheOutput').textContent = JSON.stringify(cache.get('tempData'), null, 2)
+    }
+    updateCacheUI()
+
+    // 5. OBSERVER
+    // -----------
+
+    let observerActive = false
+    const logEl = document.getElementById('observerLog')
+
+    document.getElementById('startObserver').onclick = () => {
+      observerActive = true
+      logEl.textContent += 'Observer started!\n'
+    }
+
+    document.getElementById('stopObserver').onclick = () => {
+      observerActive = false
+      logEl.textContent += 'Observer stopped!\n'
+    }
+
+    // This creates a persistent observer
+    useObserver((newVal, oldVal) => {
+      if (observerActive) {
+        logEl.textContent += `Changed: ${oldVal} → ${newVal}\n`
+        logEl.scrollTop = logEl.scrollHeight
+      }
+    }, [state.testValue])
+
+    // 6. PLATFORM INFO
+    // ----------------
+
+    const platformInfo = document.getElementById('platformInfo')
+    platformInfo.textContent = `
+Platform Detection:
+-----------------
+Browser: ${memorio.isBrowser() ? '✅' : '❌'}
+Node.js: ${memorio.isNode() ? '✅' : '❌'}
+Deno: ${memorio.isDeno() ? '✅' : '❌'}
+Edge: ${memorio.isEdge() ? '✅' : '❌'}
+
+Capabilities:
+-------------
+localStorage: ${memorio.getCapabilities().hasLocalStorage ? '✅' : '❌'}
+sessionStorage: ${memorio.getCapabilities().hasSessionStorage ? '✅' : '❌'}
+IndexedDB: ${memorio.getCapabilities().hasIndexedDB ? '✅' : '❌'}
+
+Session ID: ${memorio.getCapabilities().sessionId.substring(0, 8)}...
+    `.trim()
+
+    // Log welcome
+    console.log('🧠 Memorio loaded!')
+    console.log('Platform:', memorio.getCapabilities().platform)
+  </script>
+</body>
+
+</html>