@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/guide/primitives/array.md

@@ -2,15 +2,6 @@
 
 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
 
@@ -18,16 +9,12 @@ 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
 
@@ -52,7 +39,7 @@ 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()`.
+Arrays provide several operations: `set()`, `update()`, `push()`, `pop()`, `unshift()`, `shift()`, `splice()`, and `clear()`.
 
 ```typescript
 const $list = array<number>([])
@@ -61,7 +48,7 @@ const $list = array<number>([])
 $list.set([1, 2, 3])
 
 // Replace item at index
-$list.setItem(0, 10)
+$list.update(0, 10)
 
 // Add to end
 $list.push(4)
@@ -82,9 +69,9 @@ $list.splice(1, 1, 99) // Remove 1 item at index 1, add 99
 $list.clear()
 
 // Read (reactive)
-effect((t) => {
-  const items = $list.get(t)
+$list.subscribe((items) => {
   // Track entire array
+  console.log(items)
 })
 
 // Read (non-reactive)
@@ -92,21 +79,18 @@ const snapshot = $list.pick()
 ```
 
 **Important**: 
-- `setItem(index, item)` throws an error if the index is out of bounds
+- `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 with `.get(t)`
+### Whole Array Tracking
 
 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
+$items.subscribe((items) => {
   console.log('Array changed:', items)
 })
 
@@ -117,33 +101,34 @@ $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
+### Fine-Grained Tracking
 
 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.$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"
@@ -151,190 +136,121 @@ $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:
+When you create a subscription that tracks an array:
 
-1. **Registration**: The array registers the effect as a watcher
+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 effects are scheduled to run
-5. **Re-execution**: Each watching effect re-executes its function
+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 Effect
+    participant Subscription
     
-    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,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,Effect: 2. Operation Phase
+    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->>Effect: Schedule execution
+    Signal->>Subscription: Schedule execution
     deactivate Signal
     Array->>Array: Notify whole array watchers
-    Array->>Effect: Schedule execution
+    Array->>Subscription: 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
+    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
 
-### 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!
+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
-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
+subscribe(
+  (t) => $resources.$lastAction.get(t),
+  (action) => {
+    if (action && action.type === 'splice') {
+      // Dispose removed items 
+    }
   }
-})
+)
 ```
 
-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
+$items.subscribe((items) => {
   const lastItem = items[items.length - 1]
-  animateNewItem(lastItem)
+  animateNewItem(lastItem) // Runs on ALL changes
 })
 ```
 
@@ -342,12 +258,14 @@ effect((t) => {
 
 ```typescript
 // ✅ Track only pushes
-effect((t) => {
-  const action = $items.$lastAction.get(t)
-  if (action && action.type === 'push') {
-    animateNewItem(action.item)
+subscribe(
+  (t) => $items.$lastAction.get(t),
+  (action) => {
+    if (action && action.type === 'push') {
+      animateNewItem(action.item)
+    }
   }
-})
+)
 ```
 
 ### Mutating Retrieved Arrays
@@ -365,36 +283,4 @@ items.push(newItem) // Doesn't update reactive array!
 ```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
-  }
-})
-```
+```