@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/guide/introduction/lifecycle.md

@@ -0,0 +1,371 @@
+# Lifecycle
+
+Understanding PicoFlow's internal execution model is key to mastering reactive programming. This guide walks through exactly what happens during creation, updates, and disposal using a concrete example.
+
+## The Example
+
+Throughout this guide, we'll use this simple but complete example:
+
+```typescript
+const $a = state(1)
+const $b = state(2)
+const $c = derivation((t) => $a.get(t) + $b.get(t))
+effect((t) => console.log('C =', $c.get(t)))
+```
+
+This example demonstrates:
+- **Two states**: `$a` and `$b`
+- **One derivation**: `$c` that computes the sum
+- **One effect**: that logs the result
+
+Let's see what happens at each stage of the lifecycle.
+
+## Creation Flow
+
+When you run the example code, here's the exact sequence of events:
+
+### Step-by-Step
+
+1. **`state(1)` creates `$a`**
+   - A new `FlowState` instance is created
+   - Internal value is set to `1`
+   - No dependencies yet
+
+2. **`state(2)` creates `$b`**
+   - Another `FlowState` instance is created
+   - Internal value is set to `2`
+   - No dependencies yet
+
+3. **`derivation(...)` creates `$c`**
+   - A new `FlowDerivation` instance is created
+   - The compute function is stored but **NOT executed** (lazy evaluation)
+   - A `TrackingContext` is created for the derivation
+   - Still no computed value yet
+
+4. **`effect(...)` creates the effect**
+   - A new `FlowEffect` instance is created
+   - A `TrackingContext` is created for the effect
+   - **The effect executes immediately** (not lazy!)
+   - During execution:
+     - Effect calls `$c.get(t)`
+     - This triggers `$c` to initialize (first access)
+     - `$c` runs its compute function with its tracking context
+     - Compute calls `$a.get(t)` → returns `1`, registers `$a` as dependency of `$c`
+     - Compute calls `$b.get(t)` → returns `2`, registers `$b` as dependency of `$c`
+     - Compute returns `3`
+     - Effect's `$c.get(t)` returns `3`, registers `$c` as dependency of effect
+   - Effect logs: `"C = 3"`
+
+### Creation Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $a as $a (State)
+    participant $b as $b (State)
+    participant $c as $c (Derivation)
+    participant Effect
+    participant Context
+    
+    User->>$a: state(1)
+    activate $a
+    Note over $a: Store value: 1
+    deactivate $a
+    
+    User->>$b: state(2)
+    activate $b
+    Note over $b: Store value: 2
+    deactivate $b
+    
+    User->>$c: derivation((t) => ...)
+    activate $c
+    Note over $c: Store compute fn<br/>NOT executed yet<br/>(lazy)
+    deactivate $c
+    
+    User->>Effect: effect((t) => ...)
+    activate Effect
+    Note over Effect: Create & execute<br/>immediately
+    
+    Effect->>$c: get(t)
+    activate $c
+    Note over $c: First access!<br/>Initialize & compute
+    
+    $c->>$a: get(t)
+    activate $a
+    $a-->>$c: 1
+    $a->>$c: Register as listener
+    Note over $a,$c: $c now depends on $a
+    deactivate $a
+    
+    $c->>$b: get(t)
+    activate $b
+    $b-->>$c: 2
+    $b->>$c: Register as listener
+    Note over $b,$c: $c now depends on $b
+    deactivate $b
+    
+    Note over $c: Compute: 1 + 2 = 3
+    $c-->>Effect: 3
+    $c->>Effect: Register as effect
+    Note over $c,Effect: Effect depends on $c
+    deactivate $c
+    
+    Note over Effect: Log: "C = 3"
+    deactivate Effect
+```
+
+**Key Insights:**
+- States are simple: just store the value
+- Derivations are **lazy**: they don't compute until accessed
+- Effects are **eager**: they execute immediately on creation
+- Dependencies are registered **during execution** through `.get(t)`
+
+## Update Flow
+
+Now let's see what happens when we update `$a`:
+
+```typescript
+$a.set(5)
+```
+
+### The Push-Pull Model
+
+PicoFlow uses a "**push notification, pull computation**" model:
+
+- **Push**: When a value changes, notifications are pushed to all dependents immediately
+- **Pull**: Actual recomputation only happens when a value is accessed (pulled)
+
+This is efficient because:
+- Derivations that aren't currently needed don't recompute
+- Multiple state changes can batch before triggering computation
+- Only the necessary chain of dependencies is recomputed
+
+### Step-by-Step
+
+1. **`$a.set(5)` is called**
+   - `$a` checks if the value changed: `5 !== 1` ✓
+   - `$a` updates its internal value: `1 → 5`
+   - `$a` notifies all its dependents
+
+2. **`$a` notifies its dependents**
+   - `$a` sends notifications to all listeners (includes `$c`)
+   - `$c` receives the notification
+
+3. **`$c` receives notification**
+   - `$c` marks itself as needing recomputation
+   - **Does NOT recompute yet!** (lazy evaluation)
+   - `$c` propagates the notification to its dependents
+
+4. **`$c` notifies its dependents**
+   - `$c` sends notifications to all effects (includes our effect)
+   - The effect is scheduled to execute
+
+5. **Effect executes**
+   - Effect runs its function with tracking context
+   - Calls `$c.get(t)`
+
+6. **`$c` recomputes (pull)**
+   - `$c.get(t)` detects that recomputation is needed
+   - Clears old dependencies
+   - Runs compute function again
+   - Compute calls `$a.get(t)` → returns `5`
+   - Compute calls `$b.get(t)` → returns `2`
+   - Computes new value: `5 + 2 = 7`
+   - Re-registers dependencies
+   - Returns `7`
+
+7. **Effect logs the result**
+   - Effect receives `7` from `$c.get(t)`
+   - Logs: `"C = 7"`
+
+### Update Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $a as $a (State)
+    participant $c as $c (Derivation)
+    participant Effect
+    
+    User->>$a: set(5)
+    activate $a
+    Note over $a: Check: 5 !== 1 ✓<br/>Update: 1 → 5
+    
+    $a->>$c: notify
+    activate $c
+    Note over $c: Mark as needs<br/>recomputation<br/>NO recompute yet!
+    
+    $c->>Effect: notify
+    deactivate $c
+    deactivate $a
+    
+    activate Effect
+    Note over Effect: Execute function
+    
+    Effect->>$c: get(t)
+    activate $c
+    Note over $c: Recomputation<br/>needed? YES
+    
+    Note over $c: Recompute
+    activate $c
+    Note over $c: Clear old deps
+    
+    $c->>$a: get(t)
+    activate $a
+    $a-->>$c: 5
+    deactivate $a
+    
+    $c->>$b: get(t)
+    activate $b
+    $b-->>$c: 2
+    deactivate $b
+    
+    Note over $c: Compute: 5 + 2 = 7<br/>Re-register deps
+    deactivate $c
+    
+    $c-->>Effect: 7
+    deactivate $c
+    
+    Note over Effect: Log: "C = 7"
+    deactivate Effect
+```
+
+**Key Insights:**
+- **Notifications are pushed** immediately when state changes
+- **Derivations mark as dirty** but don't recompute until needed
+- **Effects execute immediately** when notified
+- **Recomputation is pulled** when effects access derivations
+- **Dependencies are re-registered** on each execution (dynamic tracking)
+
+## Disposal Flow
+
+Finally, let's see what happens when we dispose a primitive:
+
+```typescript
+$a.dispose()
+```
+
+### Step-by-Step
+
+1. **`$a.dispose()` is called**
+   - `$a` checks if already disposed (throws if yes)
+   - Iterates through all listeners (dependents like `$c`)
+   - Iterates through all effects (none in this case)
+
+2. **Cleanup listeners**
+   - For each listener, calls `listener.dispose()`
+   - This triggers `$c.dispose()`
+
+3. **`$c.dispose()` cascades**
+   - `$c` iterates through its listeners (none)
+   - `$c` iterates through its effects (includes our effect)
+   - Calls `effect.dispose()`
+
+4. **Effect cleanup**
+   - Effect unregisters from all its dependencies (`$c`)
+   - Effect marks itself as disposed
+   - Future notifications won't trigger this effect
+
+5. **State cleanup**
+   - `$a` unregisters from all its listeners
+   - `$a` marks itself as disposed
+   - Future attempts to use `$a` will throw errors
+
+6. **Result**
+   - The entire dependency graph is cleaned up
+   - Memory is freed
+   - No more reactions will occur
+
+### Disposal Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $a as $a (State)
+    participant $c as $c (Derivation)
+    participant Effect
+    
+    User->>$a: dispose()
+    activate $a
+    Note over $a: Check if disposed<br/>Iterate listeners
+    
+    $a->>$c: dispose()
+    activate $c
+    Note over $c: Iterate effects
+    
+    $c->>Effect: dispose()
+    activate Effect
+    
+    Effect->>$c: Unregister
+    Note over Effect,$c: Remove dependency
+    
+    Note over Effect: Mark disposed<br/>Stop running
+    deactivate Effect
+    
+    $c->>$a: Unregister
+    Note over $c,$a: Remove dependency
+    
+    Note over $c: Mark disposed
+    deactivate $c
+    
+    Note over $a: Mark disposed<br/>Clean up listeners
+    deactivate $a
+    
+    Note over User,Effect: All cleaned up!<br/>Memory freed
+```
+
+**Key Insights:**
+- **Disposal cascades** through the dependency graph
+- **Dependents are disposed first** (effects before derivations before states)
+- **All registrations are cleaned up** to prevent memory leaks
+- **Disposed primitives throw errors** if you try to use them
+- **Order matters**: dispose dependents before dependencies when doing manual cleanup
+
+## Practical Implications
+
+Understanding these flows helps you:
+
+### 1. Optimize Performance
+
+```typescript
+// Derivation won't compute if effect is disposed
+const $expensive = derivation((t) => {
+  return expensiveCalculation($data.get(t))
+})
+
+const fx = effect((t) => {
+  if (shouldDisplay) {
+    display($expensive.get(t)) // Only computes when accessed
+  }
+})
+
+// When not needed, just dispose the effect
+fx.dispose() // $expensive stops computing
+```
+
+### 2. Debug Dependency Issues
+
+```typescript
+// If logs don't appear, check:
+// 1. Is the effect created? (runs immediately)
+// 2. Are you using .get(t)? (not .pick())
+// 3. Is anything disposed?
+
+effect((t) => {
+  console.log('Effect created') // Should log immediately
+  console.log('Value:', $state.get(t)) // Creates dependency
+})
+```
+
+### 3. Avoid Memory Leaks
+
+```typescript
+// Always dispose effects when done
+const disposables: FlowDisposable[] = []
+
+disposables.push(effect((t) => { /* ... */ }))
+disposables.push(effect((t) => { /* ... */ }))
+
+// Clean up
+disposables.forEach(d => d.dispose())
+```