memorio 4.9.31 → 5.0.0

package/markdown/TYPED.md

@@ -0,0 +1,165 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Typed Stores - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation.
+
+It's a **zero-runtime-cost** wrapper: the returned object is the *exact same* Proxy as `globalThis.state`, just with TypeScript types applied via a generic.
+
+---
+
+## Quick Start
+
+```typescript
+import { memorio, state, typed, useObserver } from 'memorio'
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+// Type-checked at compile time:
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+
+// TypeScript errors:
+// app.user = { name: 42 }            // age missing, name wrong type
+// app.theme = 'purple'               // not a valid literal
+```
+
+---
+
+## Why use typed stores?
+
+| Without typed | With `memorio.typed<T>()` |
+|---|---|
+| `state.user = { name: 42 }` - runs silently, bug at runtime | `app.user = { name: 42 }` - TypeScript error at compile time |
+| No autocomplete on `state.user.email` | Full IntelliSense: properties, types, method suggestions |
+| Rename `user` to `profile` - no compiler warning anywhere | Every `app.user` access flagged as an error |
+| AI-generated code lacks guardrails | AI gets autocomplete and type feedback inline |
+
+---
+
+## Combine with Schema Validation
+
+Typed stores catch type errors at compile time; schema validation catches invalid values at runtime. Together they form a **defense-in-depth** strategy:
+
+```typescript
+import { memorio, state } from 'memorio'
+
+interface ProfileState {
+  profile: { bio: string; avatar?: string }
+}
+
+const app = memorio.typed<ProfileState>()
+
+memorio.registerSchema('profile', {
+  type: 'object',
+  required: ['bio'],
+  properties: {
+    bio: { type: 'string', min: 1 },
+    avatar: { type: 'string' }
+  }
+})
+
+app.profile = { bio: 'Developer', avatar: 'pic.png' } // ✅ type + schema pass
+app.profile = { avatar: 'pic.png' }                  // ❌ TypeScript: bio missing
+                                                     // ❌ Runtime: bio required
+```
+
+See [Schema Validation](SCHEMA.md) for runtime validation details.
+
+---
+
+## Named import variant
+
+`typed` is also available as a named export if you prefer explicit dependencies:
+
+```typescript
+import { typed } from 'memorio'
+
+const app = typed<AppState>()
+```
+
+The `memorio` namespace object is the same across both usage styles - named imports and the `memorio/global` entrypoint share the same runtime instances.
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.typed<T>()` | Generic type `T` | `T` | Returns the global `state` proxy cast to `T` |
+
+The returned object shares the same identity as `globalThis.state`:
+
+```typescript
+const app = memorio.typed<AppState>()
+console.debug(app === state) // true - same Proxy instance
+```
+
+---
+
+## React + typed stores
+
+Pair with the `useObserver` hook for type-safe, reactive React components:
+
+```tsx
+import { memorio, state, useObserver } from 'memorio'
+import { useReducer } from 'react'
+
+interface AppState {
+  user: { name: string; age: number }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+function UserProfile() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  useObserver(forceUpdate, [state.user.name])
+
+  return (
+    <div>
+      <h1>{app.user.name}</h1>
+      <span>Theme: {app.theme}</span>
+    </div>
+  )
+}
+```
+
+---
+
+## Best Practices
+
+1. **Define your AppState at the root** of your app and import it everywhere:
+
+   ```typescript
+   // types/app-state.ts
+   export interface AppState {
+     user: { name: string; email: string }
+     theme: 'light' | 'dark'
+   }
+   ```
+
+   ```typescript
+   // anywhere in your app
+    import { memorio } from 'memorio'
+    import type { AppState } from '../types/app-state'
+    const app = memorio.typed<AppState>()
+   ```
+
+2. **Layer schema validation on top** for runtime safety, especially for data coming from APIs or user input.
+
+3. **Use alongside `memorio.help()`** (via `import 'memorio/global'`) to list available globals during development.

package/markdown/USEOBSERVER.md

@@ -0,0 +1,257 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# useObserver - Memorio
+
+> ⚛️ **React Only**: This is a React hook and only works within React components
+
+useObserver is a React hook for observing state changes. It automatically subscribes to state changes and includes powerful auto-discovery features.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { useObserver, state } from 'memorio';
+```
+
+> **Global API**: `import 'memorio/global'` is the opt-in entrypoint that also exposes `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+function Counter() {
+  // Direct values work! ✅
+  useObserver(() => {
+    console.debug('Counter changed:', state.counter);
+  }, [state.counter]);
+
+  return <div>{state.counter}</div>;
+}
+```
+
+### Auto-Discovery (Magic Mode)
+
+```javascript
+// Pass your callback WITHOUT dependencies - it auto-discovers!
+function MyComponent() {
+  useObserver(() => {
+    // This will automatically track ALL state properties used inside
+    console.debug('Something changed:', state.user.name, state.items.length);
+  });
+
+  return <div>{state.user.name}</div>;
+}
+```
+
+### Example 2: Intermediate
+
+```javascript
+function UserProfile() {
+  const [localState, setLocalState] = useState(null);
+
+  useObserver(() => {
+    setLocalState(state.user);
+  }, [state.user]);
+
+  return <div>{localState?.name}</div>;
+}
+```
+
+### Example 3: Advanced
+
+```javascript
+// Multiple watchers with array - works with direct values
+function MultiWatch() {
+  useObserver(() => {
+    console.debug('A or B changed:', state.a, state.b);
+  }, [state.a, state.b]); // Direct values work!
+  
+  return <div>{state.a} - {state.b}</div>;
+}
+
+// With string path (for store)
+function StoreWatcher() {
+  useObserver(() => {
+    console.debug('Store changed');
+  }, 'store.userPreferences');
+
+  return <div />;
+}
+```
+
+---
+
+## API Reference
+
+### useObserver(callback, deps)
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `callback` | `function` | Function to run on change |
+| `deps` | `function \| string \| array \| proxy` | State path(s) to watch. Supports: |
+| | | - Direct values: `state.counter` |
+| | | - String paths: `'state.counter'` |
+| | | - Arrow functions: `() => state.counter` |
+| | | - Arrays: `[state.a, state.b]` or `['state.a', 'state.b']` |
+| | | - Optional chaining: `[state?.one]` |
+
+### Primitive Values
+
+Direct primitive values are now fully supported:
+
+```javascript
+// Direct values work with primitives ✅
+useObserver(() => { console.debug('changed') }, [state.counter])
+
+// Arrays of primitives work ✅
+useObserver(() => { console.log(state.a, state.b) }, [state.a, state.b])
+
+// Optional chaining works ✅
+useObserver(() => { console.log(state?.one) }, [state?.one])
+
+// Strings still work ✅
+useObserver(() => { console.debug('changed') }, ['state.counter'])
+
+// Functions still work ✅
+useObserver(() => { console.debug('changed') }, [() => state.counter])
+```
+
+### Callback Parameters
+
+```javascript
+// Single value (no array needed)
+useObserver(
+  () => {
+    console.debug('Changed:', state.key);
+  }, state.key  // Single value works!
+);
+
+// Array of values
+useObserver(
+  () => {
+    console.debug('Changed:', state.key);
+  }, [state.key]  // Array also works!
+);
+```
+
+### Auto-Discovery Mode
+
+When `deps` is omitted, useObserver automatically discovers all state properties accessed inside the callback:
+
+```javascript
+// No deps needed - magic auto-discovery!
+useObserver(() => {
+  // Automatically tracks state.user, state.items, state.counter
+  console.debug(state.user.name, state.items.length, state.counter);
+},[]);
+```
+
+Returns a cleanup function:
+
+## useObserver vs observer
+
+| Feature | observer | useObserver |
+| ------- | -------- | ----------- |
+| Framework | Vanilla JS | React |
+| Auto-cleanup | Manual | Auto |
+| React lifecycle | No | Yes |
+
+---
+
+## Common Patterns
+
+### Sync with useState (Recommended for Primitives)
+
+```javascript
+function CounterComponent() {
+  // Sync memorio state with React state
+  const [counter, setCounter] = useState(state.counter)
+  
+  // React useEffect works correctly with primitive values
+  useEffect(() => {
+    console.log('Counter changed:', counter)
+  }, [counter])
+  
+  // Direct values now work with primitives!
+  useObserver(() => {
+    setCounter(state.counter)
+  }, [state.counter])  // ✅ Works now!
+  
+  return (
+    <div>
+      <button onClick={() => { state.counter++ }}>Increment</button>
+      <span>{counter}</span>
+    </div>
+  )
+}
+```
+
+### Safe Access with Optional Chaining (Protection)
+
+```javascript
+// Optional chaining is supported - protects against errors
+useObserver(() => {
+  if (test?.one) {
+    console.log(test.one)
+  }
+}, [test?.one])
+
+// Works with objects
+function SafeComponent() {
+  const [test, setTest] = useState(state.test)
+  
+  useEffect(() => {
+    if (test?.one) {
+      console.log('test.one:', test.one)
+    }
+  }, [test?.one])
+  
+  useObserver(() => {
+    if (state.test?.one) {
+      setTest(state.test)
+    }
+  }, ['state.test.one'])
+  
+  return <div>{test?.one || 'Loading...'}</div>
+}
+```
+
+### Multiple Watchers
+
+```javascript
+// Watch multiple properties with strings
+useObserver(() => {
+  console.log(state.a, state.b)
+}, ['state.a', 'state.b'])
+
+// Watch multiple properties with functions
+useObserver(() => {
+  console.log(state.a, state.b)
+}, [() => state.a, () => state.b])
+
+// Watch with auto-discovery
+useObserver(() => {
+  console.log(state.a, state.b) // Automatically tracks both
+}, [])
+```
+
+---
+
+## Best Practices
+
+1. Always use in React components
+2. Use auto-discovery for simpler code: `useObserver(() => { ... })`
+3. No manual cleanup needed - returns cleanup function automatically
+4. Use with state for reactive UI
+5. Check console for auto-discovery logs