@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/guide/primitives/map.md

@@ -2,32 +2,18 @@
 
 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.
 
-Imagine you have a map of 1000 users. In a naive reactive system, every time you add, remove, or update a single user, the entire map re-renders. **Inefficient!** With PicoFlow's reactive maps, you can track specific operations and only update what changed.
-
-### Key Characteristics
-
-- **Fine-grained reactivity**: Track individual operations (add, update, delete) separately
-- **Multiple tracking levels**: Track the whole map or specific operations
-- **Native Map**: Uses JavaScript's native `Map<K, V>` internally
-- **Operation-specific signals**: `$lastAdded`, `$lastUpdated`, `$lastDeleted` for granular tracking
-- **Disposable**: Can be disposed to clean up resources
-
 ## 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
-- ✅ Manage key-value pairs where individual key operations matter
 - ✅ Optimize performance by avoiding full map re-processing
-- ✅ Animate or handle UI updates for specific changes
 
 Don't use maps when:
 
-- ❌ You have a small, simple object (use `state` instead)
-- ❌ You don't need fine-grained tracking (use `state` with a Record)
+- ❌ You don't need fine-grained tracking (use `state` with a Record/Map)
 - ❌ You need array-like operations (use `array` instead)
-- ❌ The collection is rarely modified (regular state might be simpler)
 
 ## Creating Maps
 
@@ -69,8 +55,7 @@ $cache.update('user:1', updatedUserData)
 $cache.delete('user:1')
 
 // Read (reactive)
