@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/guide/advanced/disposal.md

@@ -1,426 +0,0 @@
-# Disposal
-
-Memory management is crucial in long-running applications. PicoFlow provides explicit disposal mechanisms to prevent memory leaks and ensure resources are properly cleaned up.
-
-## Why Disposal Matters
-
-All PicoFlow primitives are disposable. When you're done with them, you should clean them up:
-
-```typescript
-const $count = state(0)
-const fx = effect((t) => {
-  console.log($count.get(t))
-})
-
-// Later... clean up
-fx.dispose() // Effect stops running
-$count.dispose() // State is cleaned up
-```
-
-**Why disposal matters:**
-- **Prevents memory leaks** - Unreferenced but undisposed primitives stay in memory
-- **Stops effects from running** - Effects continue executing until explicitly disposed
-- **Cleans up resources** - WebSocket connections, intervals, event listeners, etc.
-- **Important in long-running applications** - SPAs, dashboards, real-time apps
-
-```mermaid
-flowchart LR
-    A[Create primitive] --> B[Use in effects]
-    B --> C[No longer needed]
-    C --> D{Disposed?}
-    D -->|Yes| E[Memory freed]
-    D -->|No| F[Memory leak!]
-    
-    style E fill:#90EE90
-    style F fill:#FFB6C6
-```
-
-## When to Dispose
-
-### Component Cleanup
-
-In component-based architectures, dispose primitives when components unmount:
-
-```typescript
-class TodoList {
-  private $todos = state<Todo[]>([])
-  private disposables: FlowDisposable[] = []
-  
-  constructor() {
-    // Track all disposables
-    this.disposables.push(
-      effect((t) => {
-        this.render($todos.get(t))
-      })
-    )
-  }
-  
-  destroy() {
-    // Clean up when component is destroyed
-    this.disposables.forEach(d => d.dispose())
-    this.$todos.dispose()
-  }
-}
-```
-
-### Conditional Effects
-
-Dispose and recreate effects based on application state:
-
-```typescript
-let currentEffect: FlowEffect | null = null
-
-function enableLogging(enable: boolean) {
-  // Dispose previous effect
-  currentEffect?.dispose()
-  
-  if (enable) {
-    currentEffect = effect((t) => {
-      console.log('Value:', $data.get(t))
-    })
-  }
-}
-
-// Toggle logging on/off
-enableLogging(true)  // Effect starts
-enableLogging(false) // Effect disposed
-```
-
-### Resource Management
-
-Dispose primitives that manage external resources:
-
-```typescript
-const $wsData = stream<string>((set) => {
-  const ws = new WebSocket('ws://example.com')
-  ws.onmessage = (e) => set(e.data)
-  
-  // Cleanup function called on disposal
-  return () => ws.close()
-})
-
-// Use the stream
-effect((t) => {
-  console.log('Message:', $wsData.get(t))
-})
-
-// Later... close the connection
-$wsData.dispose()
-```
-
-### Interval Cleanup
-
-```typescript
-const $tick = stream<number>((set) => {
-  let count = 0
-  const interval = setInterval(() => {
-    set(count++)
-  }, 1000)
-  
-  // Cleanup: clear interval on disposal
-  return () => clearInterval(interval)
-})
-
-// Later...
-$tick.dispose() // Interval cleared
-```
-
-## Automatic Cleanup
-
-Effects automatically clean up their dependencies when disposed:
-
-```typescript
-const $a = state(1)
-const $b = state(2)
-
-const fx = effect((t) => {
-  console.log($a.get(t) + $b.get(t))
-})
-
-fx.dispose()
-
-// These no longer trigger the effect
-$a.set(10) // No console log
-$b.set(20) // No console log
-```
-
-When an effect is disposed:
-1. It unregisters from all its dependencies
-2. Future changes to those dependencies won't trigger it
-3. The effect's memory is freed
-
-## Best Practices
-
-### 1. Always Dispose in Cleanup Hooks
-
-In any framework with lifecycle hooks, dispose in the cleanup phase:
-
-```typescript
-// React
-useEffect(() => {
-  const fx = effect((t) => {
-    // ... effect code
-  })
-  
-  return () => fx.dispose() // Cleanup
-}, [])
-
-// Vue
-onUnmounted(() => {
-  fx.dispose()
-})
-
-// Svelte
-onDestroy(() => {
-  fx.dispose()
-})
-```
-
-### 2. Group Related Disposables
-
-Use collections to manage multiple disposables:
-
-```typescript
-class DataManager {
-  private disposables = new Set<FlowDisposable>()
-  
-  track(disposable: FlowDisposable) {
-    this.disposables.add(disposable)
-  }
-  
-  cleanup() {
-    this.disposables.forEach(d => d.dispose())
-    this.disposables.clear()
-  }
-}
-
-// Usage
-const manager = new DataManager()
-manager.track(effect((t) => { /* ... */ }))
-manager.track(effect((t) => { /* ... */ }))
-manager.track($someState)
-
-// Clean up everything
-manager.cleanup()
-```
-
-### 3. Dispose in Reverse Order of Creation
-
-Dispose dependents before dependencies:
-
-```typescript
-const $data = state(0)
-const $derived = derivation((t) => $data.get(t) * 2)
-const fx = effect((t) => console.log($derived.get(t)))
-
-// Cleanup: dispose in reverse order
-fx.dispose()      // Effect first (depends on $derived)
-$derived.dispose() // Derivation second (depends on $data)
-$data.dispose()    // State last (no dependencies)
-```
-
-**Why?** Disposing in reverse order prevents:
-- Accessing disposed dependencies
-- Unnecessary recomputations during cleanup
-- Race conditions during shutdown
-
-### 4. Check Disposal State
-
-Use the `disposed` property to check if a primitive has been disposed:
-
-```typescript
-const fx = effect((t) => {
-  console.log($count.get(t))
-})
-
-console.log(fx.disposed) // false
-
-fx.dispose()
-
-console.log(fx.disposed) // true
-```
-
-### 5. Handle Disposal Errors
-
-Wrap disposal in try-catch for robust cleanup:
-
-```typescript
-function cleanupResources(disposables: FlowDisposable[]) {
-  const errors: Error[] = []
-  
-  for (const disposable of disposables) {
-    try {
-      disposable.dispose()
-    } catch (error) {
-      errors.push(error as Error)
-    }
-  }
-  
-  if (errors.length > 0) {
-    console.error('Disposal errors:', errors)
-  }
-}
-```
-
-## Common Pitfalls
-
-### Pitfall 1: Not Disposing Effects
-
-```typescript
-// ❌ Memory leak - effect never disposed
-function updateCounter() {
-  effect((t) => {
-    document.getElementById('count').textContent = $count.get(t)
-  })
-}
-
-// Called 100 times = 100 effects running!
-for (let i = 0; i < 100; i++) {
-  updateCounter()
-}
-
-// ✅ Proper cleanup
-function updateCounter(): () => void {
-  const fx = effect((t) => {
-    document.getElementById('count').textContent = $count.get(t)
-  })
-  
-  return () => fx.dispose()
-}
-
-const cleanup = updateCounter()
-// Later...
-cleanup()
-```
-
-### Pitfall 2: Disposing Too Early
-
-```typescript
-// ❌ Disposed too early
-const fx = effect((t) => {
-  console.log($count.get(t))
-})
-
-fx.dispose() // Effect disposed immediately!
-
-$count.set(1) // No effect runs
-
-// ✅ Dispose at the right time
-const fx = effect((t) => {
-  console.log($count.get(t))
-})
-
-// Use the effect...
-$count.set(1) // Effect runs
-
-// Now dispose when truly done
-fx.dispose()
-```
-
-### Pitfall 3: Forgetting Stream Cleanup
-
-```typescript
-// ❌ WebSocket never closed
-function connectWebSocket() {
-  const $ws = stream<string>((set) => {
-    const socket = new WebSocket('ws://...')
-    socket.onmessage = (e) => set(e.data)
-    // Missing: return () => socket.close()
-  })
-  return $ws
-}
-
-// ✅ Proper cleanup
-function connectWebSocket() {
-  const $ws = stream<string>((set) => {
-    const socket = new WebSocket('ws://...')
-    socket.onmessage = (e) => set(e.data)
-    
-    return () => socket.close() // Cleanup function
-  })
-  return $ws
-}
-```
-
-## Disposal Patterns
-
-### Pattern 1: Disposable Builder
-
-```typescript
-class DisposableBuilder {
-  private disposables: FlowDisposable[] = []
-  
-  add<T extends FlowDisposable>(disposable: T): T {
-    this.disposables.push(disposable)
-    return disposable
-  }
-  
-  disposeAll(): void {
-    // Dispose in reverse order
-    for (let i = this.disposables.length - 1; i >= 0; i--) {
-      this.disposables[i].dispose()
-    }
-    this.disposables = []
-  }
-}
-
-// Usage
-const builder = new DisposableBuilder()
-builder.add(effect((t) => { /* ... */ }))
-builder.add(effect((t) => { /* ... */ }))
-builder.disposeAll()
-```
-
-### Pattern 2: Scoped Disposables
-
-```typescript
-function withDisposables<T>(
-  fn: (track: <D extends FlowDisposable>(d: D) => D) => T
-): T & { cleanup: () => void } {
-  const disposables: FlowDisposable[] = []
-  
-  const track = <D extends FlowDisposable>(d: D): D => {
-    disposables.push(d)
-    return d
-  }
-  
-  const result = fn(track) as T & { cleanup: () => void }
-  result.cleanup = () => disposables.forEach(d => d.dispose())
-  
-  return result
-}
-
-// Usage
-const { cleanup } = withDisposables((track) => {
-  const $count = track(state(0))
-  const fx = track(effect((t) => console.log($count.get(t))))
-})
-
-// Clean up everything
-cleanup()
-```
-
-### Pattern 3: Auto-disposal on Condition
-
-```typescript
-function createAutoDisposeEffect(
-  condition: () => boolean,
-  apply: (t: TrackingContext) => void
-): FlowEffect {
-  const fx = effect((t) => {
-    if (!condition()) {
-      fx.dispose()
-      return
-    }
-    apply(t)
-  })
-  return fx
-}
-
-// Usage: effect auto-disposes when count > 10
-createAutoDisposeEffect(
-  () => $count.pick() <= 10,
-  (t) => console.log('Count:', $count.get(t))
-)
-```
-