@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/guide/primitives/effects.md

@@ -1,124 +1,76 @@
-# Effects
+# Side Effects & Subscribe
 
-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.
+Side effects are how you perform **actions** 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.
+Side effects are created by subscribing to reactive primitives using `subscribe()` or `.subscribe()`. When you subscribe, you get a `FlowEffect` object that can be disposed to stop the side effect.
 
 ### Key Characteristics
 
+- **Two syntaxes**: `.subscribe()` for single primitive, `subscribe()` for multiple
 - **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
+- **Returns FlowEffect**: Disposable handle to stop the subscription
 
-## When to Use Effects
+## When to Use Subscribe
 
-Use effects when you need to:
+Use subscribe 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:
+Don't use subscribe 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 Side Effects
 
-Creating an effect is straightforward:
+There are two ways to create side effects, depending on your needs:
 
-```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.
+### Single Primitive - `.subscribe()`
 
-## 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:
+When reacting to a single primitive, use the `.subscribe()` method:
 
 ```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:
+import { state } from '@ersbeth/picoflow'
 
-```typescript
-const $activeUserId = state(1)
-const $userDatabase = state({ /* large object */ })
+const $count = state(0)
 
-effect((t) => {
-  const activeId = $activeUserId.get(t)     // Reactive
-  const database = $userDatabase.pick()     // Snapshot
-  
-  const user = database[activeId]
-  console.log('Active user:', user)
+// Subscribe directly to the primitive
+const effect = $count.subscribe((value) => {
+  console.log('Count is:', value)
 })
 
-// Only changes to $activeUserId trigger the effect
-// Changes to $userDatabase are ignored
+// Later: dispose the effect
+effect.dispose()
 ```
 
-### Watching Signals with `.watch(t)`
+### Multiple Primitives - `subscribe()`
 
-Signals are special - they don't hold values, so use `.watch(t)` to track them:
+When combining multiple primitives, use the global `subscribe()` function:
 
 ```typescript
-import { signal, effect } from '@ersbeth/picoflow'
+import { state, subscribe } 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
+// Combine multiple values
+const effect = subscribe(
+  (t) => ({ first: $firstName.get(t), last: $lastName.get(t) }),
+  (data) => {
+    console.log('Full name:', data.first, data.last)
+  }
+)
 ```
 
+The parameter `t` is the **FlowTracker** - your tool for creating dependencies.
+
+## Using Side-Effects
+
 ### Conditional Dependencies
 
 Dependencies can be conditional - they're re-evaluated on each execution:
@@ -127,43 +79,51 @@ Dependencies can be conditional - they're re-evaluated on each execution:
 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')
