@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/guide/primitives/streams.md

@@ -1,931 +0,0 @@
-# Streams
-
-Streams are reactive primitives for handling continuous, event-driven data. Unlike resources that you fetch on demand, streams **push** updates to you whenever new data arrives.
-
-## Understanding Streams
-
-Think of a stream like a **river of data** - it flows continuously, and you dip your cup in whenever you want the latest value. Or like a **news feed** - stories arrive as they happen, and you're notified of each new one.
-
-### Streams vs Resources vs State
-
-| Feature | State | Resource | Stream |
-|---------|-------|----------|--------|
-| Data flow | You set it | You pull (fetch) | It pushes to you |
-| Updates | Manual (`.set()`) | Manual (`.fetch()`) | Automatic (events) |
-| Use case | User input, toggles | API calls, file loading | WebSockets, events, timers |
-| Initial value | Required | Optional | Optional (undefined until first update) |
-| Cleanup | None needed | None needed | **Must return disposer** |
-
-```mermaid
-flowchart LR
-    A[State] -->|You control| B[Value]
-    C[Resource] -->|You request| D[Fetch] -->|Returns| B
-    E[External Event] -->|Pushes| F[Stream] -->|Updates| B
-    
-    style A fill:#FFE6E6
-    style C fill:#E6F3FF
-    style F fill:#E6FFE6
-```
-
-## When to Use Streams
-
-Use streams when:
-- ✅ Data comes from external events (WebSockets, DOM events)
-- ✅ Updates happen continuously (timers, intervals)
-- ✅ You don't control when data arrives
-- ✅ You want push-based reactivity
-
-Use resources when:
-- ✅ You initiate the data fetch
-- ✅ Data is pulled on demand
-- ✅ You control when to refetch
-
-Use state when:
-- ✅ You set the value directly
-- ✅ Updates come from user actions
-- ✅ Data is local to your application
-
-## Creating Streams
-
-The basic syntax:
-
-```typescript
-import { stream } from '@ersbeth/picoflow'
-
-const $stream = stream(
-  (set) => {
-    // Setup: Subscribe to events, start timers, etc.
-    // Call set(value) whenever you have new data
-    
-    // Return cleanup function
-    return () => {
-      // Cleanup: Unsubscribe, clear timers, close connections
-    }
-  },
-  initialValue // Optional initial value
-)
-```
-
-### Anatomy of a Stream
-
-```mermaid
-flowchart TD
-    A[Create stream] --> B[Execute updater function]
-    B --> C[Setup subscriptions/timers]
-    C --> D[Return disposer function]
-    D --> E[Wait for events]
-    E --> F{Event occurs}
-    F -->|Yes| G[Call set new value]
-    G --> H[Notify dependents]
-    H --> E
-    F -->|dispose called| I[Run disposer]
-    I --> J[Cleanup complete]
-```
-
-### The `set` Callback
-
-Inside your updater function, you receive a `set` callback. Call it with a new value whenever you want to update the stream:
-
-```typescript
-const $ticker = stream((set) => {
-  // Call set() to update the value
-  const interval = setInterval(() => {
-    set(Date.now())
-  }, 1000)
-  
-  return () => clearInterval(interval)
-}, Date.now())
-```
-
-### The Disposer
-
-The function you return is crucial - it cleans up resources when the stream is disposed:
-
-```typescript
-const $messages = stream((set) => {
-  const ws = new WebSocket('ws://example.com')
-  
-  ws.onmessage = (event) => {
-    set(event.data) // Update stream with each message
-  }
-  
-  // IMPORTANT: Return cleanup function!
-  return () => {
-    ws.close() // Clean up WebSocket connection
-  }
-})
-
-// Later, cleanup
-$messages.dispose() // Calls the disposer, closes WebSocket
-```
-
-## Basic Examples
-
-### Example 1: Timer
-
-```typescript
-import { stream, effect } from '@ersbeth/picoflow'
-
-const $timer = stream((set) => {
-  let count = 0
-  const interval = setInterval(() => {
-    set(++count)
-  }, 1000)
-  
-  return () => clearInterval(interval)
-}, 0)
-
-effect((t) => {
-  console.log('Timer:', $timer.get(t))
-})
-// Logs: "Timer: 0", "Timer: 1", "Timer: 2", ...
-```
-
-### Example 2: Current Time
-
-```typescript
-const $currentTime = stream((set) => {
-  // Update every second
-  const interval = setInterval(() => {
-    set(new Date())
-  }, 1000)
-  
-  return () => clearInterval(interval)
-}, new Date())
-
-effect((t) => {
-  const time = $currentTime.get(t)
-  document.getElementById('clock').textContent = time.toLocaleTimeString()
-})
-```
-
-### Example 3: Mouse Position
-
-```typescript
-interface Point {
-  x: number
-  y: number
-}
-
-const $mousePosition = stream<Point>((set) => {
-  function handleMouseMove(event: MouseEvent) {
-    set({ x: event.clientX, y: event.clientY })
-  }
-  
-  window.addEventListener('mousemove', handleMouseMove)
-  
-  return () => {
-    window.removeEventListener('mousemove', handleMouseMove)
-  }
-}, { x: 0, y: 0 })
-
-effect((t) => {
-  const pos = $mousePosition.get(t)
-  console.log(`Mouse at (${pos.x}, ${pos.y})`)
-})
-```
-
-## Asynchronous Streams
-
-Async streams handle Promise-based values:
-
-```typescript
-import { streamAsync } from '@ersbeth/picoflow'
-
-const $asyncData = streamAsync((set) => {
-  async function fetchData() {
-    const response = await fetch('/api/data')
-    const data = await response.json()
-    set(data)
-  }
-  
-  const interval = setInterval(fetchData, 5000)
-  fetchData() // Initial fetch
-  
-  return () => clearInterval(interval)
-})
-```
-
-Use with `await` in effects:
-
-```typescript
-effect(async (t) => {
-  const data = await $asyncData.get(t)
-  console.log('Data:', data)
-})
-```
-
-## Stream Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> Created: stream((set) => ...)
-    Created --> Active: Execute updater
-    Active --> Active: set() called → update value
-    Active --> Disposing: .dispose() called
-    Disposing --> Disposed: Execute disposer function
-    Disposed --> [*]
-    
-    note right of Active: Event handlers listening<br/>Timers running<br/>Connections open
-    note right of Disposed: All cleanup complete<br/>No more updates
-```
-
-## Push-Based Data Flow
-
-Here's how streams push data compared to pull-based resources:
-
-```mermaid
-sequenceDiagram
-    participant Event as External Event
-    participant Stream as Stream
-    participant Effect as Effect
-    
-    Note over Stream: Stream created
-    Stream->>Stream: Setup subscriptions
-    
-    Note over Event,Effect: Data flows automatically
-    Event->>Stream: Event occurs
-    Stream->>Stream: Call set(value)
-    Stream->>Effect: Notify of change
-    Effect->>Stream: .get(t)
-    Stream->>Effect: Return latest value
-    
-    Note over Event,Effect: More events...
-    Event->>Stream: Another event
-    Stream->>Stream: Call set(value)
-    Stream->>Effect: Notify again
-```
-
-Compare to pull-based resources:
-
-```mermaid
-sequenceDiagram
-    participant You as Your Code
-    participant Resource as Resource
-    participant API as External API
-    
-    Note over You,API: You control when to fetch
-    You->>Resource: .fetch()
-    Resource->>API: Request data
-    API->>Resource: Return data
-    Resource->>Resource: Update value
-    Resource->>You: Done
-```
-
-## Practical Examples
-
-### Example 1: WebSocket Connection
-
-```typescript
-interface Message {
-  type: string
-  content: string
-  timestamp: number
-}
-
-const $messages = stream<Message>((set) => {
-  const ws = new WebSocket('wss://example.com/socket')
-  
-  ws.onopen = () => {
-    console.log('WebSocket connected')
-  }
-  
-  ws.onmessage = (event) => {
-    const message = JSON.parse(event.data)
-    set(message)
-  }
-  
-  ws.onerror = (error) => {
-    console.error('WebSocket error:', error)
-  }
-  
-  ws.onclose = () => {
-    console.log('WebSocket closed')
-  }
-  
-  // Cleanup
-  return () => {
-    if (ws.readyState === WebSocket.OPEN) {
-      ws.close()
-    }
-  }
-})
-
-// Display messages
-effect((t) => {
-  const message = $messages.get(t)
-  if (message) {
-    displayMessage(message)
-  }
-})
-```
-
-### Example 2: Keyboard Events
-
-```typescript
-const $keyPressed = stream<string>((set) => {
-  function handleKeyDown(event: KeyboardEvent) {
-    set(event.key)
-  }
-  
-  window.addEventListener('keydown', handleKeyDown)
-  
-  return () => {
-    window.removeEventListener('keydown', handleKeyDown)
-  }
-}, '')
-
-effect((t) => {
-  const key = $keyPressed.get(t)
-  console.log('Key pressed:', key)
-})
-```
-
-### Example 3: Countdown Timer
-
-```typescript
-const $countdown = stream((set) => {
-  let remaining = 60 // 60 seconds
-  set(remaining)
-  
-  const interval = setInterval(() => {
-    remaining--
-    set(remaining)
-    
-    if (remaining <= 0) {
-      clearInterval(interval)
-    }
-  }, 1000)
-  
-  return () => clearInterval(interval)
-}, 60)
-
-effect((t) => {
-  const time = $countdown.get(t)
-  document.getElementById('countdown').textContent = `${time}s`
-  
-  if (time === 0) {
-    alert('Time is up!')
-  }
-})
-```
-
-### Example 4: Real-time Notifications
-
-```typescript
-interface Notification {
-  id: string
-  title: string
-  message: string
-}
-
-const $notifications = stream<Notification[]>((set) => {
-  const notifications: Notification[] = []
-  
-  // Server-Sent Events
-  const eventSource = new EventSource('/api/notifications/stream')
-  
-  eventSource.onmessage = (event) => {
-    const notification = JSON.parse(event.data)
-    notifications.push(notification)
-    set([...notifications]) // Update with new array
-  }
-  
-  eventSource.onerror = (error) => {
-    console.error('SSE error:', error)
-  }
-  
-  return () => {
-    eventSource.close()
-  }
-}, [])
-
-// Show notifications
-effect((t) => {
-  const notifications = $notifications.get(t)
-  displayNotifications(notifications)
-})
-```
-
-### Example 5: Window Resize
-
-```typescript
-interface WindowSize {
-  width: number
-  height: number
-}
-
-const $windowSize = stream<WindowSize>((set) => {
-  function updateSize() {
-    set({
-      width: window.innerWidth,
-      height: window.innerHeight
-    })
-  }
-  
-  // Initial size
-  updateSize()
-  
-  // Listen for changes
-  window.addEventListener('resize', updateSize)
-  
-  return () => {
-    window.removeEventListener('resize', updateSize)
-  }
-}, { width: window.innerWidth, height: window.innerHeight })
-
-// Respond to size changes
-effect((t) => {
-  const size = $windowSize.get(t)
-  console.log(`Window: ${size.width}x${size.height}`)
-  
-  if (size.width < 768) {
-    enableMobileLayout()
-  } else {
-    enableDesktopLayout()
-  }
-})
-```
-
-## Stream Patterns
-
-### Pattern 1: Filtered Stream
-
-```typescript
-// Only emit values that pass a condition
-function filteredStream<T>(
-  setup: (set: (value: T) => void) => () => void,
-  predicate: (value: T) => boolean,
-  initial?: T
-) {
-  return stream<T>((set) => {
-    return setup((value) => {
-      if (predicate(value)) {
-        set(value)
-      }
-    })
-  }, initial)
-}
-
-// Usage
-const $significantMoves = filteredStream(
-  (set) => {
-    let lastX = 0
-    function handleMove(event: MouseEvent) {
-      // Only emit if mouse moved > 10px
-      if (Math.abs(event.clientX - lastX) > 10) {
-        lastX = event.clientX
-        set(event.clientX)
-      }
-    }
-    window.addEventListener('mousemove', handleMove)
-    return () => window.removeEventListener('mousemove', handleMove)
-  },
-  (x) => true,
-  0
-)
-```
-
-### Pattern 2: Debounced Stream
-
-```typescript
-function debouncedStream<T>(
-  setup: (set: (value: T) => void) => () => void,
-  delay: number,
-  initial?: T
-) {
-  return stream<T>((set) => {
-    let timeout: number | null = null
-    
-    const disposer = setup((value) => {
-      if (timeout) clearTimeout(timeout)
-      timeout = setTimeout(() => set(value), delay)
-    })
-    
-    return () => {
-      if (timeout) clearTimeout(timeout)
-      disposer()
-    }
-  }, initial)
-}
-
-// Usage: Debounce input changes
-const $searchQuery = state('')
-const $debouncedQuery = debouncedStream((set) => {
-  return effect((t) => {
-    set($searchQuery.get(t))
-  }).dispose
-}, 300)
-```
-
-### Pattern 3: Combined Streams
-
-```typescript
-// Merge multiple streams
-function mergeStreams<T>(...streams: FlowStream<T>[]) {
-  return stream<T>((set) => {
-    const disposers = streams.map(stream => {
-      return effect((t) => {
-        set(stream.get(t))
-      })
-    })
-    
-    return () => {
-      disposers.forEach(d => d.dispose())
-    }
-  })
-}
-```
-
-### Pattern 4: Stream from Observable
-
-```typescript
-import { Observable } from 'rxjs'
-
-function fromObservable<T>(observable: Observable<T>, initial?: T) {
-  return stream<T>((set) => {
-    const subscription = observable.subscribe({
-      next: (value) => set(value),
-      error: (error) => console.error('Observable error:', error)
-    })
-    
-    return () => subscription.unsubscribe()
-  }, initial)
-}
-
-// Usage
-import { interval } from 'rxjs'
-const $rxTimer = fromObservable(interval(1000), 0)
-```
-
-## Cleanup and Disposal
-
-**The most important rule:** Always return a disposer function!
-
-### Why Cleanup Matters
-
-```mermaid
-flowchart TD
-    A[Stream Created] --> B[Subscriptions Active]
-    B --> C[Timers Running]
-    C --> D[Connections Open]
-    D --> E{Stream Disposed?}
-    E -->|No| F[⚠️ MEMORY LEAK]
-    E -->|Yes| G[Run Disposer]
-    G --> H[Clear Subscriptions]
-    H --> I[Stop Timers]
-    I --> J[Close Connections]
-    J --> K[✅ Clean]
-    
-    style F fill:#FFE6E6
-    style K fill:#E6FFE6
-```
-
-### Good Cleanup Examples
-
-```typescript
-// ✅ Timer cleanup
-const $timer = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id) // Cleanup!
-}, Date.now())
-
-// ✅ Event listener cleanup
-const $clicks = stream((set) => {
-  const handler = () => set(Date.now())
-  window.addEventListener('click', handler)
-  return () => window.removeEventListener('click', handler) // Cleanup!
-})
-
-// ✅ WebSocket cleanup
-const $ws = stream((set) => {
-  const socket = new WebSocket('ws://example.com')
-  socket.onmessage = (e) => set(e.data)
-  return () => socket.close() // Cleanup!
-})
-
-// ✅ Multiple cleanups
-const $multi = stream((set) => {
-  const interval = setInterval(() => set('tick'), 1000)
-  const handler = () => set('click')
-  window.addEventListener('click', handler)
-  
-  return () => {
-    clearInterval(interval)
-    window.removeEventListener('click', handler)
-  } // Cleanup both!
-})
-```
-
-### Bad Cleanup Examples
-
-```typescript
-// ❌ No cleanup - memory leak!
-const $bad = stream((set) => {
-  setInterval(() => set(Date.now()), 1000)
-  // Missing: return () => clearInterval(...)
-})
-
-// ❌ Cleanup doesn't work
-const $broken = stream((set) => {
-  setInterval(() => set(Date.now()), 1000)
-  return () => {
-    clearInterval(123) // Wrong ID!
-  }
-})
-```
-
-## Error Handling
-
-### Basic Error Handling
-
-```typescript
-const $data = streamAsync((set) => {
-  const ws = new WebSocket('wss://example.com')
-  
-  ws.onmessage = async (event) => {
-    try {
-      const data = JSON.parse(event.data)
-      set(data)
-    } catch (error) {
-      console.error('Failed to parse message:', error)
-    }
-  }
-  
-  ws.onerror = (error) => {
-    console.error('WebSocket error:', error)
-  }
-  
-  return () => ws.close()
-})
-```
-
-### With Error State
-
-```typescript
-const $wsData = stream<any>((set) => {
-  const ws = new WebSocket('wss://example.com')
-  
-  ws.onopen = () => $wsStatus.set('connected')
-  ws.onclose = () => $wsStatus.set('disconnected')
-  ws.onerror = () => $wsStatus.set('error')
-  ws.onmessage = (e) => set(JSON.parse(e.data))
-  
-  return () => ws.close()
-})
-
-const $wsStatus = state<'connected' | 'disconnected' | 'error'>('disconnected')
-
-effect((t) => {
-  const status = $wsStatus.get(t)
-  
-  switch (status) {
-    case 'connected':
-      showConnected()
-      break
-    case 'error':
-      showError('Connection failed')
-      break
-    case 'disconnected':
-      showDisconnected()
-      break
-  }
-})
-```
-
-## Best Practices
-
-### 1. Always Return a Disposer
-
-```typescript
-// ✅ Good
-const $stream = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id)
-}, Date.now())
-
-// ❌ Bad - no cleanup
-const $stream = stream((set) => {
-  setInterval(() => set(Date.now()), 1000)
-  // Missing return!
-}, Date.now())
-```
-
-### 2. Provide Initial Values
-
-```typescript
-// ✅ Good - immediate value available
-const $time = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id)
-}, Date.now()) // Initial value
-
-// ⚠️ Okay but requires undefined check
-const $time = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id)
-}) // undefined initially
-```
-
-### 3. Handle Connection Errors
-
-```typescript
-const $ws = stream((set) => {
-  const ws = new WebSocket('wss://example.com')
-  
-  ws.onerror = (error) => {
-    console.error('WebSocket error:', error)
-    // Maybe set error state or reconnect
-  }
-  
-  ws.onmessage = (e) => set(e.data)
-  
-  return () => ws.close()
-})
-```
-
-### 4. Avoid Duplicate Subscriptions
-
-```typescript
-// ❌ Bad - creates new stream on every render
-function MyComponent() {
-  const $stream = stream((set) => { /* ... */ })
-  // New stream created each time!
-}
-
-// ✅ Good - create stream once
-const $stream = stream((set) => { /* ... */ })
-
-function MyComponent() {
-  // Use existing stream
-}
-```
-
-### 5. Clean Up in Components
-
-```typescript
-// React example
-function useStream<T>(stream: FlowStream<T>) {
-  useEffect(() => {
-    return () => {
-      stream.dispose() // Cleanup when component unmounts
-    }
-  }, [stream])
-  
-  // ... use stream
-}
-```
-
-## Comparing: Stream vs Resource
-
-```mermaid
-flowchart TD
-    A{Who initiates updates?} -->|You do pull| B[Use Resource]
-    A -->|External pushes| C[Use Stream]
-    B --> D[.fetch to get data]
-    C --> E[.set called by events]
-    D --> F[HTTP APIs<br/>File reads<br/>Database queries]
-    E --> G[WebSockets<br/>DOM events<br/>Timers<br/>Server-Sent Events]
-```
-
-## Common Pitfalls
-
-### Pitfall 1: Forgetting Cleanup
-
-```typescript
-// ❌ Memory leak!
-const $bad = stream((set) => {
-  setInterval(() => set(Date.now()), 1000)
-})
-
-// ✅ Proper cleanup
-const $good = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id)
-}, Date.now())
-```
-
-### Pitfall 2: Wrong Cleanup Reference
-
-```typescript
-// ❌ Loses reference to interval ID
-const $bad = stream((set) => {
-  setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(999) // Wrong ID!
-}, Date.now())
-
-// ✅ Correct reference
-const $good = stream((set) => {
-  const id = setInterval(() => set(Date.now()), 1000)
-  return () => clearInterval(id) // Correct ID
-}, Date.now())
-```
-
-### Pitfall 3: Not Handling Errors
-
-```typescript
-// ❌ Unhandled errors crash app
-const $bad = stream((set) => {
-  const ws = new WebSocket('wss://example.com')
-  ws.onmessage = (e) => set(JSON.parse(e.data)) // Might throw!
-  return () => ws.close()
-})
-
-// ✅ Error handling
-const $good = stream((set) => {
-  const ws = new WebSocket('wss://example.com')
-  ws.onmessage = (e) => {
-    try {
-      set(JSON.parse(e.data))
-    } catch (error) {
-      console.error('Parse error:', error)
-    }
-  }
-  ws.onerror = (error) => console.error('WS error:', error)
-  return () => ws.close()
-})
-```
-
-## Complete Example: Live Chat
-
-```typescript
-import { stream, state, derivation, effect } from '@ersbeth/picoflow'
-
-interface ChatMessage {
-  id: string
-  user: string
-  text: string
-  timestamp: number
-}
-
-// WebSocket stream for incoming messages
-const $incomingMessages = stream<ChatMessage>((set) => {
-  const ws = new WebSocket('wss://chat.example.com')
-  
-  ws.onopen = () => {
-    console.log('Chat connected')
-    $connected.set(true)
-  }
-  
-  ws.onmessage = (event) => {
-    const message = JSON.parse(event.data)
-    set(message)
-  }
-  
-  ws.onerror = (error) => {
-    console.error('Chat error:', error)
-    $connected.set(false)
-  }
-  
-  ws.onclose = () => {
-    console.log('Chat disconnected')
-    $connected.set(false)
-  }
-  
-  return () => {
-    ws.close()
-  }
-})
-
-// Connection state
-const $connected = state(false)
-
-// All messages
-const $messages = state<ChatMessage[]>([])
-
-// Add incoming messages to list
-effect((t) => {
-  const newMessage = $incomingMessages.get(t)
-  if (newMessage) {
-    $messages.set(messages => [...messages, newMessage])
-  }
-})
-
-// Unread count
-const $lastReadTime = state(Date.now())
-const $unreadCount = derivation((t) => {
-  const messages = $messages.get(t)
-  const lastRead = $lastReadTime.get(t)
-  return messages.filter(m => m.timestamp > lastRead).length
-})
-
-// Display messages
-effect((t) => {
-  const messages = $messages.get(t)
-  const connected = $connected.get(t)
-  
-  renderChatUI(messages, connected)
-})
-
-// Update unread badge
-effect((t) => {
-  const unread = $unreadCount.get(t)
-  document.getElementById('unread-badge').textContent = String(unread)
-  document.getElementById('unread-badge').hidden = unread === 0
-})
-
-// Mark as read
-function markAllRead() {
-  $lastReadTime.set(Date.now())
-}
-```