@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/guide/primitives/signal.md

@@ -0,0 +1,259 @@
+# Signals
+
+A **signal** is a reactive primitive that represents an event or notification. Unlike state or derivations, signals don't hold values - they simply notify watchers that something has happened.
+
+Imagine a refresh button on a web page. When clicked, it doesn't need to pass data - it just needs to tell the system "hey, refresh now!" That's exactly what signals do.
+
+### Key Characteristics
+
+- **No value**: Signals don't store or return data
+- **Pure notification**: They exist solely to trigger reactions
+- **Lightweight**: Perfect for events that don't need to carry information
+- **Explicit tracking**: Use `.watch(t)` to track them in effects
+
+## When to Use Signals
+
+Use signals when you need to:
+
+- ✅ Trigger manual refreshes or updates
+- ✅ Coordinate actions between independent parts of your app
+- ✅ Signal that an event has occurred without sending data
+- ✅ Create synchronization points in reactive flows
+
+Don't use signals when:
+
+- ❌ You need to pass data (use state instead)
+- ❌ You're tracking continuous streams of events (use streams instead)
+- ❌ The value itself matters (use state or derivation)
+
+## Creating Signals
+
+Creating a signal is straightforward:
+
+```typescript
+import { signal } from '@ersbeth/picoflow'
+
+const $refreshTrigger = signal()
+const $saveComplete = signal()
+const $userLoggedOut = signal()
+```
+
+Signals don't take any parameters since they don't hold values.
+
+## Using Signals
+
+Signals have three main operations: watching, triggering, and disposing.
+
+### Watching Signals with `.watch(t)`
+
+Inside an effect or derivation, use `.watch(t)` to track a signal:
+
+```typescript
+import { signal, effect } from '@ersbeth/picoflow'
+
+const $refresh = signal()
+
+effect((t) => {
+  $refresh.watch(t)
+  console.log('Refresh triggered!')
+})
+
+$refresh.trigger() // Logs: "Refresh triggered!"
+$refresh.trigger() // Logs: "Refresh triggered!" again
+```
+
+Every time the signal is triggered, the effect re-executes.
+
+### Triggering Signals with `.trigger()`
+
+Call `.trigger()` to notify all watchers:
+
+```typescript
+const $notification = signal()
+
+// Setup an effect that watches the signal
+effect((t) => {
+  $notification.watch(t)
+  showNotification('New activity!')
+})
+
+// Trigger from anywhere
+function onNewMessage() {
+  $notification.trigger()
+}
+
+function onNewLike() {
+  $notification.trigger()
+}
+```
+
+### Disposing Signals with `.dispose()`
+
+Signals can be disposed to free resources and prevent memory leaks:
+
+```typescript
+const $mySignal = signal()
+
+// Use the signal
+effect((t) => {
+  $mySignal.watch(t)
+  console.log('Signal triggered!')
+})
+
+// Later, clean up
+$mySignal.dispose()
+
+// Subsequent operations will throw
+$mySignal.trigger() // Error: Primitive is disposed
+```
+
+## Lifecyle
+
+When you create an effect that watches a signal:
+
+1. **Registration**: The signal registers the effect as a watcher
+2. **Waiting**: The signal waits for `.trigger()` to be called
+3. **Notification**: When triggered, all watching effects are scheduled to run
+4. **Re-execution**: Each watching effect re-executes its function
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Signal as $refresh (Signal)
+    participant Effect
+    
+    Note over User,Effect: 1. Setup Phase
+    User->>Effect: Create effect
+    activate Effect
+    Effect->>Signal: watch(t)
+    Note over Signal: Register Effect as watcher
+    Signal-->>Effect: Registered
+    Effect->>Effect: Execute function
+    Note over Effect: Log: "Ready to refresh"
+    deactivate Effect
+    
+    Note over User,Effect: 2. Trigger Phase
+    User->>Signal: trigger()
+    activate Signal
+    Note over Signal: Notify all watchers
+    Signal->>Effect: Schedule execution
+    deactivate Signal
+    
+    activate Effect
+    Note over Effect: Re-execute function
+    Effect->>Effect: Perform refresh
+    Note over Effect: Log: "Refreshing..."
+    deactivate Effect
+```
+
+## Best Practices
+
+### Name Signals Clearly
+
+Use names that describe the event, not the action:
+
+```typescript
+// ✅ Good - describes the event
+const $refreshRequested = signal()
+const $saveComplete = signal()
+const $validationFailed = signal()
+
+// ❌ Bad - describes the handler
+const $doRefresh = signal()
+const $handleSave = signal()
+```
+
+## Common Pitfalls
+
+### Using Signals When State Would Be Better
+
+**Problem**: Using a signal when you actually need to track a value.
+
+```typescript
+// ❌ Bad - should use state
+const $userUpdated = signal()
+let currentUser: User | null = null
+
+effect((t) => {
+  $userUpdated.watch(t)
+  if (currentUser) {
+    renderUser(currentUser)
+  }
+})
+
+function setUser(user: User) {
+  currentUser = user
+  $userUpdated.trigger()
+}
+```
+
+**Solution**: Use state to hold the value:
+
+```typescript
+// ✅ Good - state holds the value
+const $currentUser = state<User | null>(null)
+
+effect((t) => {
+  const user = $currentUser.get(t)
+  if (user) {
+    renderUser(user)
+  }
+})
+
+function setUser(user: User) {
+  $currentUser.set(user)
+}
+```
+
+### Forgetting to Watch the Signal
+
+**Problem**: Calling `.trigger()` without any watchers.
+
+```typescript
+// ❌ Bad - nothing watches the signal
+const $refresh = signal()
+
+effect((t) => {
+  // Forgot to watch!
+  performRefresh()
+})
+
+$refresh.trigger() // Effect won't run
+```
+
+**Solution**: Make sure to call `.watch(t)`:
+
+```typescript
+// ✅ Good - explicitly watch the signal
+const $refresh = signal()
+
+effect((t) => {
+  $refresh.watch(t) // Now it will react!
+  performRefresh()
+})
+
+$refresh.trigger() // Effect runs
+```
+
+### Over-Triggering
+
+**Problem**: Triggering a signal in a loop or too frequently.
+
+```typescript
+// ❌ Bad - triggers in a loop
+for (let i = 0; i < 100; i++) {
+  processItem(i)
+  $itemProcessed.trigger() // 100 triggers!
+}
+```
+
+**Solution**: Trigger once after the batch:
+
+```typescript
+// ✅ Good - single trigger after batch
+for (let i = 0; i < 100; i++) {
+  processItem(i)
+}
+$batchProcessed.trigger() // 1 trigger
+```
+

package/docs/guide/primitives/state.md

@@ -0,0 +1,368 @@
+# State
+
+**State** is a reactive primitive that holds a mutable value. When you update the state, all effects and derivations watching it automatically re-execute.
+
+Imagine a thermometer in your home. The temperature is state - it changes throughout the day, and your heating system watches it to decide when to turn on or off. That's exactly what state does in PicoFlow.
+
+### Key Characteristics
+
+- **Mutable**: Can be updated with `.set()`
+- **Reactive**: Automatically notifies watchers on changes
+- **Equality checking**: Only notifies if the new value differs from the current value
+- **Type-safe**: TypeScript ensures updates match the initial type
+
+## When to Use State
+
+Use state when you need to:
+
+- ✅ Track values that change over time
+- ✅ Respond to user input or interactions
+- ✅ Store data fetched from APIs
+- ✅ Manage application state (UI state, form data, etc.)
+
+Don't use state when:
+
+- ❌ The value never changes (use constants instead)
+- ❌ The value is derived from other reactive values (use derivations instead)
+- ❌ You're tracking events without data (use signals instead)
+
+## Creating State
+
+Creating state is straightforward:
+
+```typescript
+import { state } from '@ersbeth/picoflow'
+
+const $count = state(0)
+const $name = state('Alice')
+const $user = state({ id: 1, name: 'Bob', age: 25 })
+const $items = state<string[]>([])
+```
+
+The value you pass becomes the initial value. It can be any type: numbers, strings, objects, arrays, etc.
+
+## Using State
+
+State provides methods for reading, updating, and disposing.
+
+### Reading with `.get(t)`
+
+Inside an effect or derivation, use `.get(t)` to read the value and create a dependency:
+
+```typescript
+import { state, effect } from '@ersbeth/picoflow'
+
+const $count = state(0)
+
+effect((t) => {
+  const value = $count.get(t) // Read and track
+  console.log('Count is:', value)
+})
+
+$count.set(1) // Console logs: "Count is: 1"
+$count.set(2) // Console logs: "Count is: 2"
+```
+
+### Reading with `.pick()`
+
+Use `.pick()` when you want the current value without creating a dependency:
+
+```typescript
+const $count = state(0)
+
+// Read without tracking (e.g., outside an effect)
+const currentValue = $count.pick()
+console.log(currentValue) // 0
+
+// Or inside an effect, when you don't want to track changes
+const $trigger = signal()
+effect((t) => {
+  $trigger.watch(t)           // Only track trigger
+  const snapshot = $count.pick() // Don't track count
+  console.log(snapshot)
+})
+```
+
+### Updating with `.set(value)`
+
+Pass the new value directly to `.set()`:
+
+```typescript
+const $count = state(0)
+
+$count.set(5)   // Set to 5
+$count.set(10)  // Set to 10
+```
+
+### Updating with `.set(updater)`
+
+Pass a function that receives the current value and returns the new value:
+
+```typescript
+const $count = state(0)
+
+$count.set(n => n + 1)  // Increment by 1
+$count.set(n => n * 2)  // Double the value
+$count.set(n => Math.max(0, n - 1)) // Decrement, min 0
+```
+
+**When to use updater functions:**
+- When the new value depends on the current value
+- To guarantee you're working with the latest value
+- For atomic updates (important in concurrent scenarios)
+
+### Disposing with `.dispose()`
+
+State can be disposed to free resources and prevent memory leaks:
+
+```typescript
+const $count = state(0)
+
+// Use the state
+effect((t) => {
+  console.log($count.get(t))
+})
+
+// Later, clean up
+$count.dispose()
+
+// Subsequent operations will throw
+$count.set(5) // Error: Primitive is disposed
+```
+
+## Lifecycle
+
+When you update state, a specific flow occurs to ensure efficiency and consistency.
+
+### Update Flow
+
+Here's what happens when you call `.set()`:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $count as $count (State)
+    participant $double as $double (Derivation)
+    participant Effect
+    
+    User->>$count: set(n => n + 1)
+    activate $count
+    Note over $count: Get current: 0<br/>Compute new: 0 + 1 = 1
+    Note over $count: Check: 1 !== 0 ✓
+    Note over $count: Update: 0 → 1
+    
+    $count->>$double: Notify (mark dirty)
+    activate $double
+    Note over $double: Mark as dirty<br/>NO recompute yet
+    deactivate $double
+    
+    $count->>Effect: Schedule execution
+    deactivate $count
+    
+    activate Effect
+    Note over Effect: Execute function
+    
+    Effect->>$count: get(t)
+    activate $count
+    $count-->>Effect: 1
+    deactivate $count
+    
+    Effect->>$double: get(t)
+    activate $double
+    Note over $double: Dirty? YES<br/>Recompute now
+    
+    $double->>$count: get(t)
+    activate $count
+    $count-->>$double: 1
+    deactivate $count
+    
+    Note over $double: Compute: 1 * 2 = 2
+    $double-->>Effect: 2
+    deactivate $double
+    
+    Note over Effect: Log: "Count: 1, Double: 2"
+    deactivate Effect
+```
+
+**How it works:**
+
+1. **Compute new value**: If updater function, call it with current value
+2. **Equality check**: Compare new value with current using `===`
+3. **Early return**: If equal, skip notification entirely
+4. **Update value**: Store the new value
+5. **Notify dependents**: 
+   - Derivations are marked dirty (not recomputed yet)
+   - Effects are scheduled for execution
+6. **Pull-based recompute**: When effects run and read derivations, they recompute
+
+### Equality Check Example
+
+State only notifies when the value actually changes:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $count as $count (State)
+    participant Effect
+    
+    Note over User,Effect: Initial state: $count = 5
+    
+    User->>$count: set(5)
+    activate $count
+    Note over $count: Check: 5 === 5?<br/>YES - no change
+    Note over $count: Skip notification
+    deactivate $count
+    Note over Effect: Effect does NOT run
+    
+    User->>$count: set(10)
+    activate $count
+    Note over $count: Check: 10 === 5?<br/>NO - value changed
+    Note over $count: Update: 5 → 10
+    $count->>Effect: Notify & schedule
+    deactivate $count
+    
+    activate Effect
+    Note over Effect: Effect runs
+    deactivate Effect
+```
+
+## Best Practices
+
+### Use Updater Functions for Computed Updates
+
+Always use updater functions when the new value depends on the current value:
+
+```typescript
+// ❌ Bad - race condition risk
+const current = $count.pick()
+$count.set(current + 1)
+
+// ✅ Good - atomic update
+$count.set(n => n + 1)
+```
+
+### Immutable Updates for Objects
+
+Create new objects instead of mutating:
+
+```typescript
+// ❌ Bad - mutation
+$user.set(user => {
+  user.name = 'Bob' // Mutates the object!
+  return user
+})
+
+// ✅ Good - immutable
+$user.set(user => ({
+  ...user,
+  name: 'Bob'
+}))
+```
+
+### Granular State Over Large Objects
+
+Prefer multiple small state values when fields update independently:
+
+```typescript
+// ❌ Less efficient - entire object tracked
+const $form = state({
+  email: '',
+  password: '',
+  confirmPassword: ''
+})
+
+// ✅ More efficient - independent tracking
+const form = {
+  $email: state(''),
+  $password = state(''),
+  $confirmPassword = state(''),
+}
+```
+
+### Name State Clearly
+
+Use the `$` prefix for all reactive values:
+
+```typescript
+// ✅ Good - clear reactive naming
+const $count = state(0)
+const $user = state({...})
+const $isLoading = state(false)
+
+// ❌ Less clear
+const count = state(0)
+const user = state({...})
+```
+
+## Common Pitfalls
+
+### Using `.pick()` in Effects
+
+**Problem**: Using `.pick()` inside effects prevents reactivity.
+
+```typescript
+// ❌ Wrong - will never update
+effect((t) => {
+  const count = $count.pick() // No dependency created!
+  console.log(count) // Only logs once
+})
+```
+
+**Solution**: Use `.get(t)` to create dependencies:
+
+```typescript
+// ✅ Correct - creates dependency
+effect((t) => {
+  const count = $count.get(t) // Creates dependency
+  console.log(count) // Logs on every change
+})
+```
+
+### Forgetting Updater Functions
+
+**Problem**: Reading and setting separately creates race conditions.
+
+```typescript
+// ❌ Potential race condition
+const current = $count.pick()
+$count.set(current + 1)
+// What if $count changes between pick() and set()?
+```
+
+**Solution**: Use updater functions:
+
+```typescript
+// ✅ Safe - uses latest value atomically
+$count.set(n => n + 1)
+```
+
+### Mutating State Directly
+
+**Problem**: Directly mutating arrays or objects doesn't trigger updates.
+
+```typescript
+const $items = state([1, 2, 3])
+
+// ❌ Wrong - mutates the array
+const items = $items.pick()
+items.push(4) // Doesn't trigger updates!
+
+// ❌ Also wrong - same array reference
+$items.set(items => {
+  items.push(4) // Mutation!
+  return items // Same reference, no notification!
+})
+```
+
+**Solution**: Create new arrays/objects (or use FlowArray/FlowMap):
+
+```typescript
+// ✅ Correct - creates new array
+$items.set(items => [...items, 4])
+
+// ✅ Also correct - for objects
+$user.set(user => ({
+  ...user,
+  age: user.age + 1
+}))
+```