@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/guide/advanced/disposal.md

@@ -0,0 +1,426 @@
+# 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))
+)
+```
+

package/docs/guide/advanced/solidjs.md

@@ -0,0 +1,221 @@
+# Use with SolidJS
+
+PicoFlow provides seamless integration with SolidJS through the `@ersbeth/picoflow/solid` module. This integration allows you to use PicoFlow's reactive primitives within SolidJS components, combining PicoFlow's explicit tracking model with SolidJS's automatic dependency tracking.
+
+## Why Use PicoFlow with SolidJS?
+
+PicoFlow and SolidJS complement each other well:
+
+- **PicoFlow** provides explicit control over reactivity with fine-grained tracking
+- **SolidJS** offers automatic dependency tracking within components
+- **Together** you get the best of both worlds: explicit control in your business logic and automatic reactivity in your UI
+
+### When to Use This Integration
+
+Use PicoFlow with SolidJS when:
+
+- ✅ You want explicit control over reactivity in shared business logic
+- ✅ You need fine-grained tracking (e.g., specific array operations)
+- ✅ You're building a library that should work with multiple frameworks
+- ✅ You want to share reactive logic between different UI frameworks
+- ✅ You prefer PicoFlow's explicit tracking model for complex state management
+
+Use pure SolidJS when:
+
+- ✅ Your reactive logic is tightly coupled to components
+- ✅ You prefer automatic dependency tracking everywhere
+- ✅ You don't need fine-grained control over reactivity
+
+## Installation
+
+First, ensure you have both PicoFlow and SolidJS installed:
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @ersbeth/picoflow solid-js
+```
+
+```bash [npm]
+npm install @ersbeth/picoflow solid-js
+```
+
+```bash [yarn]
+yarn add @ersbeth/picoflow solid-js
+```
+
+:::
+
+Then import the integration utilities:
+
+```typescript
+import { from } from '@ersbeth/picoflow/solid'
+import { state, derivation, resource } from '@ersbeth/picoflow'
+```
+
+## PicoFlow to SolidJS
+
+The `from()` function converts PicoFlow observables into SolidJS primitives that work seamlessly in Solid components.
+
+### Basic Conversion
+
+Convert any PicoFlow observable to a Solid primitive:
+
+```typescript
+import { from } from '@ersbeth/picoflow/solid'
+import { state } from '@ersbeth/picoflow'
+
+// Create PicoFlow state
+const $count = state(0)
+
+
+// Use in Solid component
+function Counter() {
+  // Convert to Solid primitive
+  const count = from($count)
+  return <div>Count: {count.get()}</div>
+}
+```
+
+The `from()` function uses SolidJS's `onMount` and `onCleanup` to properly dispose of the internal PicoFlow effects when the component unmounts. You don't need to manually dispose of converted primitives.
+
+### Conversion Rules
+
+The `from()` function automatically determines the right Solid primitive based on the value type:
+
+| PicoFlow Input | Solid Output | When |
+|----------------|--------------|------|
+| `FlowObservable<T>` (non-Promise) | `SolidDerivation<T>` | Synchronous values |
+| `FlowObservable<Promise<T>>` | `SolidResource<T>` | Asynchronous values |
+| `(t) => T` (getter function) | `SolidDerivation<T>` | Synchronous computation |
+| `(t) => Promise<T>` (getter function) | `SolidResource<T>` | Asynchronous computation |
+
+## SolidJS Primitives
+
+PicoFlow also provides Solid-style primitives that you can use directly in Solid components. These are thin wrappers around SolidJS's built-in primitives with a class-based API consistent with PicoFlow's style.
+
+### SolidState
+
+`SolidState` wraps SolidJS's `createSignal`:
+
+```typescript
+import { SolidState } from '@ersbeth/picoflow/solid'
+
+// Use in component
+function Counter() {
+
+  // Create Solid state
+  const count = new SolidState(0)
+
+  return (
+    <div>
+      <p>Count: {count.get()}</p>
+      <button onClick={() => count.set(count.get() + 1)}>Increment</button>
+      <button onClick={() => count.set(prev => prev + 1)}>Increment (updater)</button>
+    </div>
+  )
+}
+```
+
+**When to use:** When you want a simple reactive state that's only used in Solid components.
+
+### SolidDerivation
+
+`SolidDerivation` wraps SolidJS's `createMemo`:
+
+```typescript
+import { SolidState, SolidDerivation } from '@ersbeth/picoflow/solid'
+
+// Use in component
+function NameDisplay() {
+  const firstName = new SolidState('John')
+  const lastName = new SolidState('Doe')
+  
+  // Create derived value
+  const fullName = new SolidDerivation(() => {
+    return `${firstName.get()} ${lastName.get()}`
+  })
+  return <div>{fullName.get()}</div> // Automatically updates
+}
+```
+
+**When to use:** When you need computed values that are only used in Solid components.
+
+### SolidResource
+
+`SolidResource` wraps SolidJS's `createResource`:
+
+```typescript
+import { SolidResource } from '@ersbeth/picoflow/solid'
+
+// Use in component
+function UserProfile() {
+
+  // Create resource
+  const user = new SolidResource(async () => {
+    const res = await fetch('/api/user')
+    return res.json()
+  })
+
+  const userData = user.get()
+  
+  return (
+    <div>
+      {user.state() === 'pending' && <p>Loading...</p>}
+      {state.state() === 'ready' && user.latest() && (
+        <>
+          <h1>{user.latest().name}</h1>
+          <p>{user.latest().email}</p>
+        </>
+      )}
+      {user.state() === 'errored' && <p>Error loading user</p>}
+      <button onClick={() => user.refetch()}>Refresh</button>
+    </div>
+  )
+}
+```
+
+**When to use:** When you need async data loading that integrates with SolidJS's Suspense and ErrorBoundary.
+
+## Complete Examples
+
+```typescript
+import { from } from '@ersbeth/picoflow/solid'
+import { state, derivation } from '@ersbeth/picoflow'
+
+// Create PicoFlow global state and derivation
+const $count = state(0)
+const $isEven = derivation((t) => $count.get(t) % 2 === 0)
+
+// Use in component
+function Counter() {
+
+  // Convert to Solid primitives
+  const count = from($count)
+  const isEven = from($isEven)
+  
+  return (
+    <div>
+      <p>Count: {count.get()}</p>
+      <p>{isEven.get() ? 'Even' : 'Odd'}</p>
+      <button onClick={() => $count.set(prev => prev + 1)}>Increment</button>
+      <button onClick={() => $count.set(prev => prev - 1)}>Decrement</button>
+    </div>
+  )
+}
+```
+
+## Best Practices
+
+### When to Convert vs Use Directly
+
+**Convert PicoFlow observables (`from()`) when:**
+- ✅ You have existing PicoFlow state/logic to reuse
+- ✅ You want to share reactive logic between frameworks
+- ✅ You need fine-grained PicoFlow features (arrays, maps, streams)
+- ✅ Your business logic is framework-agnostic
+
+**Use Solid primitives directly when:**
+- ✅ The state is only used in Solid components
+- ✅ You don't need PicoFlow's advanced features
+- ✅ You prefer SolidJS's automatic tracking for simple cases