memorio 4.9.7 → 4.9.10

package/examples/cache.ts

@@ -0,0 +1,72 @@
+/**
+ * Memorio Cache Example
+ *
+ * This example demonstrates the cache module for in-memory storage.
+ * Cache is perfect for temporary data that doesn't need persistence.
+ *
+ * Run: npx ts-node examples/cache.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// BASIC CACHE OPERATIONS
+// ============================================
+
+// Set values
+cache.set('username', 'Mario')
+cache.set('score', 1500)
+cache.set('player', { name: 'Mario', level: 5 })
+
+// Get values
+console.debug('Username:', cache.get('username'))
+console.debug('Score:', cache.get('score'))
+console.debug('Player:', cache.get('player'))
+
+// Direct property access
+cache.tempData = 'Hello'
+console.debug('Temp data:', cache.tempData)
+
+// ============================================
+// CACHE WITH OBJECTS
+// ============================================
+
+// Store complex objects
+cache.set('gameState', {
+  level: 3,
+  score: 2500,
+  inventory: ['sword', 'shield', 'potion'],
+  position: { x: 100, y: 200 }
+})
+
+const gameState = cache.get('gameState')
+console.debug('Game level:', gameState?.level)
+console.debug('Inventory:', gameState?.inventory)
+
+// ============================================
+// CACHE SIZE
+// ============================================
+
+// Add multiple items
+for (let i = 0; i < 10; i++) {
+  cache.set(`item_${i}`, { id: i, data: `item-${i}` })
+}
+
+console.debug('Cache keys:', Object.keys(cache))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove single item
+cache.remove('username')
+
+// Clear all cache
+cache.removeAll()
+
+// Or use clearAll alias
+// cache.clearAll()
+
+console.debug('Cache after clear:', cache.get('score'))
+
+console.debug('Cache example complete!')

package/examples/cross-platform-guards.ts

@@ -0,0 +1,57 @@
+/**
+ * cross-platform-guards.ts
+ *
+ * Scenario: code that might run in a browser, Node.js, Deno, or an edge
+ * runtime, and needs to behave correctly (not just "not crash") in each.
+ *
+ * Prefer `getCapabilities()` over branching on `isBrowser()`/`isNode()`
+ * alone — capability support can differ *within* a platform category
+ * (some edge runtimes expose `localStorage`, some don't).
+ */
+import { memorio, idb, store, session } from 'memorio'
+
+export async function savePreferences(prefs: Record<string, unknown>) {
+  const caps = memorio.getCapabilities()
+
+  // store/session silently fall back to a non-durable in-memory Map outside
+  // the browser — that's not a crash, but it's also not what "save" implies
+  // to a caller. Surface the distinction instead of hiding it.
+  store.set('preferences', prefs)
+
+  if (!store.isPersistent) {
+    console.warn(
+      '[preferences] store is not durable in this environment (%s) — ' +
+        'data will not survive a process restart',
+      caps.platform
+    )
+  }
+
+  return store.isPersistent
+}
+
+export async function saveStructuredRecord(dbName: string, table: string, record: unknown) {
+  // idb is disabled outright in Node.js/Deno (no-op + warning). Guard
+  // explicitly instead of relying on that warning reaching anyone.
+  if (!idb.db.support()) {
+    throw new Error(
+      `[saveStructuredRecord] IndexedDB is not available in this environment ` +
+        `(platform: ${memorio.getCapabilities().platform}). ` +
+        `Use sqlite or store instead when running outside a browser.`
+    )
+  }
+
+  await idb.db.create(dbName)
+  await idb.table.create(dbName, table)
+  await idb.data.set(dbName, table, record)
+}
+
+export function describeEnvironment() {
+  const caps = memorio.getCapabilities()
+
+  return {
+    platform: caps.platform,
+    canPersistAcrossTabs: caps.hasLocalStorage,
+    canPersistThisTabOnly: session.isPersistent,
+    canUseStructuredStorage: caps.hasIndexedDB,
+  }
+}

package/examples/idb.ts

