memorio 4.9.7 → 4.9.10

package/examples/sqlite-batched-writes.ts

@@ -0,0 +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.

package/examples/state-advanced.ts

@@ -0,0 +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!')

package/examples/store-advanced.ts

@@ -0,0 +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, 'bytes')
+
+// ============================================
+// 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/typed-and-schema.ts

@@ -0,0 +1,100 @@
+/**
+ * MEMORIO TYPED STORES + SCHEMA VALIDATION - LIVE EXAMPLES
+ *
+ * This file demonstrates every code snippet used in docs/markdown/SCHEMA.md
+ * and docs/markdown/TYPED.md. It is real, compiling TypeScript.
+ *
+ * Primary usage: `import 'memorio'` (side-effect import) makes all globals
+ * available, including the `memorio` namespace object.
+ *
+ * @module memorio/examples/typed-and-schema
+ */
+
+import 'memorio'
+
+// =============================================================================
+// TYPED STORES - compile-time type safety on the global `state` proxy
+// =============================================================================
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+app.items = ['apple', 'banana']
+
+state.user.name = 'Luigi'
+state.counter = 100
+const currentTheme: 'light' | 'dark' = app.theme
+void currentTheme
+
+// =============================================================================
+// SCHEMA VALIDATION - runtime guards that reject invalid state writes
+// =============================================================================
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+memorio.registerSchema('theme', { enum: ['light', 'dark'] })
+
+memorio.registerSchema('items', {
+  type: 'array',
+  validator: (val: any) => Array.isArray(val) && val.every((i: any) => typeof i === 'string')
+    ? true
+    : 'items must be an array of strings'
+})
+
+memorio.registerSchema('counter', (val: any) => {
+  if (typeof val !== 'number') return 'counter must be a number'
+  if (val < 0) return 'counter must be >= 0'
+  return true
+})
+
+// These writes are rejected at runtime:
+state.user = { name: 'Sara' }        // missing 'email' - rejected
+state.theme = 'purple'                // not in enum - rejected
+state.counter = -5                    // fails custom validator - rejected
+
+// These pass:
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }
+state.theme = 'light'
+state.counter = 5
+
+// Manual validation:
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+memorio.validate('theme', 'dark')
+
+memorio.listSchemas()
+memorio.unregisterSchema('counter')
+
+// =============================================================================
+// TYPED + SCHEMA - combine both for full safety
+// =============================================================================
+
+memorio.registerSchema('profile', {
+  type: 'object',
+  required: ['bio'],
+  properties: {
+    bio: { type: 'string', min: 1 },
+    avatar: { type: 'string' }
+  }
+})
+
+interface ProfileState {
+  profile: { bio: string; avatar?: string }
+}
+
+const typedProfile = memorio.typed<ProfileState>()
+typedProfile.profile = { bio: 'Developer', avatar: 'pic.png' }

package/examples/useObserver.tsx

@@ -0,0 +1,141 @@
+/**
+ * Memorio useObserver Example
+ *
+ * This example demonstrates the useObserver hook for React.
+ * useObserver automatically tracks state changes and triggers re-renders.
+ *
+ * Note: This example requires React to be present in the environment.
+ * Run in a React environment.
+ */
+
+import 'memorio'
+
+// ============================================
+// BASIC USEOBSERVER
+// ============================================
+
+// Example 1: Watch single value
+useObserver(callback, [state.value])
+
+function Counter() {
+  useObserver(() => {
+    console.debug('Count changed:', state.count)
+  }, [state.count])
+
+  return <div>{state.count} </div>
+}
+
+// ============================================
+// MULTIPLE DEPENDENCIES
+// ============================================
+
+// Example 2: Watch multiple values
+function UserProfile() {
+  useObserver(() => {
+    console.debug('User or theme changed')
+  }, [state.user, state.theme])
+
+  return <div>{state.user.name} </div>
+}
+
+// ============================================
+// AUTO-DISCOVERY
+// ============================================
+
+// Example 3: No dependencies - auto-discovers all state access
+function AutoDiscovery() {
+  useObserver(() => {
+    // Automatically tracks state.user, state.items, state.count
+    console.debug('Changed:', state.user.name, state.items.length, state.count)
+  })
+
+  return <div>{state.user.name} </div>
+}
+
+// ============================================
+// SYNC WITH USESTATE
+// ============================================
+
+// Example 4: Sync with useState
+function SyncedComponent() {
+  const [localData, setLocalData] = useState(null)
+
+  useObserver((newValue) => {
+    setLocalData(newValue)
+  }, [state.data])
+
+  return <div>{localData} </div>
+}
+
+// ============================================
+// PRACTICAL EXAMPLE
+// ============================================
+
+// Real-world React component example:
+import 'memorio'
+
+function TodoApp() {
+  // Track todos
+  useObserver(() => {
+    console.debug('Todos updated:', state.todos)
+    // Optionally save to store
+    store.set('todos', state.todos)
+  }, [state.todos])
+
+  // Track filter
+  useObserver(() => {
+    console.debug('Filter changed:', state.filter)
+  }, [state.filter])
+
+  const addTodo = (text) => {
+    state.todos = [...(state.todos || []), { text, done: false }]
+  }
+
+  const toggleTodo = (index) => {
+    const todos = [...state.todos]
+    todos[index].done = !todos[index].done
+    state.todos = todos
+  }
+
+  const filteredTodos = (state.todos || []).filter(t =>
+    state.filter === 'all' ||
+    (state.filter === 'done' && t.done) ||
+    (state.filter === 'todo' && !t.done)
+  )
+
+  return (
+    <div>
+      <select
+        value={state.filter}
+        onChange={e => state.filter = e.target.value}
+      >
+        <option value="all" > All </option>
+        < option value="done" > Done </option>
+        < option value="todo" > Todo </option>
+      </select>
+      <ul>
+        {
+          filteredTodos.map((todo, i) => (
+            <li
+              key={i}
+              onClick={() => toggleTodo(i)}
+              style={{ textDecoration: todo.done ? 'line-through' : 'none' }
+              }
+            >
+              {todo.text}
+            </li>
+          ))}
+      </ul>
+      < input
+        onKeyDown={e => {
+          if (e.key === 'Enter') {
+            addTodo(e.target.value)
+            e.target.value = ''
+          }
+        }}
+      />
+    </div>
+  )
+}
+
+console.debug('useObserver example - run in React environment!')