memorio 4.9.7 → 4.9.10

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 'memorio'
+
+// ============================================
+// PLATFORM DETECTION
+// ============================================
+
+console.debug('=== Platform Detection ===')
+console.debug('Memorio version:', memorio.version)
+
+// Check which platform we're on
+if (memorio.isBrowser()) {
+  console.debug('Running in: Browser')
+  console.debug('store.isPersistent:', store.isPersistent) // true
+  console.debug('session.isPersistent:', session.isPersistent) // true
+} else if (memorio.isNode()) {
+  console.debug('Running in: Node.js')
+  console.debug('store.isPersistent:', store.isPersistent) // false (memory fallback)
+  console.debug('session.isPersistent:', session.isPersistent) // false (memory fallback)
+} else if (memorio.isDeno()) {
+  console.debug('Running in: Deno')
+  console.debug('store.isPersistent:', store.isPersistent) // false (memory fallback)
+  console.debug('session.isPersistent:', session.isPersistent) // false (memory fallback)
+} else if (memorio.isEdge()) {
+  console.debug('Running in: Edge Worker')
+  console.debug('store.isPersistent:', store.isPersistent) // true
+  console.debug('session.isPersistent:', session.isPersistent) // true
+}
+
+// Get detailed capabilities
+const caps = memorio.getCapabilities()
+console.debug('\nCapabilities:')
+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)
+
+// ============================================
+// CONTEXT ISOLATION (Server-Side)
+// ============================================
+
+console.debug('\n=== Context Isolation ===')
+console.debug('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.debug('\nUser A context:')
+console.debug('  state.name:', userAContext.state.name) // 'Mario'
+console.debug('  store.preferences:', userAContext.store.get('preferences')) // { theme: 'dark' }
+console.debug('  session.token:', userAContext.session.get('token')) // 'user-A-token'
+
+console.debug('\nUser B context:')
+console.debug('  state.name:', userBContext.state.name) // 'Luigi'
+console.debug('  store.preferences:', userBContext.store.get('preferences')) // { theme: 'light' }
+console.debug('  session.token:', userBContext.session.get('token')) // 'user-B-token'
+
+// Global state is separate from contexts
+console.debug('\nGlobal state (not affected by contexts):')
+console.debug('  state.name:', state.name) // undefined
+
+// List all contexts
+console.debug('\nActive contexts:', memorio.listContexts()) // ['user-A', 'user-B']
+
+// Cleanup - delete a context when done
+memorio.deleteContext('user-A')
+console.debug('After deleting user-A:', memorio.listContexts()) // ['user-B']
+
+// ============================================
+// USE CASE: EXPRESS/FASTIFY MIDDLEWARE EXAMPLE
+// ============================================
+
+console.debug('\n=== Server Use Case ===')
+console.debug(`
+// 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.debug('\nPlatform & Context example complete!')

package/examples/react-app.tsx

@@ -0,0 +1,362 @@
+/**
+ * Memorio React App Example
+ *
+ * This example shows how to use Memorio state in a React application.
+ *
+ * Run: npx ts-node --esm examples/react-app.tsx
+ * Or copy to your React project
+ */
+
+import React, { useState, useEffect } from 'react'
+import 'memorio'
+
+// ============================================
+// 1. SETUP - Import once at app start
+// ============================================
+
+// In your main App.tsx or index.js:
+// import 'memorio'
+
+// ============================================
+// 2. DEFINE YOUR STATE SHAPE
+// ============================================
+
+interface AppState {
+  user: {
+    name: string
+    email: string
+    avatar?: string
+  } | null
+  theme: 'light' | 'dark'
+  notifications: Notification[]
+  cart: CartItem[]
+  isLoading: boolean
+}
+
+interface Notification {
+  id: string
+  message: string
+  read: boolean
+}
+
+interface CartItem {
+  id: number
+  name: string
+  price: number
+  quantity: number
+}
+
+// ============================================
+// 3. USE STATE IN COMPONENTS
+// ============================================
+
+// ------------------------------
+// Header Component
+// ------------------------------
+function Header() {
+  // Using useObserver to react to state changes
+  const [theme, setTheme] = useState(state.theme)
+
+  useObserver(() => {
+    setTheme(state.theme)
+  }, [state.theme])
+
+  return (
+    <header className={`header header--${theme}`}>
+      <h1>My App</h1>
+      <button onClick={() => {
+        state.theme = state.theme === 'light' ? 'dark' : 'light'
+      }}>
+        Toggle Theme
+      </button>
+    </header>
+  )
+}
+
+// ------------------------------
+// User Profile Component
+// ------------------------------
+function UserProfile() {
+  const [user, setUser] = useState(state.user)
+
+  // Auto-discover all state changes
+  useObserver(() => {
+    setUser(state.user)
+  })
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
+
+  return (
+    <div className="profile">
+      <img src={user.avatar} alt={user.name} />
+      <h2>{user.name}</h2>
+      <p>{user.email}</p>
+    </div>
+  )
+}
+
+// ------------------------------
+// Login Form Component
+// ------------------------------
+function LoginForm() {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+
+    // Set user state
+    state.user = {
+      name,
+      email,
+      avatar: `https://api.dicebear.com/7.x/avataaars/svg?seed=${name}`
+    }
+
+    // Also persist to store
+    store.set('lastUser', name)
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={name}
+        onChange={e => setName(e.target.value)}
+        placeholder="Name"
+      />
+      <input
+        value={email}
+        onChange={e => setEmail(e.target.value)}
+        placeholder="Email"
+      />
+      <button type="submit">Login</button>
+    </form>
+  )
+}
+
+// ------------------------------
+// Shopping Cart Component
+// ------------------------------
+function Cart() {
+  const [items, setItems] = useState<CartItem[]>([])
+
+  useObserver(() => {
+    setItems(state.cart || [])
+  }, [state.cart])
+
+  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+
+  return (
+    <div className="cart">
+      <h2>Cart ({items.length})</h2>
+      {items.map(item => (
+        <div key={item.id}>
+          {item.name} - ${item.price} x {item.quantity}
+        </div>
+      ))}
+      <strong>Total: ${total}</strong>
+      <div style={{ marginTop: '1rem' }}>
+        <AddToCartButton
+          product={{ id: 1, name: 'Sample Product', price: 9.99 }}
+        />
+      </div>
+    </div>
+  )
+}
+
+// ------------------------------
+// Add to Cart Button
+// ------------------------------
+function AddToCartButton({ product }: { product: { id: number, name: string, price: number } }) {
+  return (
+    <button onClick={() => {
+      // Initialize cart if not exists
+      if (!state.cart) {
+        state.cart = []
+      }
+
+      // Add item or increment quantity
+      const existing = state.cart.find(item => item.id === product.id)
+      if (existing) {
+        existing.quantity++
+      } else {
+        state.cart.push({
+          id: product.id,
+          name: product.name,
+          price: product.price,
+          quantity: 1
+        })
+      }
+    }}>
+      Add to Cart
+    </button>
+  )
+}
+
+// ------------------------------
+// Notifications Component
+// ------------------------------
+function Notifications() {
+  const [notifications, setNotifications] = useState<Notification[]>([])
+
+  useObserver(() => {
+    setNotifications(state.notifications || [])
+  }, [state.notifications])
+
+  const unread = notifications.filter(n => !n.read).length
+
+  return (
+    <div className="notifications">
+      <span>🔔 {unread} unread</span>
+      {notifications.map(n => (
+        <div key={n.id} className={n.read ? 'read' : 'unread'}>
+          {n.message}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ------------------------------
+// Settings Component
+// ------------------------------
+function Settings() {
+  const [theme] = useState(state.theme)
+  const [savedSettings, setSavedSettings] = useState<any>(null)
+
+  // Load saved settings from store
+  useEffect(() => {
+    const settings = store.get('appSettings')
+    if (settings) {
+      setSavedSettings(settings)
+    }
+  }, [])
+
+  const saveSettings = () => {
+    store.set('appSettings', { theme: state.theme })
+    alert('Settings saved!')
+  }
+
+  return (
+    <div className="settings">
+      <h2>Settings</h2>
+
+      <label>
+        Theme:
+        <select
+          value={theme}
+          onChange={e => state.theme = e.target.value as 'light' | 'dark'}
+        >
+          <option value="light">Light</option>
+          <option value="dark">Dark</option>
+        </select>
+      </label>
+
+      <button onClick={saveSettings}>Save Settings</button>
+
+      {savedSettings && (
+        <p>Saved: {savedSettings.theme}</p>
+      )}
+    </div>
+  )
+}
+
+// ============================================
+// 4. MAIN APP COMPONENT
+// ============================================
+
+function App() {
+  // Initialize default state
+  useEffect(() => {
+    // Load theme from store
+    const savedTheme = store.get('appSettings')?.theme
+    if (savedTheme) {
+      state.theme = savedTheme
+    } else {
+      state.theme = 'light'
+    }
+
+    // Initialize notifications
+    state.notifications = [
+      { id: '1', message: 'Welcome to Memorio!', read: false },
+      { id: '2', message: 'Check out our new features', read: false }
+    ]
+
+    // Check for returning user
+    const lastUser = store.get('lastUser')
+    if (lastUser) {
+      console.debug('Welcome back,', lastUser)
+    }
+  }, [])
+
+  return (
+    <div className={`app app--${state.theme}`}>
+      <Header />
+      <main>
+        {state.user ? (
+          <>
+            <UserProfile />
+            <Cart />
+            <Notifications />
+            <Settings />
+
+            <button onClick={() => {
+              // Logout - clear user but keep settings
+              state.user = null
+            }}>
+              Logout
+            </button>
+          </>
+        ) : (
+          <LoginForm />
+        )}
+      </main>
+    </div>
+  )
+}
+
+export default App
+
+// ============================================
+// 5. USAGE SUMMARY
+// ============================================
+
+/*
+MEMORIO REACT USAGE GUIDE:
+
+1. IMPORT ONCE (index.js or App.tsx):
+   import 'memorio'
+
+2. SET STATE:
+   state.user = { name: 'Mario', email: 'mario@example.com' }
+   state.theme = 'dark'
+   state.cart = []
+
+3. READ STATE:
+   const value = state.user.name
+   const theme = state.theme
+
+4. REACT TO CHANGES:
+   useObserver(() => {
+     console.debug('State changed!')
+   }, [state.user])
+
+5. AUTO-DISCOVERY (watch all):
+   useObserver(() => {
+     console.debug(state.user, state.theme)
+   })
+
+6. PERSIST DATA:
+   store.set('settings', { theme: 'dark' })
+   const settings = store.get('settings')
+
+7. SESSION DATA (cleared on tab close):
+   session.set('token', 'abc123')
+   const token = session.get('token')
+
+8. CLEAR DATA:
+   state.removeAll()     // Clear all state
+   store.removeAll()     // Clear all persisted
+   session.removeAll()   // Clear all session
+*/

package/examples/react-observer.tsx

@@ -0,0 +1,63 @@
+/**
+ * react-observer.tsx
+ *
+ * Scenario: a React component reading reactive `state`. Shows both
+ * `useObserver` modes and when to prefer each, plus `typed<T>()` +
+ * `registerSchema()` for the paths you don't want to fail silently on a
+ * typo or a later rename.
+ */
+import 'memorio'
+import { useReducer } from 'react'
+
+interface AppState {
+  counter: number
+  user: { name: string; email: string }
+}
+
+// Compile-time safety: same Proxy as the global `state`, no duplicated store.
+const app = memorio.typed<AppState>()
+
+// Runtime safety: reject writes that don't match the shape, independent of
+// whatever calls it (including code you didn't write).
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+  },
+})
+
+export function Counter() {
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
+
+  // Auto-discovery mode: re-runs when any state path *touched inside the
+  // callback* changes. Convenient, but re-runs on anything you read there —
+  // don't reach for it in a callback that reads many unrelated paths.
+  useObserver(() => {
+    forceUpdate()
+  }, state.counter)
+
+  return (
+    <div>
+      <span>Count: {app.counter}</span>
+      <button onClick={() => { app.counter += 1 }}>+1</button>
+    </div>
+  )
+}
+
+export function UserBadge() {
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
+
+  // Explicit deps mode: only re-runs when the listed path(s) change — use
+  // this when you want precise control instead of auto-discovery.
+  useObserver(() => {
+    forceUpdate()
+  }, [state.user])
+
+  return <span>{app.user?.name ?? 'Guest'}</span>
+}
+
+// Rejected at write time by the schema registered above:
+// app.user = { name: 'Sara' }              // ❌ missing "email"
+// app.user = { name: 'Sara', email: 'x@y.com' }  // ✅

package/examples/semantic-memory.ts

@@ -0,0 +1,60 @@
+/**
+ * semantic-memory.ts
+ *
+ * Scenario: an LLM-backed app that needs to remember facts about a user
+ * with confidence, source, and expiry — and later retrieve only what's
+ * relevant to the current task.
+ *
+ * Important: `memory.context()` ranks by tags/type/confidence/recency.
+ * It is NOT embedding-based semantic search — don't build a feature that
+ * assumes free-text meaning-based retrieval on top of this alone.
+ */
+import { memorio } from 'memorio'
+
+export async function rememberPreference(
+  key: string,
+  value: unknown,
+  opts: { confidence: number; source: string; tags: string[] }
+) {
+  await memorio.memory.remember(key, value, {
+    type: 'preference',
+    scope: 'local',
+    ...opts,
+  })
+}
+
+export async function correctPreference(key: string, newValue: unknown, confidence: number) {
+  // update() supersedes, it doesn't overwrite — the old entry becomes
+  // status: 'superseded' and stays queryable for history/audit purposes.
+  await memorio.memory.update(key, newValue, { confidence })
+}
+
+export async function getRelevantContext(tags: string[]) {
+  // This is rule-based retrieval, not semantic similarity search. It's the
+  // right tool for "give me what's tagged/confident/recent enough," not for
+  // "find the memory that means the same thing as this new sentence."
+  return memorio.memory.context({
+    tags,
+    types: ['preference', 'decision'],
+    minConfidence: 0.7,
+    maxEntries: 10,
+  })
+}
+
+// If the task genuinely needs meaning-based retrieval over free text (e.g.
+// "find prior notes about a similar problem" rather than "find notes tagged
+// X with confidence > Y"), pair this with a dedicated embedding store for
+// the similarity search, and keep using memorio.memory for the lifecycle
+// metadata (confidence, TTL, supersession) on top of whatever it finds —
+// don't simulate similarity search with context() alone.
+
+// Usage:
+// await rememberPreference('user.language', 'Italian', {
+//   confidence: 0.92,
+//   source: 'conversation',
+//   tags: ['user', 'ui'],
+// })
+//
+// await correctPreference('user.language', 'English', 0.95)
+//
+// const ctx = await getRelevantContext(['user'])

package/examples/session-advanced.ts

@@ -0,0 +1,91 @@
+/**
+ * Memorio Session Advanced Example
+ *
+ * This example shows advanced session (sessionStorage) operations.
+ * Session data is cleared when the browser tab closes.
+ *
+ * Run: npx ts-node examples/session-advanced.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// CHECK PERSISTENCE
+// ============================================
+
+console.debug('=== Session Persistence Check ===')
+console.debug('Is persistent (survives tab close):', session.isPersistent)
+// In browser: true (sessionStorage)
+// In Node.js/Deno: false (memory fallback)
+
+if (!session.isPersistent) {
+  console.debug('⚠️ Warning: Using in-memory storage. Data will be lost on process restart!')
+}
+
+// ============================================
+// AUTHENTICATION
+// ============================================
+
+// Store auth token (temporary - cleared when tab closes)
+session.set('authToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
+session.set('userId', 12345)
+
+// Check if user is logged in
+const token = session.get('authToken')
+if (token) {
+  console.debug('User is logged in, token:', token.substring(0, 20) + '...')
+}
+
+// ============================================
+// FORM PROGRESS
+// ============================================
+
+// Save form draft
+session.set('formDraft', {
+  name: 'Mario',
+  email: 'mario@example.com',
+  message: 'Hello world!'
+})
+
+// Restore on page refresh
+const draft = session.get('formDraft')
+if (draft) {
+  console.debug('Restored draft:', draft)
+}
+
+// ============================================
+// SHOPPING CART
+// ============================================
+
+// Store cart items (temporary)
+session.set('cart', [
+  { id: 1, name: 'Super Mushroom', price: 99, qty: 2 },
+  { id: 2, name: 'Fire Flower', price: 199, qty: 1 }
+])
+
+// Calculate total
+const cart = session.get('cart') || []
+const total = cart.reduce((sum, item) => sum + (item.price * item.qty), 0)
+console.debug('Cart total:', total)
+
+// ============================================
+// SESSION SIZE
+// ============================================
+
+// Get session storage size
+console.debug('Session size:', session.size(), 'bytes')
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove specific item
+session.remove('formDraft')
+
+// Clear all session data (logout)
+// session.removeAll()
+
+// Or use alias
+// session.clearAll()
+
+console.debug('Session advanced example complete!')