memorio 4.9.35 → 5.0.0

package/examples/typed-and-schema.ts

@@ -1,100 +1,102 @@
-/**
- * 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' }
+/**
+ * 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: explicit named imports give you both the APIs and the
+ * `memorio` namespace object without polluting `globalThis`.
+ *
+ * @module memorio/examples/typed-and-schema
+ */
+
+import { memorio, state } from 'memorio'
+
+// =============================================================================
+// TYPED STORES - compile-time type safety on the 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
+// =============================================================================
+
+// `app` shares the same identity as `state` - same Proxy instance
+
+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

@@ -1,141 +1,140 @@
-/**
- * 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!')
+/**
+ * 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 (e.g. Vite/CRA), not directly with ts-node.
+ */
+
+import { useState } from 'react'
+import { useObserver, state, store } from 'memorio'
+
+// ============================================
+// BASIC USEOBSERVER
+// ============================================
+
+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: unknown) => {
+    setLocalData(newValue)
+  }, [state.data])
+
+  return <div>{localData}</div>
+}
+
+// ============================================
+// PRACTICAL EXAMPLE
+// ============================================
+
+// Real-world React component example:
+interface Todo {
+  text: string
+  done: boolean
+}
+
+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: string) => {
+    state.todos = [...(state.todos || []), { text, done: false }]
+  }
+
+  const toggleTodo = (index: number) => {
+    const todos: Todo[] = [...state.todos]
+    todos[index].done = !todos[index].done
+    state.todos = todos
+  }
+
+  const filteredTodos: Todo[] = (state.todos || []).filter((t: Todo) =>
+    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 as HTMLInputElement).value)
+            ;(e.target as HTMLInputElement).value = ''
+          }
+        }}
+      />
+    </div>
+  )
+}
+
+export { Counter, UserProfile, AutoDiscovery, SyncedComponent, TodoApp }