memorio 4.9.10 → 4.9.31

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/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.

package/examples/react-observer.tsx

@@ -1,63 +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' }  // ✅
+/**
+ * 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

@@ -1,60 +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'])
+/**
+ * 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

@@ -73,7 +73,7 @@ console.debug('Cart total:', total)
 // ============================================
 
 // Get session storage size
-console.debug('Session size:', session.size(), 'bytes')
+console.debug('Session size:', session.size(), 'kilobytes')
 
 // ============================================
 // CLEANUP

package/examples/sqlite-batched-writes.ts

@@ -1,57 +1,57 @@
-/**
- * sqlite-batched-writes.ts
- *
- * Scenario: importing or writing many rows into memorio's sqlite layer.
- *
- * Persistence there serializes the ENTIRE database on every flush — not
- * incremental. Calling a persisting write inside a per-row loop is the
- * single most common way to accidentally make this layer slow.
- */
-import { memorio } from 'memorio'
-
-interface UserRow {
-  id: number
-  name: string
-  role: string
-}
-
-export async function importUsers(users: UserRow[]) {
-  await memorio.sqlite.ready
-  await memorio.sqlite.db.create('app', { persistence: true })
-
-  await memorio.sqlite.query.run(
-    'app',
-    `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, role TEXT)`
-  )
-
-  // Bad: this would serialize the whole DB after every single insert.
-  //
-  // for (const user of users) {
-  //   await memorio.sqlite.query.run('app', 'INSERT INTO users ...', [...])
-  //   await memorio.sqlite.db.flush('app') // <- don't do this per row
-  // }
-
-  // Good: run every insert first, persist once after the batch.
-  for (const user of users) {
-    await memorio.sqlite.query.run(
-      'app',
-      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
-      [user.id, user.name, user.role]
-    )
-  }
-
-  // Persist explicitly, once, after the whole batch — check the installed
-  // version's API for the exact flush/persist call name if it differs from
-  // automatic persistence-on-close.
-  const admins = await memorio.sqlite.query.select(
-    'app',
-    `SELECT * FROM users WHERE role = ?`,
-    ['admin']
-  )
-
-  return admins
-}
-
-// For read-heavy or scratch-space use where durability doesn't matter,
-// skip { persistence: true } entirely — sqlite runs in memory by default,
-// which avoids the serialize cost altogether.
+/**
+ * sqlite-batched-writes.ts
+ *
+ * Scenario: importing or writing many rows into memorio's sqlite layer.
+ *
+ * Persistence there serializes the ENTIRE database on every flush - not
+ * incremental. Calling a persisting write inside a per-row loop is the
+ * single most common way to accidentally make this layer slow.
+ */
+import { memorio } from 'memorio'
+
+interface UserRow {
+  id: number
+  name: string
+  role: string
+}
+
+export async function importUsers(users: UserRow[]) {
+  await memorio.sqlite.ready
+  await memorio.sqlite.db.create('app', { persistence: true })
+
+  await memorio.sqlite.query.run(
+    'app',
+    `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, role TEXT)`
+  )
+
+  // Bad: this would serialize the whole DB after every single insert.
+  //
+  // for (const user of users) {
+  //   await memorio.sqlite.query.run('app', 'INSERT INTO users ...', [...])
+  //   await memorio.sqlite.db.flush('app') // <- don't do this per row
+  // }
+
+  // Good: run every insert first, persist once after the batch.
+  for (const user of users) {
+    await memorio.sqlite.query.run(
+      'app',
+      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
+      [user.id, user.name, user.role]
+    )
+  }
+
+  // Persist explicitly, once, after the whole batch - check the installed
+  // version's API for the exact flush/persist call name if it differs from
+  // automatic persistence-on-close.
+  const admins = await memorio.sqlite.query.select(
+    'app',
+    `SELECT * FROM users WHERE role = ?`,
+    ['admin']
+  )
+
+  return admins
+}
+
+// For read-heavy or scratch-space use where durability doesn't matter,
+// skip { persistence: true } entirely - sqlite runs in memory by default,
+// which avoids the serialize cost altogether.

package/examples/store-advanced.ts

@@ -51,7 +51,7 @@ if (savedPrefs) {
 
 // Get storage size
 const currentSize = store.size()
-console.debug('Current storage size:', currentSize, 'bytes')
+console.debug('Current storage size:', currentSize, 'kilobytes')
 
 // ============================================
 // ALIAS METHODS