+subscribe(
+  (t) => {
+    const show = $showDetails.get(t)
+    if (show) {
+      return { show: true, details: $details.get(t) }
+    }
+    return { show: false, details: null }
+  },
+  (data) => {
+    if (data.show) {
+      console.log('Details:', data.details)
+    } 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
+// When $showDetails is false, changes to $details don't trigger the subscription
+$details.set({ info: 'new secret' }) // Subscription 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!
+$showDetails.set(true) // Subscription runs and now tracks $details
+$details.set({ info: 'updated' }) // Now this triggers the subscription!
 ```
 
-### Disposing with `.dispose()`
+### Dispose
 
-Effects run indefinitely unless disposed. Always clean them up when no longer needed:
+Subscriptions 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))
+// Create subscription
+const effect = $count.subscribe((value) => {
+  console.log(value)
 })
 
-// Later... stop the effect
-fx.dispose()
+// Later... stop the subscription
+effect.dispose()
 
-// After disposal, the effect won't run anymore
+// After disposal, the subscription won't run anymore
 $count.set(10) // No console log
 ```
 
-**Always dispose effects when:**
+**Always dispose subscriptions when:**
 - Component unmounts (in UI frameworks)
 - Feature is disabled
 - User navigates away
@@ -176,25 +136,25 @@ $count.set(10) // No console log
 function createUserPanel(userId: number) {
   const $user = state(getUserData(userId))
   
-  effect((t) => {
-    updateUI($user.get(t))
+  $user.subscribe((user) => {
+    updateUI(user)
   })
-  // Effect never disposed! ⚠️
+  // Subscription never disposed! ⚠️
 }
 
-// Called 100 times = 100 effects still running!
+// Called 100 times = 100 subscriptions still running!
 
 // ✅ Proper cleanup
 function createUserPanel(userId: number) {
   const $user = state(getUserData(userId))
   
-  const fx = effect((t) => {
-    updateUI($user.get(t))
+  const effect = $user.subscribe((user) => {
+    updateUI(user)
   })
   
   return {
     dispose: () => {
-      fx.dispose()
+      effect.dispose()
       $user.dispose()
     }
   }
@@ -203,129 +163,140 @@ function createUserPanel(userId: number) {
 
 ## 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.
+Subscriptions 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.
+When you create a subscription, it runs **synchronously** - not on the next tick, but right away. This allows subscriptions to establish initial dependencies and perform initial side effects. When a dependency changes, the subscription re-executes synchronously.
 
 ```mermaid
 sequenceDiagram
     participant User
     participant $count as $count (State)
-    participant Effect
+    participant Subscription
     
-    Note over User,Effect: 1. Creation Phase
-    User->>Effect: Create effect((t) => ...)
-    activate Effect
-    Note over Effect: Execute immediately
+    Note over User,Subscription: 1. Creation Phase
+    User->>Subscription: "Create $count.subscribe(...)"
+    activate Subscription
+    Note over Subscription: Execute immediately
     
-    Effect->>$count: get(t)
+    Subscription->>$count: Read value
     activate $count
-    Note over $count: Register Effect as dependent
-    $count-->>Effect: 0
+    Note over $count: Register Subscription as dependent
+    $count-->>Subscription: 0
     deactivate $count
     
-    Note over Effect: console.log("Count: 0")
-    Note over Effect: Track: depends on $count
-    deactivate Effect
+    Note over Subscription: "console.log(\"Count: 0\")"
+    Note over Subscription: Track: depends on $count
+    deactivate Subscription
     
-    Note over User,Effect: 2. Change Phase
+    Note over User,Subscription: 2. Change Phase
     User->>$count: set(5)
     activate $count
     Note over $count: Value changed: 0 → 5
     
-    $count->>Effect: Notify & schedule
+    $count->>Subscription: Notify & schedule
     deactivate $count
     
-    activate Effect
-    Note over Effect: Clear old dependencies<br/>Execute function
+    activate Subscription
+    Note over Subscription: Clear old dependencies<br/>Execute callback
     
-    Effect->>$count: get(t)
+    Subscription->>$count: Read value
     activate $count
-    Note over $count: Register Effect as dependent
-    $count-->>Effect: 5
+    Note over $count: Register Subscription as dependent
+    $count-->>Subscription: 5
     deactivate $count
     
-    Note over Effect: console.log("Count: 5")
-    Note over Effect: Track: depends on $count
-    deactivate Effect
+    Note over Subscription: "console.log(\"Count: 5\")"
+    Note over Subscription: Track: depends on $count
+    deactivate Subscription
     
-    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
+    Note over User,Subscription: 3. Disposal Phase
+    User->>Subscription: dispose()
+    activate Subscription
+    Note over Subscription: Clear dependencies<br/>Unregister from $count
+    Note over Subscription: Mark as disposed
+    deactivate Subscription
     
     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)
+    Note over Subscription: (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
+1. **Creation & Immediate Execution**: The subscription callback runs synchronously during creation
+2. **Dependency Registration**: Reactive reads register the subscription as a dependent
+3. **Change Notification**: When dependencies change, the subscription is scheduled to re-run
+4. **Re-execution**: Subscription 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)
+- **Subscriptions establish dependencies on first run** (no waiting)
 - **Changes trigger re-execution immediately** (synchronous)
 - **Dynamic dependencies adapt automatically** (conditional tracking)
 
 ## Best Practices
 
-### Keep Effects Focused
+### Keep Subscriptions Focused
 
-Each effect should do one thing:
+Each subscription 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))
+$count.subscribe((value) => {
+  updateDOM(value)
+  saveToStorage(value)
+  sendAnalytics(value)
+  updateTitle(value)
 })
 
 // ✅ 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)))
+$count.subscribe((value) => updateDOM(value))
+$count.subscribe((value) => saveToStorage(value))
+$count.subscribe((value) => sendAnalytics(value))
+$count.subscribe((value) => updateTitle(value))
 ```
 
-**Why?** Easier to debug, test, and disable individual effects.
+**Why?** Easier to debug, test, and disable individual subscriptions.
 
-### Avoid Creating Effects Inside Effects
+### Avoid Creating Subscriptions Inside Subscriptions
 
 ```typescript
-// ❌ Bad - creates new effects on every run
-effect((t) => {
-  const count = $count.get(t)
-  effect((t) => {
-    console.log('Nested:', count) // Memory leak!
+// ❌ Bad - creates new subscriptions on every run
+$count.subscribe((count) => {
+  $other.subscribe((other) => {
+    console.log('Nested:', count, other) // Memory leak!
   })
 })
 
-// ✅ Good - create effects at the top level
-effect((t) => {
-  const count = $count.get(t)
-  console.log('Count:', count)
-})
+// ✅ Good - create subscriptions at the top level
+subscribe(
+  (t) => ({ count: $count.get(t), other: $other.get(t) }),
+  (data) => {
+    console.log('Values:', data.count, data.other)
+  }
+)
 ```
 
 ### Handle Errors
 
-Wrap risky operations in try-catch:
+Use the `onError` callback or wrap risky operations in try-catch:
 
 ```typescript
-effect((t) => {
-  const data = $data.get(t)
-  
+// ✅ Using onError callback
+subscribe(
+  (t) => $data.get(t),
+  (data) => {
+    updateDOM(data)
+  },
+  (error) => {
+    console.error('Failed to update DOM:', error)
+  }
+)
+
+// ✅ Or use try-catch
+$data.subscribe((data) => {
   try {
     updateDOM(data)
   } catch (error) {
@@ -336,20 +307,18 @@ effect((t) => {
 
 ### Be Careful with Infinite Loops
 
-Don't update dependencies inside the same effect:
+Don't update dependencies inside the same subscription:
 
 ```typescript
 const $count = state(0)
 
 // ❌ Infinite loop!
-effect((t) => {
-  const count = $count.get(t)
+$count.subscribe((count) => {
   $count.set(count + 1) // Triggers itself!
 })
 
 // ✅ Use a different state
-effect((t) => {
-  const count = $count.get(t)
+$count.subscribe((count) => {
   $doubled.set(count * 2) // Updates different state
 })
 ```
@@ -361,8 +330,7 @@ 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
+$refresh.subscribe(() => {
   fetchData()
 })
 
@@ -372,87 +340,33 @@ $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)
-})
+### Not Disposing Subscriptions
 
-$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.
+**Problem**: Subscriptions continue running even when no longer needed.
 
 ```typescript
 // ❌ Memory leak in component lifecycle
 function MyComponent() {
-  effect((t) => {
-    updateView($data.get(t))
+  $data.subscribe((data) => {
+    updateView(data)
   })
   // Never disposed!
 }
 
-// Each component creation adds another effect that never stops
+// Each component creation adds another subscription that never stops
 ```
 
-**Solution**: Always dispose effects when done:
+**Solution**: Always dispose subscriptions when done:
 
 ```typescript
 // ✅ Proper cleanup
 function MyComponent() {
-  const fx = effect((t) => {
-    updateView($data.get(t))
+  const effect = $data.subscribe((data) => {
+    updateView(data)
   })
   
   return {
-    cleanup: () => fx.dispose()
+    cleanup: () => effect.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.
+```