@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/guide/primitives/effects.md

@@ -1,372 +0,0 @@
-# Side Effects & Subscribe
-
-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.
-
-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
-- **Returns FlowEffect**: Disposable handle to stop the subscription
-
-## When to Use Subscribe
-
-Use subscribe when you need to:
-
-- ✅ Perform side effects (DOM updates, API calls, localStorage)
-- ✅ React to changes in reactive values
-- ✅ Coordinate with external systems
-- ✅ Log or debug reactive changes
-
-Don't use subscribe when:
-
-- ❌ Computing derived values (use derivations instead)
-- ❌ You only need to run code once (use regular functions)
-
-## Creating Side Effects
-
-There are two ways to create side effects, depending on your needs:
-
-### Single Primitive - `.subscribe()`
-
-When reacting to a single primitive, use the `.subscribe()` method:
-
-```typescript
-import { state } from '@ersbeth/picoflow'
-
-const $count = state(0)
-
-// Subscribe directly to the primitive
-const effect = $count.subscribe((value) => {
-  console.log('Count is:', value)
-})
-
-// Later: dispose the effect
-effect.dispose()
-```
-
-### Multiple Primitives - `subscribe()`
-
-When combining multiple primitives, use the global `subscribe()` function:
-
-```typescript
-import { state, subscribe } from '@ersbeth/picoflow'
-
-const $firstName = state('Alice')
-const $lastName = state('Smith')
-
-// 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:
-
-```typescript
-const $showDetails = state(false)
-const $details = state({ info: 'secret' })
-
-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 subscription
-$details.set({ info: 'new secret' }) // Subscription doesn't run
-
-// But once $showDetails is true...
-$showDetails.set(true) // Subscription runs and now tracks $details
-$details.set({ info: 'updated' }) // Now this triggers the subscription!
-```
-
-### Dispose
-
-Subscriptions run indefinitely unless disposed. Always clean them up when no longer needed:
-
-```typescript
-const $count = state(0)
-
-// Create subscription
-const effect = $count.subscribe((value) => {
-  console.log(value)
-})
-
-// Later... stop the subscription
-effect.dispose()
-
-// After disposal, the subscription won't run anymore
-$count.set(10) // No console log
-```
-
-**Always dispose subscriptions when:**
-- Component unmounts (in UI frameworks)
-- Feature is disabled
-- User navigates away
-- App shuts down
-
-**Memory leak example:**
-
-```typescript
-// ❌ Memory leak
-function createUserPanel(userId: number) {
-  const $user = state(getUserData(userId))
-  
-  $user.subscribe((user) => {
-    updateUI(user)
-  })
-  // Subscription never disposed! ⚠️
-}
-
-// Called 100 times = 100 subscriptions still running!
-
-// ✅ Proper cleanup
-function createUserPanel(userId: number) {
-  const $user = state(getUserData(userId))
-  
-  const effect = $user.subscribe((user) => {
-    updateUI(user)
-  })
-  
-  return {
-    dispose: () => {
-      effect.dispose()
-      $user.dispose()
-    }
-  }
-}
-```
-
-## Lifecycle
-
-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 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 Subscription
-    
-    Note over User,Subscription: 1. Creation Phase
-    User->>Subscription: "Create $count.subscribe(...)"
-    activate Subscription
-    Note over Subscription: Execute immediately
-    
-    Subscription->>$count: Read value
-    activate $count
-    Note over $count: Register Subscription as dependent
-    $count-->>Subscription: 0
-    deactivate $count
-    
-    Note over Subscription: "console.log(\"Count: 0\")"
-    Note over Subscription: Track: depends on $count
-    deactivate Subscription
-    
-    Note over User,Subscription: 2. Change Phase
-    User->>$count: set(5)
-    activate $count
-    Note over $count: Value changed: 0 → 5
-    
-    $count->>Subscription: Notify & schedule
-    deactivate $count
-    
-    activate Subscription
-    Note over Subscription: Clear old dependencies<br/>Execute callback
-    
-    Subscription->>$count: Read value
-    activate $count
-    Note over $count: Register Subscription as dependent
-    $count-->>Subscription: 5
-    deactivate $count
-    
-    Note over Subscription: "console.log(\"Count: 5\")"
-    Note over Subscription: Track: depends on $count
-    deactivate Subscription
-    
-    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 Subscription: (Does not run - disposed)
-```
-
-### Key Lifecycle Points
-
-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:
-- **Subscriptions establish dependencies on first run** (no waiting)
-- **Changes trigger re-execution immediately** (synchronous)
-- **Dynamic dependencies adapt automatically** (conditional tracking)
-
-## Best Practices
-
-### Keep Subscriptions Focused
-
-Each subscription should do one thing:
-
-```typescript
-// ❌ Doing too much
-$count.subscribe((value) => {
-  updateDOM(value)
-  saveToStorage(value)
-  sendAnalytics(value)
-  updateTitle(value)
-})
-
-// ✅ Separate concerns
-$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 subscriptions.
-
-### Avoid Creating Subscriptions Inside Subscriptions
-
-```typescript
-// ❌ Bad - creates new subscriptions on every run
-$count.subscribe((count) => {
-  $other.subscribe((other) => {
-    console.log('Nested:', count, other) // Memory leak!
-  })
-})
-
-// ✅ 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
-
-Use the `onError` callback or wrap risky operations in try-catch:
-
-```typescript
-// ✅ 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) {
-    console.error('Failed to update DOM:', error)
-  }
-})
-```
-
-### Be Careful with Infinite Loops
-
-Don't update dependencies inside the same subscription:
-
-```typescript
-const $count = state(0)
-
-// ❌ Infinite loop!
-$count.subscribe((count) => {
-  $count.set(count + 1) // Triggers itself!
-})
-
-// ✅ Use a different state
-$count.subscribe((count) => {
-  $doubled.set(count * 2) // Updates different state
-})
-```
-
-### Use Signals for Event-Only Tracking
-
-When you don't need a value, just an event:
-
-```typescript
-const $refresh = signal()
-
-$refresh.subscribe(() => {
-  fetchData()
-})
-
-// Trigger refresh
-$refresh.trigger()
-```
-
-## Common Pitfalls
-
-### Not Disposing Subscriptions
-
-**Problem**: Subscriptions continue running even when no longer needed.
-
-```typescript
-// ❌ Memory leak in component lifecycle
-function MyComponent() {
-  $data.subscribe((data) => {
-    updateView(data)
-  })
-  // Never disposed!
-}
-
-// Each component creation adds another subscription that never stops
-```
-
-**Solution**: Always dispose subscriptions when done:
-
-```typescript
-// ✅ Proper cleanup
-function MyComponent() {
-  const effect = $data.subscribe((data) => {
-    updateView(data)
-  })
-  
-  return {
-    cleanup: () => effect.dispose()
-  }
-}
-```

