@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/guide/introduction/lifecycle.md

@@ -1,368 +0,0 @@
-# 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))
-$c.subscribe((c) => console.log('C =', c))
-```
-
-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 `FlowTracker` will be created when the derivation is first accessed
-   - Still no computed value yet
-
-4. **`$c.subscribe(...)` creates the effect**
-   - A new `FlowEffect` instance is created
-   - **The effect executes immediately** (not lazy!)
-   - During execution:
-     - The subscribe method internally calls `$c.get(t)` with a `FlowTracker`
-     - This triggers `$c` to initialize (first access)
-     - `$c` creates its own `FlowTracker` and runs its compute function
-     - 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`
-     - The value `3` is registered as a dependency of the effect
-   - Callback is called with `3` and 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: $c.subscribe(...)
-    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 effect = $expensive.subscribe((value) => {
-  if (shouldDisplay) display(value)
-})
-
-// When not needed, just dispose the effect
-effect.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 .subscribe()? (not .pick())
-// 3. Is anything disposed?
-
-$state.subscribe((value) => {
-  console.log('Effect created') // Should log immediately
-  console.log('Value:', value)
-})
-```
-
-### 3. Avoid Memory Leaks
-
-```typescript
-// Always dispose effects when done
-const disposables: FlowDisposable[] = []
-
-disposables.push(subscribe((t) => { /* ... */ }, () => { /* ... */ }))
-disposables.push(subscribe((t) => { /* ... */ }, () => { /* ... */ }))
-
-// Clean up
-disposables.forEach(d => d.dispose())
-```

package/docs/guide/primitives/array.md

@@ -1,286 +0,0 @@
-# Arrays
-
-PicoFlow provides reactive arrays with **fine-grained tracking**. Instead of reacting to the entire array changing, you can react to specific operations like pushing, popping, or splicing individual items.
-
-
-## When to Use Arrays
-
-Use arrays when you need to:
-
-- ✅ Track large collections with fine-grained updates
-- ✅ React to specific operations (additions, removals, updates) separately
-- ✅ Optimize performance by avoiding full array re-processing
-
-Don't use arrays when:
-
-- ❌ You don't need fine-grained tracking (use `state` with an array)
-- ❌ You need key-value operations (use `map` instead)
-
-## Creating Arrays
-
-Creating a reactive array is straightforward:
-
-```typescript
-import { array } from '@ersbeth/picoflow'
-
-// Create with initial values
-const $todos = array([
-  { id: 1, text: 'Learn PicoFlow', done: false },
-  { id: 2, text: 'Build app', done: false }
-])
-
-// Create empty
-const $items = array<string>()
-```
-
-## Using Arrays
-
-Arrays provide multiple ways to track changes and perform operations.
-
-### Array Operations
-
-Arrays provide several operations: `set()`, `update()`, `push()`, `pop()`, `unshift()`, `shift()`, `splice()`, and `clear()`.
-
-```typescript
-const $list = array<number>([])
-
-// Replace entire array
-$list.set([1, 2, 3])
-
-// Replace item at index
-$list.update(0, 10)
-
-// Add to end
-$list.push(4)
-
-// Add to start
-$list.unshift(0)
-
-// Remove from end
-$list.pop()
-
-// Remove from start
-$list.shift()
-
-// Splice (remove/add at index)
-$list.splice(1, 1, 99) // Remove 1 item at index 1, add 99
-
-// Clear all
-$list.clear()
-
-// Read (reactive)
-$list.subscribe((items) => {
-  // Track entire array
-  console.log(items)
-})
-
-// Read (non-reactive)
-const snapshot = $list.pick()
-```
-
-**Important**: 
-- `update(index, item)` throws an error if the index is out of bounds
-- `push(item)` only accepts a single item
-- `splice(start, deleteCount, ...items)` accepts multiple items to add
-
-### Whole Array Tracking
-
-Track when the entire array changes (any operation):
-
-```typescript
-const $items = array([1, 2, 3])
-
-$items.subscribe((items) => {
-  console.log('Array changed:', items)
-})
-
-$items.push(4)      // Logs: "Array changed: [1,2,3,4]"
-$items.pop()        // Logs: "Array changed: [1,2,3]"
-$items.splice(1, 1) // Logs: "Array changed: [1,3]"
-```
-
-Use `.get(t)` when you need the entire array's current state. It returns a copy of the array.
-
-### Fine-Grained Tracking
-
-Track specific operations with `$lastAction`:
-
-```typescript
-const $items = array<number>([])
-
-$items.$lastAction.subscribe(
-  (action) => {
-    if (!action) return
-    
-    switch (action.type) {
-      case 'push':
-        console.log('Pushed:', action.item)
-        break
-      case 'pop':
-        console.log('Popped')
-        break
-      case 'splice':
-        console.log('Splice at', action.start, ':', action.deleteCount, 'deleted,', action.items.length, 'added')
-        break
-      case 'update':
-        console.log('Set item at', action.index, 'to', action.item)
-        break
-      // ... other operations
-    }
-  }
-)
-
-$items.push(1)          // Logs: "Pushed: 1"
-$items.push(2)          // Logs: "Pushed: 2"
-$items.pop()            // Logs: "Popped"
-$items.splice(0, 1)     // Logs: "Splice at 0: 1 deleted, 0 added"
-```
-
-## Lifecycle
-
-When you create a subscription that tracks an array:
-
-1. **Registration**: The array registers the subscription as a watcher
-2. **Operation**: When you call `push()`, `pop()`, `splice()`, etc., the array updates internally
-3. **Signal Update**: The `$lastAction` signal is updated with the operation details
-4. **Notification**: All watching subscriptions are scheduled to run
-5. **Re-execution**: Each watching subscription re-executes its function
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Array as $todos (Array)
-    participant Signal as $lastAction
-    participant Subscription
-    
-    Note over User,Subscription: 1. Setup Phase
-    User->>Subscription: Create subscription
-    activate Subscription
-    Subscription->>Array: get(t)
-    Note over Array: Register Subscription as watcher
-    Subscription->>Signal: get(t)
-    Note over Signal: Register Subscription as watcher
-    Subscription->>Subscription: Execute function
-    Note over Subscription: Initial render
-    deactivate Subscription
-    
-    Note over User,Subscription: 2. Operation Phase
-    User->>Array: push(todo)
-    activate Array
-    Note over Array: Update internal array
-    Array->>Signal: set({ type: 'push', item: todo })
-    activate Signal
-    Note over Signal: Notify watchers
-    Signal->>Subscription: Schedule execution
-    deactivate Signal
-    Array->>Array: Notify whole array watchers
-    Array->>Subscription: Schedule execution
-    deactivate Array
-    
-    activate Subscription
-    Note over Subscription: Re-execute function
-    Subscription->>Signal: get(t)
-    Signal-->>Subscription: { type: 'push', item: todo }
-    Subscription->>Subscription: Handle new todo
-    Note over Subscription: Update UI
-    deactivate Subscription
-```
-
-## Best Practices
-
-### Handle All Action Types
-
-```typescript
-subscribe(
-  (t) => $items.$lastAction.get(t),
-  (action) => {
-    if (!action) return
-    
-    switch (action.type) {
-      case 'push':
-        // Handle push
-        break
-      case 'pop':
-        // Handle pop
-        break
-      case 'splice':
-        // Handle splice
-        break
-      case 'update':
-        // Handle update
-        break
-      case 'clear':
-        // Handle clear
-        break
-      case 'unshift':
-        // Handle unshift
-        break
-      case 'shift':
-        // Handle shift
-        break
-      case 'set':
-        // Handle set (replace entire array)
-        break
-    }
-  }
-)
-```
-
-### Dispose Items Properly
-
-```typescript
-// When removing disposable items
-subscribe(
-  (t) => $resources.$lastAction.get(t),
-  (action) => {
-    if (action && action.type === 'splice') {
-      // Dispose removed items 
-    }
-  }
-)
-```
-
-## Common Pitfalls
-
-### Using Wrong Tracking
-
-**Problem**: Tracking the entire array when you only need specific operations.
-
-```typescript
-// ❌ Tracks entire array when you only need additions
-$items.subscribe((items) => {
-  const lastItem = items[items.length - 1]
-  animateNewItem(lastItem) // Runs on ALL changes
-})
-```
-
-**Solution**: Track only what you need:
-
-```typescript
-// ✅ Track only pushes
-subscribe(
-  (t) => $items.$lastAction.get(t),
-  (action) => {
-    if (action && action.type === 'push') {
-      animateNewItem(action.item)
-    }
-  }
-)
-```
-
-### Mutating Retrieved Arrays
-
-**Problem**: Mutating the array directly instead of using reactive methods.
-
-```typescript
-// ❌ Mutating the array
-const items = $items.pick()
-items.push(newItem) // Doesn't update reactive array!
-```
-
-**Solution**: Use reactive methods:
-
-```typescript
-// ✅ Use reactive methods
-$items.push(newItem)
-```