memorio 4.9.35 → 5.0.0

package/examples/state-advanced.ts

@@ -1,89 +1,89 @@
-/**
- * Memorio State Advanced Example
- *
- * This example shows advanced state features: locking, path tracking, and nesting.
- *
- * Run: npx ts-node examples/state-advanced.ts
- */
-
-import 'memorio'
-
-// ============================================
-// NESTED OBJECTS
-// ============================================
-
-// Create nested state
-state.user = {
-  name: 'Mario',
-  profile: {
-    email: 'mario@example.com',
-    settings: {
-      theme: 'dark',
-      notifications: true
-    }
-  }
-}
-
-// Access nested values
-console.debug('User name:', state.user.name)
-console.debug('Email:', state.user.profile.email)
-console.debug('Theme:', state.user.profile.settings.theme)
-
-// ============================================
-// ARRAYS
-// ============================================
-
-// State arrays work like regular arrays
-state.items = [1, 2, 3]
-state.items.push(4)
-console.debug('Items:', state.items) // [1, 2, 3, 4]
-
-state.users = [
-  { name: 'Mario', id: 1 },
-  { name: 'Luigi', id: 2 }
-]
-state.users.push({ name: 'Peach', id: 3 })
-console.debug('Users:', state.users)
-
-// ============================================
-// LOCKING STATE
-// ============================================
-
-// Lock a value to prevent modifications
-state.config = { maxUsers: 100, timeout: 30 }
-state.config.lock()
-
-// This will fail:
-// state.config.maxUsers = 200 // Error: state 'config' is locked
-
-console.debug('Config locked:', state.config)
-
-// ============================================
-// PATH TRACKING
-// ============================================
-
-// Get path information
-console.debug('Path:', state.user.__path) // "state.user"
-
-// Use path tracker for debugging
-const path = state.user.profile
-console.debug('Profile path:', path.email.toString()) // "state.user.profile.email"
-
-// ============================================
-// LIST ALL STATES
-// ============================================
-
-// Get all current state keys
-console.debug('All states:', state.list)
-
-// ============================================
-// REMOVE STATE
-// ============================================
-
-// Remove specific state
-state.remove('items')
-
-// Remove all states
-// state.removeAll()
-
-console.debug('State advanced example complete!')
+/**
+ * Memorio State Advanced Example
+ *
+ * This example shows advanced state features: locking, path tracking, and nesting.
+ *
+ * Run: npx ts-node examples/state-advanced.ts
+ */
+
+import { state } from 'memorio'
+
+// ============================================
+// NESTED OBJECTS
+// ============================================
+
+// Create nested state
+state.user = {
+  name: 'Mario',
+  profile: {
+    email: 'mario@example.com',
+    settings: {
+      theme: 'dark',
+      notifications: true
+    }
+  }
+}
+
+// Access nested values
+console.debug('User name:', state.user.name)
+console.debug('Email:', state.user.profile.email)
+console.debug('Theme:', state.user.profile.settings.theme)
+
+// ============================================
+// ARRAYS
+// ============================================
+
+// State arrays work like regular arrays
+state.items = [1, 2, 3]
+state.items.push(4)
+console.debug('Items:', state.items) // [1, 2, 3, 4]
+
+state.users = [
+  { name: 'Mario', id: 1 },
+  { name: 'Luigi', id: 2 }
+]
+state.users.push({ name: 'Peach', id: 3 })
+console.debug('Users:', state.users)
+
+// ============================================
+// LOCKING STATE
+// ============================================
+
+// Lock a value to prevent modifications
+state.config = { maxUsers: 100, timeout: 30 }
+state.config.lock()
+
+// This will fail:
+// state.config.maxUsers = 200 // Error: state 'config' is locked
+
+console.debug('Config locked:', state.config)
+
+// ============================================
+// PATH TRACKING
+// ============================================
+
+// Get path information
+console.debug('Path:', state.user.__path) // "state.user"
+
+// Use path tracker for debugging
+const path = state.user.profile
+console.debug('Profile path:', path.email.toString()) // "state.user.profile.email"
+
+// ============================================
+// LIST ALL STATES
+// ============================================
+
+// Get all current state keys
+console.debug('All states:', state.list)
+
+// ============================================
+// REMOVE STATE
+// ============================================
+
+// Remove specific state
+state.remove('items')
+
+// Remove all states
+// state.removeAll()
+
+console.debug('State advanced example complete!')

package/examples/store-advanced.ts