@@ -0,0 +1,109 @@
+/**
+ * Memorio IDB Example
+ *
+ * This example shows how to use IndexedDB for large data storage.
+ * IDB is perfect for caching, offline data, and large datasets.
+ *
+ * Run: npx ts-node examples/idb.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// CHECK SUPPORT
+// ============================================
+
+if (!idb.db.support()) {
+  console.debug('IndexedDB not supported')
+  process.exit(0)
+}
+
+// ============================================
+// CREATE DATABASE
+// ============================================
+
+// Create a new database
+idb.db.create('myApp')
+
+// Create tables (stores)
+idb.table.create('myApp', 'users')
+idb.table.create('myApp', 'products')
+
+// ============================================
+// ADD DATA
+// ============================================
+
+// Add user records
+idb.data.set('myApp', 'users', {
+  id: 1,
+  name: 'Mario',
+  email: 'mario@example.com',
+  role: 'admin'
+})
+
+idb.data.set('myApp', 'users', {
+  id: 2,
+  name: 'Luigi',
+  email: 'luigi@example.com',
+  role: 'user'
+})
+
+// Add product records
+idb.data.set('myApp', 'products', {
+  id: 1,
+  name: 'Super Mushroom',
+  price: 99,
+  inStock: true
+})
+
+idb.data.set('myApp', 'products', {
+  id: 2,
+  name: 'Fire Flower',
+  price: 199,
+  inStock: true
+})
+
+// ============================================
+// READ DATA
+// ============================================
+
+const user1 = idb.data.get('myApp', 'users', 1)
+console.debug('User 1:', user1)
+
+const product1 = idb.data.get('myApp', 'products', 1)
+console.debug('Product 1:', product1)
+
+// ============================================
+// DATABASE INFO
+// ============================================
+
+// List all databases
+const databases = idb.db.list()
+console.debug('Databases:', databases)
+
+// Check if database exists
+const exists = idb.db.exist('myApp')
+console.debug('myApp exists:', exists)
+
+// Get database version
+const version = idb.db.version('myApp')
+console.debug('myApp version:', version)
+
+// Get database size
+const size = idb.db.size('myApp')
+console.debug('myApp size:', size, 'bytes')
+
+// ============================================
+// DELETE DATA
+// ============================================
+
+// Delete a record
+idb.data.delete('myApp', 'users', 1)
+
+// Delete entire table
+// idb.table.delete('myApp', 'users');
+
+// Delete entire database
+// idb.db.delete('myApp');
+
+console.debug('IDB example complete!')

package/examples/multi-tenant-context.ts

@@ -0,0 +1,44 @@
+/**
+ * multi-tenant-context.ts
+ *
+ * Scenario: a server-side handler (API route, edge function) that may
+ * process requests from different users/tenants in the same process.
+ *
+ * `state` is a shared global namespace by default — writing to it directly
+ * in a multi-request handler leaks data between requests. Use an explicit
+ * context per request instead.
+ */
+import { memorio } from 'memorio'
+
+interface RequestContext {
+  userId: string
+  tenantId: string
+}
+
+export function handleRequest(req: RequestContext, payload: { language: string }) {
+  // Derive the context id from trusted, server-verified data — never from a
+  // raw client-supplied header or query param, since contexts are a
+  // key-prefix convention, not a hard isolation boundary.
+  const contextId = `tenant:${req.tenantId}:user:${req.userId}`
+  const ctx = memorio.createContext(contextId)
+
+  // All reads/writes go through ctx.state, not the bare global `state` —
+  // this is what actually keeps this request's data from leaking into the
+  // next one handled by the same process.
+  ctx.state.language = payload.language
+
+  return { language: ctx.state.language }
+}
+
+// Cleanup for long-lived processes that create many short-lived contexts
+// (e.g. one per request in a busy server): drop the context when the
+// request is done, or it accumulates for the life of the process.
+export function teardownRequest(req: RequestContext) {
+  const contextId = `tenant:${req.tenantId}:user:${req.userId}`
+  memorio.deleteContext(contextId)
+}
+
+// NOTE: context isolation here is organizational (key-prefixing under the
+// same storage), not a security boundary. Don't rely on it as the only
+// thing preventing one tenant from reaching another tenant's data — enforce
+// that at the auth/backend layer as well.

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 'memorio'
+
+// ============================================
+// 1. BASIC USAGE
+// ============================================
+
+console.debug('=== 1. Basic Node.js Usage ===')
+
+// Check platform
+console.debug('Platform:', memorio.isNode() ? 'Node.js ✅' : 'Other')
+
+// Check persistence (false in Node.js - uses memory fallback)
+console.debug('Store persistent:', store.isPersistent)  // false
+console.debug('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.debug('App name:', state.appName)
+console.debug('Config:', state.config)
+
+// ============================================
+// 2. CACHE (In-Memory - Perfect for Server)
+// ============================================
+
+console.debug('\n=== 2. Cache (In-Memory) ===')
+
+// Cache is perfect for temporary server data
+cache.set('apiResponse', { data: 'cached value' })
+cache.set('userCount', 42)
+
+console.debug('Cached API response:', cache.get('apiResponse'))
+console.debug('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.debug('\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.debug('Server config:', store.get('serverConfig'))
+console.debug('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.debug('\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.debug('User A name:', userAContext.state.user.name)  // Alice
+console.debug('User B name:', userBContext.state.user.name)  // Bob
+
+// Global state is separate
+console.debug('Global state:', state.appName)  // 'My Server App'
+console.debug('User A global secret:', userAContext.state.secret)  // 'Alice secret data'
+console.debug('User B global secret:', userBContext.state.secret)  // 'Bob secret data'
+
+// ============================================
+// 5. EXPRESS.JS MIDDLEWARE EXAMPLE
+// ============================================
+
+console.debug('\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.debug('See code comments for Express.js integration')
+
+// ============================================
+// 6. WEBSOCKET EXAMPLE
+// ============================================
+
+console.debug('\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.debug('See code comments for WebSocket integration')
+
+// ============================================
+// 7. JOB QUEUE / WORKER EXAMPLE
+// ============================================
+
+console.debug('\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.debug('See code comments for Job Queue integration')
+
+// ============================================
+// 8. CLI APPLICATION EXAMPLE
+// ============================================
+
+console.debug('\n=== 8. CLI Application ===')
+
+// Memorio works great in CLI apps too
+state.command = 'build'
+state.options = {
+  minify: true,
+  sourceMap: false
+}
+
+console.debug('Command:', state.command)
+console.debug('Options:', state.options)
+
+// ============================================
+// 9. PLATFORM DETECTION
+// ============================================
+
+console.debug('\n=== 9. Platform Detection ===')
+
+const caps = memorio.getCapabilities()
+console.debug('Platform:', caps.platform)
+console.debug('localStorage:', caps.hasLocalStorage ? '✅' : '❌')
+console.debug('sessionStorage:', caps.hasSessionStorage ? '✅' : '❌')
+console.debug('IndexedDB:', caps.hasIndexedDB ? '✅' : '❌')
+console.debug('Session ID:', caps.sessionId.substring(0, 8) + '...')
+
+// ============================================
+// 10. CLEANUP
+// ============================================
+
+console.debug('\n=== 10. Cleanup ===')
+
+// List all contexts
+console.debug('Active contexts:', memorio.listContexts())
+
+// Clean up when done
+memorio.deleteContext('tenant-A')
+memorio.deleteContext('tenant-B')
+
+console.debug('After cleanup:', memorio.listContexts())
+
+// ============================================
+// SUMMARY
+// ============================================
+
+console.debug('\n=== Summary ===')
+console.debug(`
+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.debug('\nNode.js example complete!')

package/examples/observer.ts

@@ -0,0 +1,60 @@
+/**
+ * Memorio Observer Example
+ *
+ * This example demonstrates the observer pattern for reactive state changes.
+ * Perfect for logging, analytics, auto-save, and UI updates.
+ *
+ * Run: npx ts-node examples/observer.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// SIMPLE OBSERVER
+// ============================================
+
+// Watch a single value
+observer('state.counter', (newValue, oldValue) => {
+  console.debug(`Counter: ${oldValue} → ${newValue}`)
+})
+
+state.counter = 0
+state.counter = 1
+state.counter = 2
+
+// ============================================
+// OBJECT OBSERVER
+// ============================================
+
+// Watch entire objects
+observer('state.user', (newUser, oldUser) => {
+  console.debug(`User changed: ${oldUser?.name} → ${newUser?.name}`)
+})
+
+state.user = { name: 'Mario', level: 1 }
+state.user = { name: 'Luigi', level: 2 }
+
+// ============================================
+// MULTIPLE OBSERVERS
+// ============================================
+
+// Multiple observers on same path
+observer('state.notifications', (count) => {
+  console.debug(`New notification count: ${count}`)
+})
+
+// List all observers
+console.debug('Active observers:', observer.list)
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove specific observer
+observer.remove('state.counter')
+
+// Remove all observers - call remove for each path
+// observer.remove('state.counter')
+// observer.remove('state.notifications')
+
+console.debug('Observer example complete!')