@ersbeth/picoflow 0.2.4 → 1.0.0

package/docs/guide/primitives/array.md

@@ -0,0 +1,400 @@
+# 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.
+
+Imagine you have a list of 1000 todos. In a naive reactive system, every time you add, remove, or update a single todo, the entire list re-renders. **Inefficient!** With PicoFlow's reactive arrays, you can track specific operations and only update what changed.
+
+### Key Characteristics
+
+- **Fine-grained reactivity**: Track individual operations (push, pop, splice, etc.) separately
+- **Multiple tracking levels**: Track the whole array or specific operations
+- **Native Array**: Uses JavaScript's native `Array<T>` internally
+- **Operation-specific signal**: `$lastAction` for granular tracking of all operations
+- **Disposable**: Can be disposed to clean up resources
+
+## 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
+- ✅ Manage ordered collections where individual item operations matter
+- ✅ Optimize performance by avoiding full array re-processing
+- ✅ Animate or handle UI updates for specific changes
+
+Don't use arrays when:
+
+- ❌ You have a small, simple list (use `state` instead)
+- ❌ You don't need fine-grained tracking (use `state` with an array)
+- ❌ You need key-value operations (use `map` instead)
+- ❌ The collection is rarely modified (regular state might be simpler)
+
+## 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()`, `setItem()`, `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.setItem(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)
+effect((t) => {
+  const items = $list.get(t)
+  // Track entire array
+})
+
+// Read (non-reactive)
+const snapshot = $list.pick()
+```
+
+**Important**: 
+- `setItem(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 with `.get(t)`
+
+Track when the entire array changes (any operation):
+
+```typescript
+import { array, effect } from '@ersbeth/picoflow'
+
+const $items = array([1, 2, 3])
+
+effect((t) => {
+  const items = $items.get(t) // Track all changes
+  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: Track Operations
+
+Track specific operations with `$lastAction`:
+
+```typescript
+const $items = array<number>([])
+
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  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 'setItem':
+      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"
+```
+
+## Array Action Types
+
+The `$lastAction` signal contains information about the last operation:
+
+```typescript
+type FlowArrayAction<T> =
+  | { type: 'set'; items: T[] }
+  | { type: 'setItem'; index: number; item: T }
+  | { type: 'push'; item: T }
+  | { type: 'pop' }
+  | { type: 'shift' }
+  | { type: 'unshift'; item: T }
+  | { type: 'splice'; start: number; deleteCount: number; items: T[] }
+  | { type: 'clear' }
+```
+
+## Lifecycle
+
+When you create an effect that tracks an array:
+
+1. **Registration**: The array registers the effect 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 effects are scheduled to run
+5. **Re-execution**: Each watching effect re-executes its function
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Array as $todos (Array)
+    participant Signal as $lastAction
+    participant Effect
+    
+    Note over User,Effect: 1. Setup Phase
+    User->>Effect: Create effect
+    activate Effect
+    Effect->>Array: get(t)
+    Note over Array: Register Effect as watcher
+    Effect->>Signal: get(t)
+    Note over Signal: Register Effect as watcher
+    Effect->>Effect: Execute function
+    Note over Effect: Initial render
+    deactivate Effect
+    
+    Note over User,Effect: 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->>Effect: Schedule execution
+    deactivate Signal
+    Array->>Array: Notify whole array watchers
+    Array->>Effect: Schedule execution
+    deactivate Array
+    
+    activate Effect
+    Note over Effect: Re-execute function
+    Effect->>Signal: get(t)
+    Signal-->>Effect: { type: 'push', item: todo }
+    Effect->>Effect: Handle new todo
+    Note over Effect: Update UI
+    deactivate Effect
+```
+
+## Best Practices
+
+### Choose the Right Granularity
+
+```typescript
+// ✅ Use fine-grained for large arrays
+const $todos = array<Todo>([...1000 todos...])
+effect((t) => {
+  const action = $todos.$lastAction.get(t)
+  if (action) {
+    // Handle specific change
+  }
+})
+
+// ✅ Use coarse-grained for small arrays
+const $settings = state(['dark', 'en', 'large'])
+effect((t) => {
+  const settings = $settings.get(t)
+  // Re-apply all settings (cheap for 3 items)
+})
+```
+
+### Combine for Best Results
+
+```typescript
+// Fine-grained for UI updates
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action) {
+    updateUIIncremental(action)
+  }
+})
+
+// Coarse-grained for totals
+const $total = derivation((t) => {
+  return $items.get(t).reduce((sum, item) => sum + item.value, 0)
+})
+```
+
+### Handle All Action Types
+
+```typescript
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (!action) return
+  
+  switch (action.type) {
+    case 'push':
+      // Handle push
+      break
+    case 'pop':
+      // Handle pop
+      break
+    case 'splice':
+      // Handle splice
+      break
+    case 'setItem':
+      // Handle setItem
+      break
+    case 'clear':
+      // Handle clear
+      break
+    // Don't forget any cases!
+  }
+})
+```
+
+### Dispose Items Properly
+
+```typescript
+// When removing disposable items
+effect((t) => {
+  const action = $resources.$lastAction.get(t)
+  if (action && action.type === 'splice') {
+    // Dispose removed items (they're already disposed by the array)
+    // But you might want to do additional cleanup
+  }
+})
+```
+
+Arrays automatically dispose disposable items when they are removed, but you can add additional cleanup logic if needed.
+
+## Common Pitfalls
+
+### Forgetting to Handle Nulls
+
+**Problem**: The `$lastAction` signal can be `null` initially or after certain operations.
+
+```typescript
+// ❌ Can be null initially
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  console.log(action.type) // Error if null!
+})
+```
+
+**Solution**: Always check for null:
+
+```typescript
+// ✅ Check for null
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action) {
+    console.log(action.type)
+  }
+})
+```
+
+### Using Wrong Tracking
+
+**Problem**: Tracking the entire array when you only need specific operations.
+
+```typescript
+// ❌ Tracks entire array when you only need additions
+effect((t) => {
+  const items = $items.get(t) // Runs on ALL changes
+  const lastItem = items[items.length - 1]
+  animateNewItem(lastItem)
+})
+```
+
+**Solution**: Track only what you need:
+
+```typescript
+// ✅ Track only pushes
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  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)
+```
+
+### Using Wrong Action Properties
+
+**Problem**: Using incorrect property names from action objects.
+
+```typescript
+// ❌ Wrong property names
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'push') {
+    console.log(action.value) // Error! Should be action.item
+  }
+  if (action && action.type === 'splice') {
+    console.log(action.index) // Error! Should be action.start
+  }
+})
+```
+
+**Solution**: Use correct property names:
+
+```typescript
+// ✅ Correct property names
+effect((t) => {
+  const action = $items.$lastAction.get(t)
+  if (action && action.type === 'push') {
+    console.log(action.item) // Correct
+  }
+  if (action && action.type === 'splice') {
+    console.log(action.start) // Correct
+  }
+})
+```