@@ -1,117 +1,117 @@
-/**
- * Memorio Store Advanced Example
- *
- * This example shows advanced store (localStorage) operations.
- *
- * Run: npx ts-node examples/store-advanced.ts
- */
-
-import 'memorio'
-
-// ============================================
-// CHECK PERSISTENCE
-// ============================================
-
-console.debug('=== Store Persistence Check ===')
-console.debug('Is persistent (survives restart):', store.isPersistent)
-// In browser: true (localStorage)
-// In Node.js/Deno: false (memory fallback)
-
-if (!store.isPersistent) {
-  console.debug('⚠️ Warning: Using in-memory storage. Data will be lost on restart!')
-}
-
-// ============================================
-// PERSIST USER PREFERENCES
-// ============================================
-
-// Save user preferences
-store.set('preferences', {
-  theme: 'dark',
-  language: 'en',
-  notifications: true,
-  fontSize: 16
-})
-
-// ============================================
-// CHECK AND LOAD PREFERENCES
-// ============================================
-
-const savedPrefs = store.get('preferences')
-if (savedPrefs) {
-  console.debug('Loaded preferences:', savedPrefs)
-} else {
-  console.debug('No preferences found, using defaults')
-  store.set('preferences', { theme: 'light', language: 'en' })
-}
-
-// ============================================
-// STORAGE QUOTA
-// ============================================
-
-// Get storage size
-const currentSize = store.size()
-console.debug('Current storage size:', currentSize, 'kilobytes')
-
-// ============================================
-// ALIAS METHODS
-// ============================================
-
-// store.delete() is alias for store.remove()
-store.set('temp', 'value')
-store.delete('temp')
-
-// store.clearAll() is alias for store.removeAll()
-// store.clearAll()
-
-// ============================================
-// ERROR HANDLING
-// ============================================
-
-// Try-catch for large data
-try {
-  // Store large data
-  const largeData = {
-    items: Array(1000).fill(null).map((_, i) => ({ id: i, data: 'x'.repeat(100) }))
-  }
-  store.set('largeData', largeData)
-  console.debug('Large data stored successfully')
-} catch (error) {
-  console.error('Storage full:', error)
-}
-
-// ============================================
-// DATA SERIALIZATION
-// ============================================
-
-// Store supports all JSON-serializable types
-store.set('string', 'hello')
-store.set('number', 42)
-store.set('boolean', true)
-store.set('array', [1, 2, 3])
-store.set('object', { nested: { value: 'deep' } })
-store.set('null', null)
-
-// Functions are not supported (logged as error)
-store.set('function', () => { }) // logs: "It's not secure to store functions."
-
-// ============================================
-// PRACTICAL EXAMPLE: APP STATE
-// ============================================
-
-// Save app state
-const appState = {
-  lastPage: '/dashboard',
-  sidebarOpen: true,
-  recentFiles: ['file1.txt', 'file2.pdf'],
-  lastSaved: Date.now()
-}
-store.set('appState', appState)
-
-// Load on next visit
-const restored = store.get('appState')
-if (restored) {
-  console.debug('Restored app state:', restored.lastPage)
-}
-
-console.debug('Store advanced example complete!')
+/**
+ * Memorio Store Advanced Example
+ *
+ * This example shows advanced store (localStorage) operations.
+ *
+ * Run: npx ts-node examples/store-advanced.ts
+ */
+
+import { store } from 'memorio'
+
+// ============================================
+// CHECK PERSISTENCE
+// ============================================
+
+console.debug('=== Store Persistence Check ===')
+console.debug('Is persistent (survives restart):', store.isPersistent)
+// In browser: true (localStorage)
+// In Node.js/Deno: false (memory fallback)
+
+if (!store.isPersistent) {
+  console.debug('⚠️ Warning: Using in-memory storage. Data will be lost on restart!')
+}
+
+// ============================================
+// PERSIST USER PREFERENCES
+// ============================================
+
+// Save user preferences
+store.set('preferences', {
+  theme: 'dark',
+  language: 'en',
+  notifications: true,
+  fontSize: 16
+})
+
+// ============================================
+// CHECK AND LOAD PREFERENCES
+// ============================================
+
+const savedPrefs = store.get('preferences')
+if (savedPrefs) {
+  console.debug('Loaded preferences:', savedPrefs)
+} else {
+  console.debug('No preferences found, using defaults')
+  store.set('preferences', { theme: 'light', language: 'en' })
+}
+
+// ============================================
+// STORAGE QUOTA
+// ============================================
+
+// Get storage size
+const currentSize = store.size()
+console.debug('Current storage size:', currentSize, 'kilobytes')
+
+// ============================================
+// ALIAS METHODS
+// ============================================
+
+// store.delete() is alias for store.remove()
+store.set('temp', 'value')
+store.delete('temp')
+
+// store.clearAll() is alias for store.removeAll()
+// store.clearAll()
+
+// ============================================
+// ERROR HANDLING
+// ============================================
+
+// Try-catch for large data
+try {
+  // Store large data
+  const largeData = {
+    items: Array(1000).fill(null).map((_, i) => ({ id: i, data: 'x'.repeat(100) }))
+  }
+  store.set('largeData', largeData)
+  console.debug('Large data stored successfully')
+} catch (error) {
+  console.error('Storage full:', error)
+}
+
+// ============================================
+// DATA SERIALIZATION
+// ============================================
+
+// Store supports all JSON-serializable types
+store.set('string', 'hello')
+store.set('number', 42)
+store.set('boolean', true)
+store.set('array', [1, 2, 3])
+store.set('object', { nested: { value: 'deep' } })
+store.set('null', null)
+
+// Functions are not supported (logged as error)
+store.set('function', () => { }) // logs: "It's not secure to store functions."
+
+// ============================================
+// PRACTICAL EXAMPLE: APP STATE
+// ============================================
+
+// Save app state
+const appState = {
+  lastPage: '/dashboard',
+  sidebarOpen: true,
+  recentFiles: ['file1.txt', 'file2.pdf'],
+  lastSaved: Date.now()
+}
+store.set('appState', appState)
+
+// Load on next visit
+const restored = store.get('appState')
+if (restored) {
+  console.debug('Restored app state:', restored.lastPage)
+}
+
+console.debug('Store advanced example complete!')

