memorio 2.6.6 → 2.7.0

package/examples/node-server.ts

@@ -0,0 +1,308 @@
+/**
+ * Memorio Node.js Server Example
+ *
+ * This example shows how to use Memorio in a Node.js server environment.
+ * Includes context isolation for multi-tenant applications.
+ *
+ * Run: npx ts-node examples/node-server.ts
+ */
+
+import '../index'
+
+// ============================================
+// 1. BASIC USAGE
+// ============================================
+
+console.log('=== 1. Basic Node.js Usage ===')
+
+// Check platform
+console.log('Platform:', memorio.isNode() ? 'Node.js ✅' : 'Other')
+
+// Check persistence (false in Node.js - uses memory fallback)
+console.log('Store persistent:', store.isPersistent)  // false
+console.log('Session persistent:', session.isPersistent)  // false
+
+// State works exactly like in browser
+state.appName = 'My Server App'
+state.startTime = Date.now()
+state.config = {
+  port: 3000,
+  env: 'production'
+}
+
+console.log('App name:', state.appName)
+console.log('Config:', state.config)
+
+// ============================================
+// 2. CACHE (In-Memory - Perfect for Server)
+// ============================================
+
+console.log('\n=== 2. Cache (In-Memory) ===')
+
+// Cache is perfect for temporary server data
+cache.set('apiResponse', { data: 'cached value' })
+cache.set('userCount', 42)
+
+console.log('Cached API response:', cache.get('apiResponse'))
+console.log('User count:', cache.get('userCount'))
+
+// Clear cache when needed
+cache.remove('apiResponse')
+// cache.clearAll() - clear all
+
+// ============================================
+// 3. STORE & SESSION (Memory Fallback in Node.js)
+// ============================================
+
+console.log('\n=== 3. Store & Session (Memory Fallback) ===')
+
+// Store and session work but don't persist (no localStorage in Node.js)
+store.set('serverConfig', { debug: true })
+session.set('requestData', { path: '/api/users' })
+
+console.log('Server config:', store.get('serverConfig'))
+console.log('Request data:', session.get('requestData'))
+
+// ⚠️ Data is lost on process restart!
+// For persistence in Node.js, use a database
+
+// ============================================
+// 4. CONTEXT ISOLATION (Multi-Tenant)
+// ============================================
+
+console.log('\n=== 4. Context Isolation (Multi-Tenant) ===')
+
+// Create isolated contexts for different tenants/requests
+const userAContext = memorio.createContext('tenant-A')
+const userBContext = memorio.createContext('tenant-B')
+
+// Each context has completely separate data
+userAContext.state.user = { name: 'Alice', id: 1 }
+userAContext.state.secret = 'Alice secret data'
+userAContext.cache.set('temp', 'A temp data')
+
+userBContext.state.user = { name: 'Bob', id: 2 }
+userBContext.state.secret = 'Bob secret data'
+userBContext.cache.set('temp', 'B temp data')
+
+// Verify isolation
+console.log('User A name:', userAContext.state.user.name)  // Alice
+console.log('User B name:', userBContext.state.user.name)  // Bob
+
+// Global state is separate
+console.log('Global state:', state.appName)  // 'My Server App'
+console.log('User A global secret:', userAContext.state.secret)  // 'Alice secret data'
+console.log('User B global secret:', userBContext.state.secret)  // 'Bob secret data'
+
+// ============================================
+// 5. EXPRESS.JS MIDDLEWARE EXAMPLE
+// ============================================
+
+console.log('\n=== 5. Express.js Middleware Example ===')
+
+/*
+// In a real Express app:
+
+import express from 'express'
+const app = express()
+
+// Middleware to create isolated context per request
+app.use((req, res, next) => {
+  // Create unique context for this request
+  const ctx = memorio.createContext(`req-${req.id}`)
+
+  // Attach to request for use in handlers
+  req.memorio = ctx
+
+  // Clean up on response finish
+  res.on('finish', () => {
+    memorio.deleteContext(ctx.id)
+  })
+
+  next()
+})
+
+// Route handler using isolated context
+app.get('/api/user', (req, res) => {
+  const ctx = req.memorio
+
+  // Set request-specific state
+  ctx.state.requestId = req.id
+  ctx.state.startTime = Date.now()
+
+  // Cache data for this request
+  ctx.cache.set('query', req.query)
+
+  // Get user data
+  const user = getUserFromDB(req.params.id)
+
+  // Return response
+  res.json({
+    user,
+    requestId: ctx.state.requestId
+  })
+})
+
+app.listen(3000)
+*/
+
+console.log('See code comments for Express.js integration')
+
+// ============================================
+// 6. WEBSOCKET EXAMPLE
+// ============================================
+
+console.log('\n=== 6. WebSocket Example ===')
+
+/*
+// For WebSocket connections:
+
+const activeConnections = new Map()
+
+function handleConnection(ws, userId) {
+  // Create isolated context for this user
+  const ctx = memorio.createContext(`ws-${userId}`)
+
+  // Store user data
+  ctx.state.userId = userId
+  ctx.state.connected = true
+
+  // Store in connection map
+  activeConnections.set(userId, ctx)
+
+  ws.on('message', (message) => {
+    // Process message using isolated context
+    ctx.cache.set('lastMessage', message)
+    handleMessage(ctx, message)
+  })
+
+  ws.on('close', () => {
+    // Clean up
+    ctx.state.connected = false
+    activeConnections.delete(userId)
+    memorio.deleteContext(ctx.id)
+  })
+}
+*/
+
+console.log('See code comments for WebSocket integration')
+
+// ============================================
+// 7. JOB QUEUE / WORKER EXAMPLE
+// ============================================
+
+console.log('\n=== 7. Job Queue Example ===')
+
+/*
+// For background jobs:
+
+async function processJob(jobId, jobData) {
+  // Create isolated context for this job
+  const ctx = memorio.createContext(`job-${jobId}`)
+
+  try {
+    // Track job progress
+    ctx.state.jobId = jobId
+    ctx.state.status = 'processing'
+    ctx.state.progress = 0
+
+    // Process in stages
+    for (let i = 0; i < 10; i++) {
+      await doWork(jobData)
+      ctx.state.progress = (i + 1) * 10
+
+      // Cache intermediate results
+      ctx.cache.set(`stage-${i}`, true)
+    }
+
+    ctx.state.status = 'completed'
+    return { success: true }
+
+  } catch (error) {
+    ctx.state.status = 'failed'
+    ctx.state.error = error.message
+    throw error
+
+  } finally {
+    // Clean up after job completes
+    memorio.deleteContext(ctx.id)
+  }
+}
+*/
+
+console.log('See code comments for Job Queue integration')
+
+// ============================================
+// 8. CLI APPLICATION EXAMPLE
+// ============================================
+
+console.log('\n=== 8. CLI Application ===')
+
+// Memorio works great in CLI apps too
+state.command = 'build'
+state.options = {
+  minify: true,
+  sourceMap: false
+}
+
+console.log('Command:', state.command)
+console.log('Options:', state.options)
+
+// ============================================
+// 9. PLATFORM DETECTION
+// ============================================
+
+console.log('\n=== 9. Platform Detection ===')
+
+const caps = memorio.getCapabilities()
+console.log('Platform:', caps.platform)
+console.log('localStorage:', caps.hasLocalStorage ? '✅' : '❌')
+console.log('sessionStorage:', caps.hasSessionStorage ? '✅' : '❌')
+console.log('IndexedDB:', caps.hasIndexedDB ? '✅' : '❌')
+console.log('Session ID:', caps.sessionId.substring(0, 8) + '...')
+
+// ============================================
+// 10. CLEANUP
+// ============================================
+
+console.log('\n=== 10. Cleanup ===')
+
+// List all contexts
+console.log('Active contexts:', memorio.listContexts())
+
+// Clean up when done
+memorio.deleteContext('tenant-A')
+memorio.deleteContext('tenant-B')
+
+console.log('After cleanup:', memorio.listContexts())
+
+// ============================================
+// SUMMARY
+// ============================================
+
+console.log('\n=== Summary ===')
+console.log(`
+MEMORIO NODE.JS USAGE:
+
+✅ WORKS:
+   - state: In-memory global state
+   - cache: In-memory temporary cache
+   - store: In-memory (NOT persistent!)
+   - session: In-memory (NOT persistent!)
+   - createContext: Perfect for isolation
+
+⚠️ NOTES:
+   - store/session don't persist in Node.js
+   - Use database for persistence
+   - Always use contexts for request isolation
+   - Clean up contexts after use
+
+🔧 BEST PRACTICES:
+   1. Create context per request: createContext(\`req-\${req.id}\`)
+   2. Use cache for temporary data
+   3. Use state for request-scoped data
+   4. Delete contexts after response
+   5. Check isPersistent before relying on persistence
+`)
+
+console.log('\nNode.js example complete!')

