@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/guide/primitives/effects.md

@@ -0,0 +1,458 @@
+# Effects
+
+Effects are how you perform **side effects** in response to reactive changes. They're the bridge between your reactive data and the outside world - updating the DOM, making API calls, saving to localStorage, and more.
+
+Imagine a light switch: when you flip it, the light turns on. Effects work the same way in reactive programming - when your data changes, effects automatically run to update the world around them.
+
+### Key Characteristics
+
+- **Immediate execution**: Runs synchronously when created
+- **Automatic re-execution**: Re-runs when dependencies change
+- **Dynamic dependency tracking**: Dependencies adapt at runtime
+- **Side effects allowed**: Designed for DOM, API, logging, etc.
+- **Disposal support**: Clean up resources when no longer needed
+
+## When to Use Effects
+
+Use effects when you need to:
+
+- ✅ Perform side effects (DOM updates, API calls, localStorage)
+- ✅ React to changes in reactive values
+- ✅ Coordinate with external systems
+- ✅ Set up subscriptions or event listeners
+- ✅ Log or debug reactive changes
+
+Don't use effects when:
+
+- ❌ Computing derived values (use derivations instead)
+- ❌ The value needs to be used elsewhere reactively (use derivations)
+- ❌ You only need to run code once (use regular functions)
+
+## Creating Effects
+
+Creating an effect is straightforward:
+
+```typescript
+import { effect } from '@ersbeth/picoflow'
+
+effect((t) => {
+  // Your side effect code here
+  // Use t to track dependencies
+})
+```
+
+The parameter `t` is the **TrackingContext** - your tool for creating dependencies.
+
+## Using Effects
+
+Effects have several ways to interact with reactive values and manage their lifecycle.
+
+### Tracking with `.get(t)` (Reactive)
+
+Use `.get(t)` to create dependencies - the effect will re-run when the value changes:
+
+```typescript
+const $username = state('Alice')
+
+effect((t) => {
+  const name = $username.get(t) // Creates dependency
+  document.getElementById('username').textContent = name
+})
+
+$username.set('Bob') // Effect re-runs, DOM updates
+```
+
+### Non-Reactive Reads with `.pick()`
+
+Use `.pick()` to read the current value without creating a dependency:
+
+```typescript
+const $activeUserId = state(1)
+const $userDatabase = state({ /* large object */ })
+
+effect((t) => {
+  const activeId = $activeUserId.get(t)     // Reactive
+  const database = $userDatabase.pick()     // Snapshot
+  
+  const user = database[activeId]
+  console.log('Active user:', user)
+})
+
+// Only changes to $activeUserId trigger the effect
+// Changes to $userDatabase are ignored
+```
+
+### Watching Signals with `.watch(t)`
+
+Signals are special - they don't hold values, so use `.watch(t)` to track them:
+
+```typescript
+import { signal, effect } from '@ersbeth/picoflow'
+
+const $refresh = signal()
+
+effect((t) => {
+  $refresh.watch(t) // React to signal triggers
+  console.log('Refreshing data...')
+  fetchData()
+})
+
+$refresh.trigger() // Effect runs
+```
+
+### Multiple Dependencies
+
+Effects can track multiple reactive values:
+
+```typescript
+const $firstName = state('Alice')
+const $lastName = state('Smith')
+
+effect((t) => {
+  const first = $firstName.get(t)
+  const last = $lastName.get(t)
+  console.log('Full name:', first, last)
+})
+
+// Changes to EITHER trigger the effect
+$firstName.set('Bob')   // Effect runs
+$lastName.set('Jones')  // Effect runs
+```
+
+### Conditional Dependencies
+
+Dependencies can be conditional - they're re-evaluated on each execution:
+
+```typescript
+const $showDetails = state(false)
+const $details = state({ info: 'secret' })
+
+effect((t) => {
+  if ($showDetails.get(t)) {
+    // Only depends on $details when $showDetails is true
+    console.log('Details:', $details.get(t))
+  } else {
+    console.log('Details hidden')
+  }
+})
+
+// When $showDetails is false, changes to $details don't trigger the effect
+$details.set({ info: 'new secret' }) // Effect doesn't run
+
+// But once $showDetails is true...
+$showDetails.set(true) // Effect runs and now tracks $details
+$details.set({ info: 'updated' }) // Now this triggers the effect!
+```
+
+### Disposing with `.dispose()`
+
+Effects run indefinitely unless disposed. Always clean them up when no longer needed:
+
+```typescript
+const $count = state(0)
+
+// Create effect
+const fx = effect((t) => {
+  console.log($count.get(t))
+})
+
+// Later... stop the effect
+fx.dispose()
+
+// After disposal, the effect won't run anymore
+$count.set(10) // No console log
+```
+
+**Always dispose effects when:**
+- Component unmounts (in UI frameworks)
+- Feature is disabled
+- User navigates away
+- App shuts down
+
+**Memory leak example:**
+
+```typescript
+// ❌ Memory leak
+function createUserPanel(userId: number) {
+  const $user = state(getUserData(userId))
+  
+  effect((t) => {
+    updateUI($user.get(t))
+  })
+  // Effect never disposed! ⚠️
+}
+
+// Called 100 times = 100 effects still running!
+
+// ✅ Proper cleanup
+function createUserPanel(userId: number) {
+  const $user = state(getUserData(userId))
+  
+  const fx = effect((t) => {
+    updateUI($user.get(t))
+  })
+  
+  return {
+    dispose: () => {
+      fx.dispose()
+      $user.dispose()
+    }
+  }
+}
+```
+
+## Lifecycle
+
+Effects execute immediately when created, track their dependencies, and re-execute when any dependency changes. Understanding this lifecycle is key to writing efficient reactive code.
+
+When you create an effect, it runs **synchronously** - not on the next tick, but right away. This allows effects to establish initial dependencies and set up initial side effects. When a dependency changes, the effect re-executes synchronously.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $count as $count (State)
+    participant Effect
+    
+    Note over User,Effect: 1. Creation Phase
+    User->>Effect: Create effect((t) => ...)
+    activate Effect
+    Note over Effect: Execute immediately
+    
+    Effect->>$count: get(t)
+    activate $count
+    Note over $count: Register Effect as dependent
+    $count-->>Effect: 0
+    deactivate $count
+    
+    Note over Effect: console.log("Count: 0")
+    Note over Effect: Track: depends on $count
+    deactivate Effect
+    
+    Note over User,Effect: 2. Change Phase
+    User->>$count: set(5)
+    activate $count
+    Note over $count: Value changed: 0 → 5
+    
+    $count->>Effect: Notify & schedule
+    deactivate $count
+    
+    activate Effect
+    Note over Effect: Clear old dependencies<br/>Execute function
+    
+    Effect->>$count: get(t)
+    activate $count
+    Note over $count: Register Effect as dependent
+    $count-->>Effect: 5
+    deactivate $count
+    
+    Note over Effect: console.log("Count: 5")
+    Note over Effect: Track: depends on $count
+    deactivate Effect
+    
+    Note over User,Effect: 3. Disposal Phase
+    User->>Effect: dispose()
+    activate Effect
+    Note over Effect: Clear dependencies<br/>Unregister from $count
+    Note over Effect: Mark as disposed
+    deactivate Effect
+    
+    User->>$count: set(10)
+    activate $count
+    Note over $count: Value changed<br/>No dependents to notify
+    deactivate $count
+    Note over Effect: (Does not run - disposed)
+```
+
+### Key Lifecycle Points
+
+1. **Creation & Immediate Execution**: The effect function runs synchronously during creation
+2. **Dependency Registration**: Reactive reads (`.get(t)`) register the effect as a dependent
+3. **Change Notification**: When dependencies change, the effect is scheduled to re-run
+4. **Re-execution**: Effect clears old dependencies, runs again, re-registers new dependencies
+5. **Disposal**: Clears all dependencies, unregisters from all reactive values, prevents future execution
+
+This immediate, synchronous execution model means:
+- **Effects establish dependencies on first run** (no waiting)
+- **Changes trigger re-execution immediately** (synchronous)
+- **Dynamic dependencies adapt automatically** (conditional tracking)
+
+## Best Practices
+
+### Keep Effects Focused
+
+Each effect should do one thing:
+
+```typescript
+// ❌ Doing too much
+effect((t) => {
+  updateDOM($count.get(t))
+  saveToStorage($count.get(t))
+  sendAnalytics($count.get(t))
+  updateTitle($count.get(t))
+})
+
+// ✅ Separate concerns
+effect((t) => updateDOM($count.get(t)))
+effect((t) => saveToStorage($count.get(t)))
+effect((t) => sendAnalytics($count.get(t)))
+effect((t) => updateTitle($count.get(t)))
+```
+
+**Why?** Easier to debug, test, and disable individual effects.
+
+### Avoid Creating Effects Inside Effects
+
+```typescript
+// ❌ Bad - creates new effects on every run
+effect((t) => {
+  const count = $count.get(t)
+  effect((t) => {
+    console.log('Nested:', count) // Memory leak!
+  })
+})
+
+// ✅ Good - create effects at the top level
+effect((t) => {
+  const count = $count.get(t)
+  console.log('Count:', count)
+})
+```
+
+### Handle Errors
+
+Wrap risky operations in try-catch:
+
+```typescript
+effect((t) => {
+  const data = $data.get(t)
+  
+  try {
+    updateDOM(data)
+  } catch (error) {
+    console.error('Failed to update DOM:', error)
+  }
+})
+```
+
+### Be Careful with Infinite Loops
+
+Don't update dependencies inside the same effect:
+
+```typescript
+const $count = state(0)
+
+// ❌ Infinite loop!
+effect((t) => {
+  const count = $count.get(t)
+  $count.set(count + 1) // Triggers itself!
+})
+
+// ✅ Use a different state
+effect((t) => {
+  const count = $count.get(t)
+  $doubled.set(count * 2) // Updates different state
+})
+```
+
+### Use Signals for Event-Only Tracking
+
+When you don't need a value, just an event:
+
+```typescript
+const $refresh = signal()
+
+effect((t) => {
+  $refresh.watch(t) // Track signal without reading a value
+  fetchData()
+})
+
+// Trigger refresh
+$refresh.trigger()
+```
+
+## Common Pitfalls
+
+### Forgetting to Use `.get(t)`
+
+**Problem**: Using `.pick()` instead of `.get(t)` breaks reactivity.
+
+```typescript
+// ❌ No dependency created - effect runs only once
+effect((t) => {
+  console.log($count.pick()) // Using .pick() instead of .get(t)
+})
+
+$count.set(10) // Effect won't run
+```
+
+**Solution**: Always use `.get(t)` to create dependencies:
+
+```typescript
+// ✅ Correct
+effect((t) => {
+  console.log($count.get(t))
+})
+
+$count.set(10) // Effect runs
+```
+
+### Not Disposing Effects
+
+**Problem**: Effects continue running even when no longer needed.
+
+```typescript
+// ❌ Memory leak in component lifecycle
+function MyComponent() {
+  effect((t) => {
+    updateView($data.get(t))
+  })
+  // Never disposed!
+}
+
+// Each component creation adds another effect that never stops
+```
+
+**Solution**: Always dispose effects when done:
+
+```typescript
+// ✅ Proper cleanup
+function MyComponent() {
+  const fx = effect((t) => {
+    updateView($data.get(t))
+  })
+  
+  return {
+    cleanup: () => fx.dispose()
+  }
+}
+```
+
+### Async Operations Without Care
+
+**Problem**: Race conditions when using async operations in effects.
+
+```typescript
+// ⚠️ Race condition possible
+effect(async (t) => {
+  const id = $userId.get(t)
+  const data = await fetchUser(id) // If $userId changes during fetch...
+  displayUser(data) // ...we might display wrong user!
+})
+```
+
+**Solution**: Check if values are still relevant after async operations:
+
+```typescript
+// ✅ Better - check if still relevant
+effect(async (t) => {
+  const id = $userId.get(t)
+  const data = await fetchUser(id)
+  
+  // Verify ID didn't change during fetch
+  if ($userId.pick() === id) {
+    displayUser(data)
+  }
+})
+```
+
+**Why this matters**: Between starting an async operation and its completion, your reactive values might change. Always verify the context is still valid before applying results.