package/docs/guide/primitives/map.md

@@ -1,265 +0,0 @@
-# Maps
-
-PicoFlow provides reactive maps with **fine-grained tracking**. Instead of reacting to the entire map changing, you can react to specific operations like adding, updating, or deleting individual entries.
-
-## When to Use Maps
-
-Use maps when you need to:
-
-- ✅ Track large collections with fine-grained updates
-- ✅ React to specific operations (additions, updates, deletions) separately
-- ✅ Optimize performance by avoiding full map re-processing
-
-Don't use maps when:
-
-- ❌ You don't need fine-grained tracking (use `state` with a Record/Map)
-- ❌ You need array-like operations (use `array` instead)
-
-## Creating Maps
-
-Creating a reactive map is straightforward:
-
-```typescript
-import { map } from '@ersbeth/picoflow'
-
-// Create with initial values (key is user id, value is User object)
-const $usersByID = map<string, User>({
-  aliceID: { name: 'Alice', email: 'alice@example.com', role: 'admin' },
-  bobID:   { name: 'Bob', email: 'bob@example.com', role: 'user' }
-})
-
-// Create empty
-const $cache = map<string, Data>()
-```
-
-The initial values (if provided) are converted to a native JavaScript `Map`.
-
-## Using Maps
-
-Maps provide multiple ways to track changes and perform operations.
-
-### Map Operations
-
-Maps provide three main operations: `add()`, `update()`, and `delete()`.
-
-```typescript
-const $cache = map<string, Data>()
-
-// Add a new key-value pair
-$cache.add('user:1', userData)
-
-// Update an existing key-value pair
-$cache.update('user:1', updatedUserData)
-
-// Delete a key-value pair
-$cache.delete('user:1')
-
-// Read (reactive)
-$cache.subscribe((data) => {
-  // Track entire map - returns Map<string, Data>
-  const hasUser = data.has('user:1')
-  if (hasUser) {
-    const user = data.get('user:1')
-    // Use the user data
-  }
-})
-
-// Read (non-reactive)
-const snapshot = $cache.pick() // Returns Map<string, Data>
-const user = snapshot.get('user:1')
-```
-
-**Important**: 
-- `add(key, value)` throws an error if the key already exists
-- `update(key, value)` throws an error if the key doesn't exist
-- `delete(key)` throws an error if the key doesn't exist
-
-
-### Whole Map Tracking
-
-Track when the entire map changes (any operation):
-
-```typescript
-const $items = map<string, number>()
-
-// Initialize with values
-$items.add('a', 1)
-$items.add('b', 2)
-
-$items.subscribe((items) => {
-  console.log('Map size:', items.size)
-})
-
-$items.add('c', 3)    // Logs: "Map size: 3"
-$items.delete('a')    // Logs: "Map size: 2"
-```
-
-Use `.get(t)` when you need the entire map's current state. It returns a native `Map<K, V>`.
-
-### Fine-Grained Tracking
-
-Track specific operations with `$lastAction`:
-
-```typescript
-const $items = map<string, number>()
-
-$items.$lastAction.subscribe((action) => {
-  if (!action) return
-  
-  switch (action.type) {
-    case 'add':
-      console.log(`Added ${action.key} = ${action.addedValue}`)
-      break
-    case 'update':
-      console.log(`Updated ${action.key}: ${action.clearedValue} → ${action.setValue}`)
-      break
-    case 'delete':
-      console.log(`Deleted ${action.key}, was: ${action.removedValue}`)
-      break
-    case 'clear':
-      console.log(`Cleared ${action.clearedMap.size} entries`)
-      break
-    case 'set':
-      console.log(`Set to ${action.setMap.size} entries`)
-      break
-  }
-})
-
-$items.add('a', 1)      // Logs: "Added a = 1"
-$items.add('b', 2)      // Logs: "Added b = 2"
-$items.update('a', 10)  // Logs: "Updated a: 1 → 10"
-$items.delete('a')      // Logs: "Deleted a, was: 10"
-$items.clear()          // Logs: "Cleared 1 entries"
-```
-
-## Lifecycle
-
-When you create a subscription that tracks a map:
-
-1. **Registration**: The map registers the subscription as a watcher
-2. **Operation**: When you call `add()`, `update()`, `delete()`, `set()`, or `clear()`, the map 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 Map as $users (Map)
-    participant Signal as $lastAction
-    participant Subscription
-    
-    Note over User,Subscription: 1. Setup Phase
-    User->>Subscription: Create subscription
-    activate Subscription
-    Subscription->>Map: get(t)
-    Note over Map: 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->>Map: add('user1', userData)
-    activate Map
-    Note over Map: Update internal Map
-    Map->>Signal: "set({ type: 'add', key, addedValue })"
-    activate Signal
-    Note over Signal: Notify watchers
-    Signal->>Subscription: Schedule execution
-    deactivate Signal
-    Map->>Map: Notify whole map watchers
-    Map->>Subscription: Schedule execution
-    deactivate Map
-    
-    activate Subscription
-    Note over Subscription: Re-execute function
-    Subscription->>Signal: get(t)
-    Signal-->>Subscription: "{ type: 'add', key: 'user1', addedValue: userData }"
-    Subscription->>Subscription: Handle new user
-    Note over Subscription: Update UI
-    deactivate Subscription
-```
-
-## Common Pitfalls
-
-### Using Wrong Tracking
-
-**Problem**: Tracking the entire map when you only need specific operations.
-
-```typescript
-// ❌ Tracks entire map when you only need additions
-$items.subscribe((items) => {
-  const keys = Array.from(items.keys())
-  const lastKey = keys[keys.length - 1]
-  animateNewItem(lastKey) // Runs on ALL changes
-})
-```
-
-**Solution**: Track only what you need:
-
-```typescript
-// ✅ Track only additions
-$items.$lastAction.subscribe((action) => {
-  if (action && action.type === 'add') {
-    animateNewItem(action.key)
-  }
-})
-```
-
-### Confusing Add and Update
-
-**Problem**: Using `add()` when the key might already exist, or `update()` when it might not.
-
-```typescript
-// ❌ Will throw if key exists
-function setUser(id: number, user: User) {
-  $users.add(id, user) // Error if user already exists!
-}
-
-// ❌ Will throw if key doesn't exist
-function changeUser(id: number, user: User) {
-  $users.update(id, user) // Error if user doesn't exist!
-}
-```
-
-**Solution**: Check first or handle errors:
-
-```typescript
-// ✅ Check before operation
-function setUser(id: number, user: User) {
-  const users = $users.pick()
-  if (users.has(id)) {
-    $users.update(id, user)
-  } else {
-    $users.add(id, user)
-  }
-}
-```
-
-### Mutating Retrieved Maps
-
-**Problem**: Mutating the map directly instead of using reactive methods.
-
-```typescript
-// ❌ Mutating the map directly
-const items = $items.pick()
-items.set('newKey', newValue) // Doesn't trigger reactivity!
-
-// ❌ Mutating the map directly
-const items = $items.get(t)
-items.set('newKey', newValue) // Changes internal state but doesn't notify properly!
-```
-
-**Solution**: Use reactive methods:
-
-```typescript
-// ✅ Use reactive methods
-const hasItem = $items.pick().has('newKey');
-if (hasItem) {
-  $items.update('newKey', newValue)
-} else {
-  $items.add('newKey', newValue)
-}
-```