@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/examples/patterns.md

@@ -0,0 +1,649 @@
+# Common Patterns
+
+This guide presents common patterns and best practices for working with PicoFlow's reactive primitives. These patterns will help you write more efficient and maintainable reactive code.
+
+## Pattern 1: Computed Display Values
+
+Use derivations to create formatted or computed values for display:
+
+```typescript
+const $price = state(99.99)
+const $quantity = state(2)
+
+const $formatted = derivation((t) => {
+  const price = $price.get(t)
+  const quantity = $quantity.get(t)
+  const total = price * quantity
+  
+  return `${quantity} × $${price.toFixed(2)} = $${total.toFixed(2)}`
+})
+
+effect((t) => {
+  console.log($formatted.get(t))
+})
+
+$quantity.set(3) // Logs: "3 × $99.99 = $299.97"
+```
+
+**Use cases:** Formatted strings, currency display, computed totals, user-friendly messages
+
+## Pattern 2: Conditional Tracking
+
+Only track a dependency when certain conditions are met:
+
+```typescript
+const $enabled = state(true)
+const $data = state('some data')
+
+effect((t) => {
+  if ($enabled.get(t)) {
+    // Only tracks $data when enabled
+    console.log('Data:', $data.get(t))
+  } else {
+    console.log('Disabled')
+  }
+})
+
+$data.set('new data')  // Logs if enabled
+$enabled.set(false)     // Now data changes won't log
+```
+
+**Use cases:** Feature flags, conditional data fetching, dynamic subscriptions
+
+## Pattern 3: Non-Reactive Snapshot
+
+Take a snapshot of a reactive value without creating a dependency:
+
+```typescript
+const $livePrice = state(100)
+const $refreshTrigger = signal()
+
+effect((t) => {
+  // React to trigger only
+  $refreshTrigger.watch(t)
+  
+  // Take snapshot of current price (no dependency)
+  const snapshot = $livePrice.pick()
+  console.log('Snapshot taken:', snapshot)
+})
+
+$livePrice.set(200)        // Does NOT trigger effect
+$refreshTrigger.trigger()  // DOES trigger, logs current price
+```
+
+**Use cases:** Manual refresh with current values, avoiding circular dependencies, comparison snapshots
+
+## Pattern 4: Snapshot + Reactive
+
+Mix reactive and non-reactive reads:
+
+```typescript
+effect((t) => {
+  const currentId = $userId.get(t)      // Reactive - triggers re-run
+  const config = $appConfig.pick()       // Non-reactive snapshot
+  
+  fetchUserData(currentId, config)
+})
+```
+
+### Use Cases
+
+- Using configuration that shouldn't trigger updates
+- Taking snapshots for comparison
+- Avoiding circular dependencies
+
+### Example: API Call with Static Config
+
+```typescript
+const $searchQuery = state('')
+const $apiConfig = state({ baseUrl: 'https://api.example.com', timeout: 5000 })
+
+effect((t) => {
+  const query = $searchQuery.get(t) // React to query changes
+  const config = $apiConfig.pick()   // Use current config without tracking
+  
+  if (query.length > 2) {
+    fetch(`${config.baseUrl}/search?q=${query}`, {
+      signal: AbortSignal.timeout(config.timeout)
+    })
+  }
+})
+```
+
+### Example: Previous Value Comparison
+
+```typescript
+const $count = state(0)
+
+effect((t) => {
+  const previous = $count.pick() // Snapshot before reactive read
+  const current = $count.get(t)  // Reactive read
+  
+  if (current > previous) {
+    console.log('Count increased')
+  }
+})
+```
+
+## Pattern 5: Batch Updates
+
+Multiple effects can depend on the same state:
+
+```typescript
+const $data = state({ count: 0, name: 'test' })
+
+effect((t) => console.log('Count:', $data.get(t).count))
+effect((t) => console.log('Name:', $data.get(t).name))
+
+$data.set({ count: 1, name: 'updated' }) // Both effects run once
+```
+
+### Use Cases
+
+- Multiple UI components reacting to the same state
+- Coordinated updates across different parts of the app
+- Efficient bulk operations
+
+### Example: Form State Management
+
+```typescript
+interface FormState {
+  username: string
+  email: string
+  isValid: boolean
+}
+
+const $form = state<FormState>({
+  username: '',
+  email: '',
+  isValid: false
+})
+
+// Multiple effects react to different parts
+effect((t) => {
+  const username = $form.get(t).username
+  validateUsername(username)
+})
+
+effect((t) => {
+  const email = $form.get(t).email
+  validateEmail(email)
+})
+
+effect((t) => {
+  const form = $form.get(t)
+  updateSubmitButton(form.isValid)
+})
+
+// Single update triggers all effects once
+function updateForm(updates: Partial<FormState>) {
+  $form.set(current => ({ ...current, ...updates }))
+}
+```
+
+## Pattern 6: Derived State Chain
+
+Create chains of computed values:
+
+```typescript
+const $items = state<Item[]>([])
+
+const $activeItems = derivation((t) => 
+  $items.get(t).filter(item => item.active)
+)
+
+const $itemCount = derivation((t) => 
+  $activeItems.get(t).length
+)
+
+const $statusMessage = derivation((t) => {
+  const count = $itemCount.get(t)
+  return count === 0 ? 'No items' : `${count} items`
+})
+
+effect((t) => {
+  console.log($statusMessage.get(t))
+})
+```
+
+### Benefits
+
+- Clear separation of concerns
+- Efficient caching at each level
+- Easy to test individual derivations
+
+## Pattern 7: Signal for Manual Refresh
+
+Use signals to trigger manual updates:
+
+```typescript
+const $refreshTrigger = signal()
+const $data = state<Data>({ cached: true })
+
+effect((t) => {
+  $refreshTrigger.watch(t) // React to manual trigger
+  
+  // Fetch fresh data
+  fetchData().then(data => $data.set(data))
+})
+
+// Trigger refresh from anywhere
+$refreshTrigger.trigger()
+```
+
+### Use Cases
+
+- Manual data refresh
+- Force recalculation
+- Synchronization points
+
+## Pattern 8: Cleanup with Effect Disposer
+
+Effects can return cleanup functions:
+
+```typescript
+const $url = state('https://api.example.com/data')
+
+effect((t) => {
+  const url = $url.get(t)
+  const controller = new AbortController()
+  
+  fetch(url, { signal: controller.signal })
+    .then(/* handle response */)
+  
+  // Cleanup when effect re-runs or disposes
+  return () => controller.abort()
+})
+```
+
+### Use Cases
+
+- Canceling pending requests
+- Clearing timers
+- Unsubscribing from events
+
+## Pattern 9: Lazy Loading with Resources
+
+Use resources for async data that depends on other reactive values:
+
+```typescript
+const $userId = state(1)
+
+const $user = resource(
+  (t) => $userId.get(t), // Reactive source
+  (id) => fetchUser(id)   // Async fetcher
+)
+
+effect((t) => {
+  const user = $user.get(t)
+  if (user.state === 'ready') {
+    console.log('User:', user.value)
+  }
+})
+```
+
+### Benefits
+
+- Built-in loading/error states
+- Automatic refetching when dependencies change
+- Cancellation of stale requests
+
+## Pattern 10: Conditional Computation (Derivations)
+
+Skip expensive derivation computation when not needed:
+
+```typescript
+const $enabled = state(false)
+const $data = state([1, 2, 3, 4, 5])
+
+const $processedData = derivation((t) => {
+  if (!$enabled.get(t)) {
+    return [] // Skip computation when disabled
+  }
+  
+  // Only compute when enabled
+  return $data.get(t).map(n => n * 2).filter(n => n > 5)
+})
+```
+
+### Use Cases
+
+- Feature flags that control expensive computations
+- Conditional data processing
+- Performance optimization for optional features
+
+## Pattern 11: Memoization Within Derivation
+
+Use derivations to cache expensive theme or configuration calculations:
+
+```typescript
+const $config = state({ theme: 'dark', lang: 'en' })
+
+const $themeColors = derivation((t) => {
+  const theme = $config.get(t).theme
+  
+  // Expensive computation
+  return theme === 'dark' 
+    ? generateDarkPalette()
+    : generateLightPalette()
+})
+```
+
+### Use Cases
+
+- Theme color palette generation
+- Expensive configuration parsing
+- Complex UI calculations
+
+## Pattern 12: Combining Multiple Derivations
+
+Chain derivations to create a computation pipeline:
+
+```typescript
+const $sales = state([100, 200, 150])
+const $expenses = state([50, 80, 60])
+
+const $totalSales = derivation((t) => {
+  return $sales.get(t).reduce((a, b) => a + b, 0)
+})
+
+const $totalExpenses = derivation((t) => {
+  return $expenses.get(t).reduce((a, b) => a + b, 0)
+})
+
+const $profit = derivation((t) => {
+  return $totalSales.get(t) - $totalExpenses.get(t)
+})
+
+const $profitMargin = derivation((t) => {
+  const profit = $profit.get(t)
+  const sales = $totalSales.get(t)
+  return sales > 0 ? (profit / sales) * 100 : 0
+})
+```
+
+Dependency graph:
+
+```mermaid
+graph TD
+    A[$sales] --> C[$totalSales]
+    B[$expenses] --> D[$totalExpenses]
+    C --> E[$profit]
+    D --> E
+    E --> F[$profitMargin]
+    C --> F
+    
+    style A fill:#FFE6E6
+    style B fill:#FFE6E6
+    style C fill:#E6F3FF
+    style D fill:#E6F3FF
+    style E fill:#E6F3FF
+    style F fill:#E6F3FF
+```
+
+### Benefits
+
+- Each derivation is simple and focused
+- Efficient caching at each level
+- Easy to test and debug
+- Clear dependency relationships
+
+## Pattern 13: Logging and Debugging with Effects
+
+Use effects for reactive logging and debugging:
+
+```typescript
+const $count = state(0)
+
+// Debug logger
+effect((t) => {
+  const value = $count.get(t)
+  console.log('[DEBUG] count changed:', value, 'at', new Date())
+})
+```
+
+### Use Cases
+
+- Development debugging
+- Tracking state changes
+- Performance monitoring
+- Audit logs
+
+## Pattern 14: DOM Updates with Effects
+
+Effects are perfect for updating the DOM based on reactive state:
+
+```typescript
+const $username = state('')
+
+effect((t) => {
+  const name = $username.get(t)
+  document.getElementById('username').textContent = name
+})
+```
+
+### Use Cases
+
+- Updating text content
+- Toggling classes
+- Managing visibility
+- Synchronizing UI with state
+
+## Pattern 15: LocalStorage Sync with Effects
+
+Automatically persist state to localStorage:
+
+```typescript
+const $preferences = state({ theme: 'light', lang: 'en' })
+
+effect((t) => {
+  const prefs = $preferences.get(t)
+  localStorage.setItem('preferences', JSON.stringify(prefs))
+})
+```
+
+### Use Cases
+
+- User preferences
+- Draft autosave
+- Cache management
+- Offline-first applications
+
+## Pattern 16: Derived Side Effects
+
+Combine derivations with effects for complex reactive behaviors:
+
+```typescript
+const $items = state([1, 2, 3])
+const $total = derivation((t) => {
+  return $items.get(t).reduce((sum, n) => sum + n, 0)
+})
+
+effect((t) => {
+  const total = $total.get(t)
+  if (total > 100) {
+    alert('Total exceeded limit!')
+  }
+})
+```
+
+### Use Cases
+
+- Threshold alerts
+- Conditional notifications
+- Validation side effects
+- Derived triggers
+
+## Pattern 17: Batch Updates with Maps
+
+When updating multiple map entries, consider the notification pattern:
+
+```typescript
+// ❌ Multiple updates = multiple notifications
+$map.add('a', 1)
+$map.add('b', 2)
+$map.add('c', 3)
+// Each operation triggers notifications
+
+// ✅ Consider if batching is possible at a higher level
+// Note: PicoFlow doesn't have built-in batching, but you can
+// minimize unnecessary work by grouping related operations
+const updates = [
+  { key: 'a', value: 1 },
+  { key: 'b', value: 2 },
+  { key: 'c', value: 3 }
+]
+for (const { key, value } of updates) {
+  const existing = $map.pick().has(key)
+  if (existing) {
+    $map.update(key, value)
+  } else {
+    $map.add(key, value)
+  }
+}
+```
+
+**Use cases:** Bulk operations, data synchronization, minimizing UI updates during batch changes
+
+## Pattern 18: Selective Tracking with Maps
+
+Track only the operations you need, not all operations:
+
+```typescript
+// Track only additions, not updates or deletions
+effect((t) => {
+  const lastAdded = $users.$lastAdded.get(t)
+  if (lastAdded) {
+    handleNewUser(lastAdded.value)
+  }
+})
+
+// Separate effect for deletions
+effect((t) => {
+  const lastDeleted = $users.$lastDeleted.get(t)
+  if (lastDeleted) {
+    handleRemovedUser(lastDeleted.key)
+  }
+})
+
+// Separate effect for updates
+effect((t) => {
+  const lastUpdated = $users.$lastUpdated.get(t)
+  if (lastUpdated) {
+    handleUpdatedUser(lastUpdated.value)
+  }
+})
+```
+
+**Use cases:** Different UI animations for different operations, selective logging, operation-specific side effects
+
+## Pattern 19: Combine Coarse and Fine-Grained Tracking
+
+Use both whole-map tracking and fine-grained tracking together:
+
+```typescript
+// Coarse: Update count (reacts to any change)
+effect((t) => {
+  const count = $items.get(t).size
+  updateCountDisplay(count)
+})
+
+// Fine: Animate specific changes
+effect((t) => {
+  const lastAdded = $items.$lastAdded.get(t)
+  if (lastAdded) {
+    animateNewItem(lastAdded.key, lastAdded.value)
+  }
+})
+
+effect((t) => {
+  const lastDeleted = $items.$lastDeleted.get(t)
+  if (lastDeleted) {
+    animateRemovedItem(lastDeleted.key)
+  }
+})
+```
+
+**Use cases:** Combining aggregate statistics with individual item animations, efficient UI updates that need both totals and specific changes
+
+## Pattern 20: Batch Updates with Arrays
+
+Minimize notifications by batching multiple operations:
+
+```typescript
+// ❌ Multiple updates = multiple notifications
+$items.push(1)
+$items.push(2)
+$items.push(3)
+
+// ✅ Use splice for batch additions
+$items.splice($items.length, 0, 1, 2, 3)
+
+// Or use set() to replace entire array if appropriate
+const newItems = [...$items.pick(), 1, 2, 3]
+$items.set(newItems)
+```
+
+**Use cases:** Bulk operations, data synchronization, minimizing UI updates during batch changes
+
+## Pattern 21: Selective Tracking with Arrays
+
+Track only the operations you need, not all operations:
+
+```typescript
+// Track only additions, not deletions
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'push') {
+    handleNewItem(action.item)
+  }
+})
+
+// Separate effect for deletions
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && (action.type === 'pop' || action.type === 'splice')) {
+    handleRemovedItems(action)
+  }
+})
+
+// Separate effect for updates
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'setItem') {
+    handleUpdatedItem(action.index, action.item)
+  }
+})
+```
+
+**Use cases:** Different UI animations for different operations, selective logging, operation-specific side effects
+
+## Pattern 22: Combine Coarse and Fine-Grained Array Tracking
+
+Use both whole-array tracking and fine-grained tracking together:
+
+```typescript
+// Coarse: Update count (reacts to any change)
+effect((t) => {
+  const count = $items.get(t).length
+  updateCountDisplay(count)
+})
+
+// Fine: Animate specific changes
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'push') {
+    animateNewItem(action.item)
+  }
+})
+
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'splice') {
+    animateRemovedItems(action.start, action.deleteCount)
+  }
+})
+```
+
+**Use cases:** Combining aggregate statistics with individual item animations, efficient UI updates that need both totals and specific changes
+