memorio 4.9.35 → 5.0.0

package/examples/cache.ts

@@ -1,72 +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!')
+/**
+ * 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 { cache } from '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

@@ -1,57 +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,
-  }
-}
+/**
+ * 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/history.ts

@@ -0,0 +1,104 @@
+/**
+ * history.ts
+ *
+ * Scenario: an AI agent (or any code) that wants to try a batch of state
+ * mutations, inspect what actually changed, and only keep them if they
+ * look right - otherwise roll everything back in one shot.
+ *
+ * History tracking is opt-in and disabled by default to avoid overhead -
+ * call `memorio.enableHistory()` before you rely on undo/redo/trace.
+ * `snapshot()`/`diff()`/`rollback()` work independently of that flag.
+ */
+import { memorio, state } from 'memorio'
+
+export function tryExperiment(mutate: () => void) {
+  // Snapshot first - this is the safe rollback point, independent of
+  // whether history tracking is enabled.
+  const before = memorio.snapshot()
+
+  mutate()
+
+  const changes = memorio.diff(before)
+  console.debug('Proposed changes:', changes)
+
+  return { before, changes }
+}
+
+export function commitOrRollback(before: Record<string, unknown>, accept: boolean) {
+  if (!accept) {
+    // Full-state restore, in one step - not the same as calling undo()
+    // repeatedly, which only unwinds one mutation at a time.
+    memorio.rollback(before)
+    console.debug('Rolled back - state restored to pre-experiment snapshot')
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Undo / redo, step by step
+// ---------------------------------------------------------------------------
+
+export function stepByStepDemo() {
+  memorio.enableHistory()
+
+  state.user = { name: 'Sara' }
+  state.counter = 100
+  state.items = ['a', 'b']
+
+  memorio.undo() // removes state.items
+  memorio.undo() // counter → undefined
+  memorio.redo() // counter → 100 again
+
+  console.debug('canUndo:', memorio.canUndo())
+  console.debug('canRedo:', memorio.canRedo())
+
+  // Keep at most 50 mutations per undo/redo stack (default: 100). Lower
+  // this in memory-constrained environments.
+  memorio.setMaxHistory(50)
+}
+
+// ---------------------------------------------------------------------------
+// Trace log - every mutation, with before/after values and a timestamp
+// ---------------------------------------------------------------------------
+
+export function auditTrail() {
+  memorio.enableHistory()
+
+  state.user.name = 'Sara'
+  state.counter = 1
+  state.counter = 2
+
+  const log = memorio.trace()
+  console.debug('Mutation log:', log)
+
+  // ⚠️ The trace log records every value written, including tokens/PII.
+  // Don't ship it as-is to a client, and clear it (or disable tracking)
+  // on paths that touch sensitive data.
+  return log
+}
+
+export function exportAndReplayTrace() {
+  const log = memorio.trace()
+  const saved = JSON.stringify(log)
+
+  // ... persist `saved` somewhere (store, a file, a request body) ...
+
+  const restored = JSON.parse(saved) as Array<{ action: string; path: string; newValue: unknown }>
+  for (const record of restored) {
+    if (record.action === 'set') {
+      // `state` accepts dotted-path-style top-level keys as used in the
+      // trace log; nested paths need a small helper to walk into `state`.
+      ;(state as Record<string, unknown>)[record.path] = record.newValue
+    }
+  }
+}
+
+export function resetHistory() {
+  memorio.clearHistory() // wipes undo/redo stacks + trace log (state itself is untouched)
+  memorio.clearRedo() // or just drop the redo stack, keeping undo intact
+}
+
+// Usage:
+// const { before, changes } = tryExperiment(() => {
+//   state.user = { name: 'Sara', role: 'admin' }
+// })
+// commitOrRollback(before, /* accept = */ changes.length <= 3)

package/examples/idb.ts

@@ -1,109 +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!')
+/**
+ * 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 { idb } from '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

@@ -1,44 +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.
+/**
+ * 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.