package/examples/sync.ts

@@ -0,0 +1,90 @@
+/**
+ * sync.ts
+ *
+ * Scenario: an app using `memorio.memory` that wants to survive being
+ * offline (data is born local, in the journal, and always readable) and
+ * mirror itself to a backend when a connection is available.
+ *
+ * The cloud is a transport/persistence provider here, never the source of
+ * truth - sync mirrors the local journal, it doesn't replace it. Provide
+ * your own `SyncProvider`; memorio doesn't ship one.
+ */
+import { memorio } from 'memorio'
+
+interface MemoryEntry {
+  key: string
+  value: unknown
+  confidence?: number
+  source?: string
+  scope?: 'device' | 'user' | 'shared'
+}
+
+interface SyncProvider {
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  pull?(since?: number): Promise<MemoryEntry[]>
+  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+
+const backendProvider: SyncProvider = {
+  push: ops =>
+    fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify(ops),
+      headers: { 'Content-Type': 'application/json' }
+    }).then(r => r.json()),
+
+  pull: since => fetch(`/api/sync?since=${since ?? 0}`).then(r => r.json()),
+
+  // Higher-confidence entry wins locally; for 'shared' scope the provider
+  // (i.e. your backend) makes the final call instead.
+  resolve: async op => (op.confidence ?? 0) >= 0.8 ? 'local' : 'remote'
+}
+
+export async function configureSync(namespace: string) {
+  // `scope: 'device'` data never syncs (sticky to this device) - only
+  // 'user' and 'shared' scoped entries flow through the provider below.
+  memorio.memory.configure({
+    namespace, // e.g. `user:123:device:abc` - partitions the local journal
+    provider: backendProvider,
+    auto: true // auto-replay the journal on focus/online (default: true)
+  })
+
+  await memorio.memory.ready
+}
+
+export async function rememberAndSync(key: string, value: unknown) {
+  // Local-first: this resolves immediately from the local store, no
+  // network round-trip required.
+  await memorio.memory.remember(key, value, { scope: 'user', source: 'app' })
+}
+
+// ---------------------------------------------------------------------------
+// The journal: the durable op log that drives cloud reconciliation
+// ---------------------------------------------------------------------------
+
+export async function inspectPendingOps() {
+  const pending = await memorio.memory.journal.pending()
+  console.debug('Operations waiting to sync:', pending)
+  return pending
+}
+
+export async function forceReplay() {
+  // Pushes pending() to the provider, marks synced entries, and pulls if
+  // the provider implements it. Normally triggered automatically (`auto:
+  // true`) on focus/online - call this manually to sync on demand instead.
+  const ack = await memorio.memory.journal.replay()
+  console.debug('Sync result:', ack)
+  return ack
+}
+
+export async function resetJournal() {
+  // Wipes the current namespace's journal only - does not touch the
+  // memory entries themselves, just the pending sync log.
+  await memorio.memory.journal.clear()
+}
+
+// Usage:
+// await configureSync('user:123:device:abc')
+// await rememberAndSync('user.language', 'Italian')
+// await inspectPendingOps()
+// await forceReplay()