package/examples/platform.ts

@@ -0,0 +1,115 @@
+/**
+ * Memorio Platform & Context Example
+ *
+ * This example demonstrates:
+ * - Platform detection
+ * - Checking storage persistence
+ * - Context isolation for server-side multi-tenancy
+ *
+ * Run: npx ts-node examples/platform.ts
+ */
+
+import '../index'
+
+// ============================================
+// PLATFORM DETECTION
+// ============================================
+
+console.log('=== Platform Detection ===')
+console.log('Memorio version:', memorio.version)
+
+// Check which platform we're on
+if (memorio.isBrowser()) {
+  console.log('Running in: Browser')
+  console.log('store.isPersistent:', store.isPersistent) // true
+  console.log('session.isPersistent:', session.isPersistent) // true
+} else if (memorio.isNode()) {
+  console.log('Running in: Node.js')
+  console.log('store.isPersistent:', store.isPersistent) // false (memory fallback)
+  console.log('session.isPersistent:', session.isPersistent) // false (memory fallback)
+} else if (memorio.isDeno()) {
+  console.log('Running in: Deno')
+  console.log('store.isPersistent:', store.isPersistent) // false (memory fallback)
+  console.log('session.isPersistent:', session.isPersistent) // false (memory fallback)
+} else if (memorio.isEdge()) {
+  console.log('Running in: Edge Worker')
+  console.log('store.isPersistent:', store.isPersistent) // true
+  console.log('session.isPersistent:', session.isPersistent) // true
+}
+
+// Get detailed capabilities
+const caps = memorio.getCapabilities()
+console.log('\nCapabilities:')
+console.log('  Platform:', caps.platform)
+console.log('  localStorage:', caps.hasLocalStorage ? '✅' : '❌')
+console.log('  sessionStorage:', caps.hasSessionStorage ? '✅' : '❌')
+console.log('  IndexedDB:', caps.hasIndexedDB ? '✅' : '❌')
+console.log('  Session ID:', caps.sessionId)
+
+// ============================================
+// CONTEXT ISOLATION (Server-Side)
+// ============================================
+
+console.log('\n=== Context Isolation ===')
+console.log('Use memorio.createContext() for multi-tenant server applications')
+
+// Example: Simulating different users/requests
+// In a real app, you'd create a context per HTTP request
+
+// Create isolated context for User A
+const userAContext = memorio.createContext('user-A')
+userAContext.state.name = 'Mario'
+userAContext.store.set('preferences', { theme: 'dark' })
+userAContext.session.set('token', 'user-A-token')
+
+// Create isolated context for User B
+const userBContext = memorio.createContext('user-B')
+userBContext.state.name = 'Luigi'
+userBContext.store.set('preferences', { theme: 'light' })
+userBContext.session.set('token', 'user-B-token')
+
+// Verify isolation - each context has its own data
+console.log('\nUser A context:')
+console.log('  state.name:', userAContext.state.name) // 'Mario'
+console.log('  store.preferences:', userAContext.store.get('preferences')) // { theme: 'dark' }
+console.log('  session.token:', userAContext.session.get('token')) // 'user-A-token'
+
+console.log('\nUser B context:')
+console.log('  state.name:', userBContext.state.name) // 'Luigi'
+console.log('  store.preferences:', userBContext.store.get('preferences')) // { theme: 'light' }
+console.log('  session.token:', userBContext.session.get('token')) // 'user-B-token'
+
+// Global state is separate from contexts
+console.log('\nGlobal state (not affected by contexts):')
+console.log('  state.name:', state.name) // undefined
+
+// List all contexts
+console.log('\nActive contexts:', memorio.listContexts()) // ['user-A', 'user-B']
+
+// Cleanup - delete a context when done
+memorio.deleteContext('user-A')
+console.log('After deleting user-A:', memorio.listContexts()) // ['user-B']
+
+// ============================================
+// USE CASE: EXPRESS/FASTIFY MIDDLEWARE EXAMPLE
+// ============================================
+
+console.log('\n=== Server Use Case ===')
+console.log(`
+// Example: Express middleware for request isolation
+app.use((req, res, next) => {
+  // Create isolated context per request
+  const ctx = memorio.createContext(\`req-\${req.id}\`)
+  req.memorio = ctx
+  next()
+})
+
+// In your route handler:
+app.get('/user', (req, res) => {
+  // This state is isolated per request
+  req.memorio.state.user = getUserData()
+  req.memorio.store.set('cache', data)
+})
+`)
+
+console.log('\nPlatform & Context example complete!')