-effect((t) => {
-  const data = $cache.get(t)
+$cache.subscribe((data) => {
   // Track entire map - returns Map<string, Data>
   const hasUser = data.has('user:1')
   if (hasUser) {
@@ -90,21 +75,18 @@ const user = snapshot.get('user:1')
 - `delete(key)` throws an error if the key doesn't exist
 
 
-### Whole Map Tracking with `.get(t)`
+### Whole Map Tracking
 
 Track when the entire map changes (any operation):
 
 ```typescript
-import { map, effect } from '@ersbeth/picoflow'
-
 const $items = map<string, number>()
 
 // Initialize with values
 $items.add('a', 1)
 $items.add('b', 2)
 
-effect((t) => {
-  const items = $items.get(t) // Track all changes
+$items.subscribe((items) => {
   console.log('Map size:', items.size)
 })
 
@@ -114,207 +96,104 @@ $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: Track Additions
-
-Track only when items are added:
-
-```typescript
-const $items = map<string, number>()
-
-effect((t) => {
-  const lastAdded = $items.$lastAdded.get(t)
-  if (lastAdded) {
-    console.log(`Added ${lastAdded.key} = ${lastAdded.value}`)
-  }
-})
-
-$items.add('a', 1)  // Logs: "Added a = 1"
-$items.add('b', 2)  // Logs: "Added b = 2"
-$items.update('a', 10)  // No log - not an addition!
-$items.delete('a')    // No log - not an addition!
-```
-
-### Fine-Grained: Track Updates
-
-Track only when existing items are updated:
+### Fine-Grained Tracking
 
-```typescript
-const $items = map<string, number>()
-
-// Add some initial values
-$items.add('a', 1)
-$items.add('b', 2)
-
-effect((t) => {
-  const lastUpdated = $items.$lastUpdated.get(t)
-  if (lastUpdated) {
-    console.log(`Updated ${lastUpdated.key} = ${lastUpdated.value}`)
-  }
-})
-
-$items.update('a', 10)  // Logs: "Updated a = 10"
-$items.add('c', 3)      // No log - not an update!
-$items.delete('a')      // No log - not an update!
-```
-
-### Fine-Grained: Track Deletions
-
-Track only when items are deleted:
+Track specific operations with `$lastAction`:
 
 ```typescript
 const $items = map<string, number>()
 
-// Add some initial values
-$items.add('a', 1)
-$items.add('b', 2)
-$items.add('c', 3)
-
-effect((t) => {
-  const lastDeleted = $items.$lastDeleted.get(t)
-  if (lastDeleted) {
-    console.log(`Deleted key: ${lastDeleted.key}, value was: ${lastDeleted.value}`)
+$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.delete('a')     // Logs: "Deleted key: a, value was: 1"
-$items.add('d', 4)     // No log - not a deletion!
-$items.update('b', 20) // No log - not a deletion!
-$items.delete('b')     // Logs: "Deleted key: b, value was: 20"
+$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 an effect that tracks a map:
+When you create a subscription that tracks a map:
 
-1. **Registration**: The map registers the effect as a watcher
-2. **Operation**: When you call `add()`, `update()`, or `delete()`, the map updates internally
-3. **Signal Update**: The appropriate signal (`$lastAdded`, `$lastUpdated`, or `$lastDeleted`) is updated
-4. **Notification**: All watching effects are scheduled to run
-5. **Re-execution**: Each watching effect re-executes its function
+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 $lastAdded
-    participant Effect
+    participant Signal as $lastAction
+    participant Subscription
     
-    Note over User,Effect: 1. Setup Phase
-    User->>Effect: Create effect
-    activate Effect
-    Effect->>Map: get(t)
-    Note over Map: 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->>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,Effect: 2. Operation Phase
+    Note over User,Subscription: 2. Operation Phase
     User->>Map: add('user1', userData)
     activate Map
     Note over Map: Update internal Map
-    Map->>Signal: set({ key, value })
+    Map->>Signal: "set({ type: 'add', key, addedValue })"
     activate Signal
     Note over Signal: Notify watchers
-    Signal->>Effect: Schedule execution
+    Signal->>Subscription: Schedule execution
     deactivate Signal
     Map->>Map: Notify whole map watchers
-    Map->>Effect: Schedule execution
+    Map->>Subscription: Schedule execution
     deactivate Map
     
-    activate Effect
-    Note over Effect: Re-execute function
-    Effect->>Signal: get(t)
-    Signal-->>Effect: { key: 'user1', value: userData }
-    Effect->>Effect: Handle new user
-    Note over Effect: Update UI
-    deactivate Effect
-```
-
-## Best Practices
-
-### Choose the Right Granularity
-
-```typescript
-// ✅ Use fine-grained for large maps
-const $users = map<number, User>()
-effect((t) => {
-  const lastAdded = $users.$lastAdded.get(t)
-  if (lastAdded) {
-    // Handle specific change
-    renderNewUser(lastAdded.value)
-  }
-})
-
-// ✅ Use coarse-grained for small maps
-const $settings = state({ theme: 'dark', lang: 'en', size: 'large' })
-effect((t) => {
-  const settings = $settings.get(t)
-  // Re-apply all settings (cheap for 3 items)
-  applySettings(settings)
-})
-```
-
-### Combine for Best Results
-
-```typescript
-// Fine-grained for UI updates
-effect((t) => {
-  const lastAdded = $items.$lastAdded.get(t)
-  if (lastAdded) {
-    updateUIIncremental(lastAdded)
-  }
-})
-
-// Coarse-grained for totals
-const $total = derivation((t) => {
-  const items = $items.get(t)
-  let sum = 0
-  for (const value of items.values()) {
-    sum += value.price
-  }
-  return sum
-})
+    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
 
-### Forgetting to Handle Nulls
-
-**Problem**: The operation signals can be `null` initially.
-
-```typescript
-// ❌ Can be null initially
-effect((t) => {
-  const lastAdded = $items.$lastAdded.get(t)
-  console.log(lastAdded.key) // Error if null!
-})
-```
-
-**Solution**: Always check for null:
-
-```typescript
-// ✅ Check for null
-effect((t) => {
-  const lastAdded = $items.$lastAdded.get(t)
-  if (lastAdded) {
-    console.log(lastAdded.key)
-  }
-})
-```
-
 ### Using Wrong Tracking
 
 **Problem**: Tracking the entire map when you only need specific operations.
 
 ```typescript
 // ❌ Tracks entire map when you only need additions
-effect((t) => {
-  const items = $items.get(t) // Runs on ALL changes
+$items.subscribe((items) => {
   const keys = Array.from(items.keys())
   const lastKey = keys[keys.length - 1]
-  animateNewItem(lastKey)
+  animateNewItem(lastKey) // Runs on ALL changes
 })
 ```
 
@@ -322,10 +201,9 @@ effect((t) => {
 
 ```typescript
 // ✅ Track only additions
-effect((t) => {
-  const lastAdded = $items.$lastAdded.get(t)
-  if (lastAdded) {
-    animateNewItem(lastAdded.key)
+$items.$lastAction.subscribe((action) => {
+  if (action && action.type === 'add') {
+    animateNewItem(action.key)
   }
 })
 ```

package/docs/guide/primitives/overview.md

@@ -1,165 +1,82 @@
 # Primitives Overview
 
-PicoFlow provides several reactive primitives, each designed for specific use cases in reactive programming. This guide introduces all the primitives and shows how they work together.
+PicoFlow distinguishes between two main concepts:
+- **Primitives**: Reactive values (state, derivation, signal, collections)
+- **Side Effects**: Created by subscribing to primitives 
 
 ::: tip
 Looking for naming conventions? Check out the **[Conventions](/guide/introduction/conventions)** guide to learn about the `$` prefix.
 :::
 
-## Listing
+## Primitives
 
-PicoFlow provides several reactive primitives for different use cases:
+PicoFlow provides several reactive primitives, each with specific capabilities. Primitive may exist in synchrone and asynchrone flavours.
 
-| Primitive | Purpose | Example |
-|-----------|---------|---------|
-| **Signal** | Event notifications | Manual refresh, synchronization |
-| **State** | Mutable values | Form inputs, toggles, counters |
-| **Constant** | Immutable values | Configuration, initial values |
-| **Derivation** | Computed values | Totals, filtered lists, formatted strings |
-| **Effect** | Side effects | DOM updates, logging, API calls |
-| **Resource** | Async data fetching | API calls, file loading |
-| **Stream** | Event-driven data | WebSockets, timers, DOM events |
-| **Map** | Reactive dictionaries | Key-value stores, caches |
-| **Array** | Reactive lists | Todo lists, dynamic collections |
+| Primitive | Sync | Async | Purpose |
+|-----------|:----:|:-----:|---------|
+| **Signal** | ✓ | - | Event notifications without values |
+| **State** | ✓ | ✓ | Mutable reactive values |
+| **Constant** | ✓ | ✓ | Immutable reactive values |
+| **Derivation** | ✓ | ✓ | Computed values from dependencies |
+| **Writable Derivation** | ✓ | ✓ | Derivations with custom setters |
+| **Array** | ✓ | - | Reactive lists with fine-grained tracking |
+| **Map** | ✓ | - | Reactive dictionaries with fine-grained tracking |
 
-## Details
+## Side Effects
 
-### Signal
+You may subscribe to any primitive to perform side effects on change. When you subscribe, you get a `FlowEffect` that can be disposed.
 
-**Event-like notifications without values** - use when you want to trigger effects without carrying data.
 
-```typescript
-const $refresh = signal()
-$refresh.trigger() // Tell everyone: "Refresh now!"
-```
-
-**Use cases:** Manual refresh triggers, event notifications, synchronization points
-
-### State
-
-**Mutable reactive values** - use for data that changes over time.
-
-```typescript
-const $count = state(0)
-$count.set(1)
-$count.set(n => n + 1) // Updater function
-```
-
-**Use cases:** Form inputs, counters, toggles, user data
-
-### Constant
-
-**Immutable reactive values** - use for values that never change but need to be part of the reactive graph.
-
-```typescript
-const $config = constant({ apiUrl: 'https://api.example.com', timeout: 5000 })
-const $version = constant('1.0.0')
-```
-
-**Use cases:** Configuration values, application constants, initial data
-
-**Key feature:** Unlike regular JavaScript constants, these can be tracked in the reactive graph, making them useful for dependencies that shouldn't change.
-
-### Derivation
-
-**Computed values** - use when you want to calculate something based on other reactive values.
-
-```typescript
-const $double = derivation((t) => $count.get(t) * 2)
-```
-
-**Use cases:** Totals, filtered lists, formatted values, derived UI state
-
-**Key feature:** Lazy evaluation and caching - only recomputes when dependencies change AND when the value is accessed.
-
-### Effect
-
-**Side effects** - use when you want to do something in response to changes (DOM updates, logging, etc.).
+When reacting to a single primitive, use the `.subscribe()` method:
 
 ```typescript
-effect((t) => {
-  console.log('Count is:', $count.get(t))
+const effect = $count.subscribe((value) => {
+  console.log('Count is:', value)
 })
-```
-
-**Use cases:** Logging, DOM manipulation, API calls, persistence
-
-**Key feature:** Eager execution - runs immediately when created and whenever dependencies change.
-
-### Resource
-
-**Async data fetching** - use when you need to load data asynchronously and track its loading state.
-
-```typescript
-const $userId = state(1)
-const $user = resource(
-  (t) => $userId.get(t),
-  (id) => fetchUser(id)
-)
-```
-
-**Use cases:** API calls, file loading, async data fetching
-
-**Key feature:** Provides loading, error, and ready states automatically, with built-in cancellation of stale requests.
-
-### Stream
 
-**Event-driven data** - use when you want to handle continuous streams of events or data.
-
-```typescript
-const $clicks = stream<MouseEvent>((emit) => {
-  document.addEventListener('click', emit)
-  return () => document.removeEventListener('click', emit)
-})
+// Later: dispose the effect
+effect.dispose()
 ```
 
-**Use cases:** WebSocket connections, timers, DOM events, real-time data
 
-**Key feature:** Push-based model for handling continuous event streams with automatic cleanup.
-
-### Map
-
-**Reactive dictionaries** - use when you need fine-grained tracking of key-value pairs.
+When combining multiple primitives, use the `subscribe()` function:
 
 ```typescript
-const $users = map<number, User>({
-  1: { id: 1, name: 'Alice' },
-  2: { id: 2, name: 'Bob' }
-})
-$users.setAt(3, { id: 3, name: 'Charlie' })
+const effect = subscribe(
+  (t) => ({ count: $count.get(t), name: $name.get(t) }),
+  (data) => {
+    console.log('Count:', data.count, 'Name:', data.name)
+  }
+)
 ```
 
-**Use cases:** Caches, entity stores, key-value collections
-
-**Key feature:** Fine-grained reactivity - track additions, deletions, or changes to the entire map separately.
-
-### Array
+### Use cases
 
-**Reactive lists** - use when you need fine-grained tracking of array operations.
-
-```typescript
-const $todos = array<Todo>([
-  { id: 1, text: 'Learn PicoFlow', done: false },
-  { id: 2, text: 'Build app', done: false }
-])
-$todos.push({ id: 3, text: 'Deploy', done: false })
-```
+- Logging and debugging
+- DOM manipulation
+- API calls and data persistence
+- Analytics and tracking
+- Side effects that don't produce values
 
-**Use cases:** Todo lists, dynamic collections, ordered data
+### Key features
 
-**Key feature:** Fine-grained reactivity - track specific operations (push, pop, splice) instead of full array changes.
+- **Eager execution**: Runs immediately when created
+- **Automatic re-execution**: Runs whenever dependencies change
+- **Returns FlowEffect**: Can be disposed to stop the effect
+- **Error handling**: Optional `onError` and `onPending` callbacks
 
-## Derivations vs Effects
+## Derivations vs Side Effects
 
-What's the difference between a derivation and an effect? Both react to changes, but they serve different purposes:
+What's the difference between a derivation and a side effect? Both react to changes, but they serve different purposes:
 
-| Feature | Derivation | Effect |
-|---------|-----------|--------|
+| Feature | Derivation | Side Effect (subscribe) |
+|---------|-----------|---------|
 | Purpose | **Compute a value** | **Perform side effects** |
-| Returns | A value | Nothing (void) |
+| Returns | A reactive value | FlowEffect (disposable) |
 | Should be pure? | ✅ Yes | ❌ No |
 | Side effects allowed? | ❌ No | ✅ Yes |
 | When it runs | Lazily (when accessed) | Immediately and on changes |
+| How to create | `derivation()` | `subscribe()` or `.subscribe()` |
 | Use case | Calculate totals, filter lists | Update DOM, save data, log |
 
 ```mermaid