@ersbeth/picoflow 0.2.4 → 1.0.0

package/docs/guide/primitives/map.md

@@ -0,0 +1,387 @@
+# 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.
+
+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 need array-like operations (use `array` instead)
+- ❌ The collection is rarely modified (regular state might be simpler)
+
+## 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)
+effect((t) => {
+  const data = $cache.get(t)
+  // 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 with `.get(t)`
+
+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
+  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: 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:
+
+```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:
+
+```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.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"
+```
+
+## Lifecycle
+
+When you create an effect 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
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Map as $users (Map)
+    participant Signal as $lastAdded
+    participant Effect
+    
+    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,Effect: 2. Operation Phase
+    User->>Map: add('user1', userData)
+    activate Map
+    Note over Map: Update internal Map
+    Map->>Signal: set({ key, value })
+    activate Signal
+    Note over Signal: Notify watchers
+    Signal->>Effect: Schedule execution
+    deactivate Signal
+    Map->>Map: Notify whole map watchers
+    Map->>Effect: 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
+})
+```
+
+## 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
+  const keys = Array.from(items.keys())
+  const lastKey = keys[keys.length - 1]
+  animateNewItem(lastKey)
+})
+```
+
+**Solution**: Track only what you need:
+
+```typescript
+// ✅ Track only additions
+effect((t) => {
+  const lastAdded = $items.$lastAdded.get(t)
+  if (lastAdded) {
+    animateNewItem(lastAdded.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)
+}
+```

package/docs/guide/primitives/overview.md

@@ -0,0 +1,175 @@
+# 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.
+
+::: tip
+Looking for naming conventions? Check out the **[Conventions](/guide/introduction/conventions)** guide to learn about the `$` prefix.
+:::
+
+## Listing
+
+PicoFlow provides several reactive primitives for different use cases:
+
+| 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 |
+
+## Details
+
+### Signal
+
+**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.).
+
+```typescript
+effect((t) => {
+  console.log('Count is:', $count.get(t))
+})
+```
+
+**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)
+})
+```
+
+**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.
+
+```typescript
+const $users = map<number, User>({
+  1: { id: 1, name: 'Alice' },
+  2: { id: 2, name: 'Bob' }
+})
+$users.setAt(3, { id: 3, name: 'Charlie' })
+```
+
+**Use cases:** Caches, entity stores, key-value collections
+
+**Key feature:** Fine-grained reactivity - track additions, deletions, or changes to the entire map separately.
+
+### Array
+
+**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 })
+```
+
+**Use cases:** Todo lists, dynamic collections, ordered data
+
+**Key feature:** Fine-grained reactivity - track specific operations (push, pop, splice) instead of full array changes.
+
+## Derivations vs Effects
+
+What's the difference between a derivation and an effect? Both react to changes, but they serve different purposes:
+
+| Feature | Derivation | Effect |
+|---------|-----------|--------|
+| Purpose | **Compute a value** | **Perform side effects** |
+| Returns | A value | Nothing (void) |
+| Should be pure? | ✅ Yes | ❌ No |
+| Side effects allowed? | ❌ No | ✅ Yes |
+| When it runs | Lazily (when accessed) | Immediately and on changes |
+| Use case | Calculate totals, filter lists | Update DOM, save data, log |
+
+```mermaid
+flowchart LR
+    A[Reactive Values] --> B[Derivation]
+    A --> C[Effect]
+    B --> D[New Computed Value]
+    C --> E[Side Effects<br/>DOM, API, Storage]
+    D -.-> F[Can be used by<br/>other derivations]
+    D -.-> G[Can be used by<br/>effects]
+```
+
+**Key insight:** Use derivations for **calculations**, use effects for **actions**.