@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/guide/primitives/constant.md

@@ -0,0 +1,380 @@
+# Constants
+
+A **constant** is a reactive primitive that holds an immutable value. Unlike state, constants cannot be updated after initialization - they exist to provide stable, reactive references to values that don't change.
+
+Imagine a configuration file in your application. It's loaded once at startup and never changes, but many parts of your app need to read it. That's what constants do in PicoFlow.
+
+### Key Characteristics
+
+- **Immutable**: No `.set()` method - value never changes
+- **Reactive**: Can be tracked with `.get(t)` just like state
+- **Lazy evaluation**: Optional - compute value on first access
+- **Cached forever**: Once computed, the value is permanently stored
+
+## When to Use Constants
+
+Use constants when you need to:
+
+- ✅ Store configuration values that don't change
+- ✅ Cache expensive computations that only run once
+- ✅ Create reactive feature flags
+- ✅ Provide stable reactive references to initialization values
+
+Don't use constants when:
+
+- ❌ The value needs to change (use state instead)
+- ❌ You need a `.set()` method
+- ❌ The value isn't reactive (use plain `const` instead)
+
+## Creating Constants
+
+Creating a constant is simple:
+
+```typescript
+import { constant } from '@ersbeth/picoflow'
+
+// Direct value - initialized immediately
+const $apiUrl = constant('https://api.example.com')
+const $config = constant({ apiUrl: 'https://api.example.com', timeout: 5000 })
+const $version = constant('1.0.0')
+```
+
+### Lazy Initialization
+
+Pass a function to defer computation until first access:
+
+```typescript
+// Lazy initialization - computed on first access
+const $expensiveValue = constant(() => {
+  console.log('Computing expensive value...')
+  return performExpensiveCalculation()
+})
+
+// Nothing logged yet - function not called
+
+effect((t) => {
+  const value = $expensiveValue.get(t)
+  // NOW it logs: "Computing expensive value..."
+  console.log(value)
+})
+
+// Subsequent accesses return the cached value (no recomputation)
+```
+
+## Using Constants
+
+Constants provide two ways to read values:
+
+### Reading with `.get(t)`
+
+Inside an effect or derivation, use `.get(t)` to read the value and create a dependency:
+
+```typescript
+import { constant, effect } from '@ersbeth/picoflow'
+
+const $config = constant({ apiUrl: 'https://api.example.com' })
+
+effect((t) => {
+  const config = $config.get(t) // Read and track
+  console.log('API URL:', config.apiUrl)
+})
+```
+
+### Reading with `.pick()`
+
+Use `.pick()` when you want the current value without creating a dependency:
+
+```typescript
+const $config = constant({ apiUrl: 'https://api.example.com' })
+
+// Read without tracking (e.g., outside an effect)
+const currentConfig = $config.pick()
+console.log(currentConfig.apiUrl)
+
+// Or inside an effect, when you don't want to track changes
+effect((t) => {
+  $trigger.watch(t)           // Only track trigger
+  const config = $config.pick() // Don't track config
+  console.log(config)
+})
+```
+
+### No `.set()` Method
+
+Constants are immutable - attempting to call `.set()` will result in a TypeScript error:
+
+```typescript
+const $config = constant({ apiUrl: 'https://api.example.com' })
+
+$config.set({ apiUrl: 'new-url' }) // Type error! Constants have no .set() method
+```
+
+### Disposing with `.dispose()`
+
+Constants can be disposed to free resources:
+
+```typescript
+const $config = constant({ apiUrl: 'https://api.example.com' })
+
+// Later, clean up
+$config.dispose()
+
+// Subsequent operations will throw
+$config.get(t) // Error: Primitive is disposed
+```
+
+## Lifecycle
+
+Constants have two initialization patterns depending on whether you pass a value or a function.
+
+### Eager Initialization Flow
+
+When you pass a direct value, it's stored immediately:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $config as $config (Constant)
+    
+    User->>$config: constant({ value: 'data' })
+    activate $config
+    Note over $config: Store value immediately<br/>Mark as initialized
+    deactivate $config
+    
+    User->>$config: get(t)
+    activate $config
+    Note over $config: Already initialized<br/>Return stored value
+    $config-->>User: { value: 'data' }
+    deactivate $config
+```
+
+### Lazy Initialization Flow
+
+When you pass a function, it's executed on first access:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $config as $config (Constant)
+    participant InitFn as Initialization Function
+    
+    Note over User,$config: 1. Creation Phase
+    User->>$config: constant(() => compute())
+    activate $config
+    Note over $config: Store function<br/>NOT called yet<br/>NOT initialized
+    deactivate $config
+    
+    Note over User,InitFn: 2. First Access
+    User->>$config: get(t)
+    activate $config
+    Note over $config: Check: initialized?<br/>NO - call function
+    
+    $config->>InitFn: Execute function
+    activate InitFn
+    Note over InitFn: Perform expensive<br/>calculation
+    InitFn-->>$config: Computed value
+    deactivate InitFn
+    
+    Note over $config: Store value<br/>Mark as initialized
+    $config-->>User: Return value
+    deactivate $config
+    
+    Note over User,$config: 3. Subsequent Access
+    User->>$config: get(t)
+    activate $config
+    Note over $config: Check: initialized?<br/>YES - return cached value
+    $config-->>User: Return cached value
+    deactivate $config
+```
+
+**How it works:**
+
+1. **Creation**: Constructor checks if value is a function
+   - If function: store it, mark as not initialized
+   - If value: store it directly, mark as initialized
+
+2. **First access**: When `.get(t)` or `.pick()` is called
+   - Check if initialized
+   - If not, execute stored function
+   - Cache result and mark as initialized
+
+3. **Subsequent access**: Always return cached value
+
+## Best Practices
+
+### Use Lazy Init for Expensive Computations
+
+Defer expensive work until it's actually needed:
+
+```typescript
+// ✅ Good - lazy evaluation
+const $parsedData = constant(() => {
+  return JSON.parse(largeDataString) // Only runs when accessed
+})
+
+// ❌ Less efficient - eager evaluation
+const $parsedData = constant(JSON.parse(largeDataString)) // Runs immediately
+```
+
+### Use Constants for Configuration
+
+Perfect for application configuration:
+
+```typescript
+const $appConfig = constant({
+  apiUrl: process.env.API_URL || 'https://api.example.com',
+  environment: process.env.NODE_ENV || 'development',
+  features: {
+    darkMode: true,
+    betaFeatures: false
+  }
+})
+
+effect((t) => {
+  const config = $appConfig.get(t)
+  setupApp(config)
+})
+```
+
+### Name Constants Clearly
+
+Use the `$` prefix like other reactive primitives:
+
+```typescript
+// ✅ Good - clear constant names
+const $apiEndpoint = constant('https://api.example.com')
+const $appVersion = constant('1.0.0')
+const $maxRetries = constant(3)
+
+// ❌ Less clear
+const apiEndpoint = constant('https://api.example.com')
+const APP_VERSION = constant('1.0.0')
+```
+
+### Prefer Plain const for Non-Reactive Values
+
+If no effects or derivations will read it, use plain JavaScript:
+
+```typescript
+// ❌ Unnecessary - no reactivity needed
+const $localConfig = constant({ timeout: 5000 })
+function fetch() {
+  const config = $localConfig.pick() // Never tracked
+  return doFetch(config)
+}
+
+// ✅ Better - plain const
+const localConfig = { timeout: 5000 }
+function fetch() {
+  return doFetch(localConfig)
+}
+```
+
+## Common Pitfalls
+
+### Using Constants When State Would Be Better
+
+**Problem**: Using a constant for a value that actually needs to change.
+
+```typescript
+// ❌ Bad - theme should be changeable
+const $theme = constant('light')
+
+// Can't update it later!
+// $theme.set('dark') // Type error!
+```
+
+**Solution**: Use state for mutable values:
+
+```typescript
+// ✅ Good - theme is mutable
+const $theme = state('light')
+
+// Can update it
+$theme.set('dark')
+```
+
+### Creating Too Many Constants
+
+**Problem**: Making every value a constant even when plain const would work.
+
+```typescript
+// ❌ Overkill - not used reactively
+const $pi = constant(3.14159)
+const $maxLength = constant(100)
+
+function calculate() {
+  return $pi.pick() * radius // Just use plain const
+}
+```
+
+**Solution**: Use plain const for non-reactive values:
+
+```typescript
+// ✅ Better - plain JavaScript
+const PI = 3.14159
+const MAX_LENGTH = 100
+
+function calculate() {
+  return PI * radius
+}
+```
+
+### Expecting Constants to Update
+
+**Problem**: Thinking constants will somehow update like state.
+
+```typescript
+// ❌ Wrong - constant won't update
+const $userName = constant('Alice')
+
+effect((t) => {
+  const name = $userName.get(t)
+  console.log(name) // Always "Alice"
+})
+
+// This won't work - no .set() method!
+// $userName.set('Bob')
+```
+
+**Solution**: Use state if the value needs to change:
+
+```typescript
+// ✅ Correct - use state
+const $userName = state('Alice')
+
+effect((t) => {
+  const name = $userName.get(t)
+  console.log(name) // Updates when changed
+})
+
+$userName.set('Bob') // Now this works!
+```
+
+### Lazy Init with Side Effects
+
+**Problem**: Using lazy initialization with side effects.
+
+```typescript
+// ❌ Bad - side effects in lazy init
+const $config = constant(() => {
+  console.log('Loading config...') // Side effect!
+  localStorage.setItem('loaded', 'true') // Side effect!
+  return loadConfig()
+})
+```
+
+**Solution**: Keep lazy init pure, handle side effects elsewhere:
+
+```typescript
+// ✅ Better - pure initialization
+const $config = constant(() => loadConfig())
+
+// Handle side effects separately
+effect((t) => {
+  const config = $config.get(t)
+  console.log('Config loaded:', config)
+  localStorage.setItem('loaded', 'true')
+})
+```
+

package/docs/guide/primitives/derivations.md

@@ -0,0 +1,348 @@
+# Derivations
+
+Derivations are **reactive formulas** that compute values based on other reactive primitives. They're pure functions that track their dependencies and efficiently recompute when needed.
+
+### Key Characteristics
+
+- **Lazy evaluation**: Computes only when accessed, not when created
+- **Automatic caching**: Caches results until dependencies change
+- **Dirty tracking**: Marked as "dirty" on changes, recomputes on next access
+- **Pure computation**: Should have no side effects
+- **Efficient**: Avoids unnecessary recomputation through smart caching
+
+## When to Use Derivations
+
+Use derivations when you need to:
+
+- ✅ Compute values from other reactive primitives
+- ✅ Transform or filter data reactively
+- ✅ Create calculated fields (totals, averages, formatted values)
+- ✅ Chain computations together
+- ✅ Build complex reactive data flows
+
+Don't use derivations when:
+
+- ❌ You need to perform side effects (use effects instead)
+- ❌ The computation is not pure or deterministic
+
+::: tip
+Not sure whether to use a derivation or an effect? See the [Derivations vs Effects](./overview.md#derivations-vs-effects) section for a detailed comparison and guidance.
+:::
+
+
+## Creating Derivations
+
+Creating a derivation is straightforward:
+
+```typescript
+import { derivation } from '@ersbeth/picoflow'
+
+const $doubled = derivation((t) => {
+  // Your computation here
+  return $count.get(t) * 2
+})
+```
+
+TypeScript automatically infers the return type based on what your function returns.
+
+## Using Derivations
+
+Derivations have several methods for reading values and managing lifecycle.
+
+### Reading with `.get(t)` (Reactive)
+
+Inside an effect or another derivation, use `.get(t)` to read the value and track the dependency:
+
+```typescript
+const $count = state(10)
+const $doubled = derivation((t) => $count.get(t) * 2)
+
+effect((t) => {
+  const value = $doubled.get(t) // Tracks dependency
+  console.log('Doubled:', value)
+})
+
+$count.set(20) // Logs: "Doubled: 40"
+```
+
+### Reading with `.pick()` (Non-Reactive)
+
+Use `.pick()` to read the current value without tracking:
+
+```typescript
+const $count = state(10)
+const $doubled = derivation((t) => $count.get(t) * 2)
+
+// Read once without tracking
+const snapshot = $doubled.pick()
+console.log(snapshot) // 20
+
+$count.set(20)
+// No reaction because we used .pick()
+```
+
+### Chaining Derivations
+
+Derivations can depend on other derivations, creating chains of reactive computations:
+
+```typescript
+const $items = state([10, 20, 30])
+
+// First derivation: sum
+const $sum = derivation((t) => {
+  return $items.get(t).reduce((a, b) => a + b, 0)
+})
+
+// Second derivation: average (depends on $sum)
+const $average = derivation((t) => {
+  const sum = $sum.get(t)
+  const count = $items.pick().length
+  return sum / count
+})
+
+// Third derivation: formatted (depends on $average)
+const $formatted = derivation((t) => {
+  const avg = $average.get(t)
+  return `Average: ${avg.toFixed(2)}`
+})
+
+effect((t) => {
+  console.log($formatted.get(t))
+})
+
+$items.set([15, 25, 35]) // All derivations update in sequence
+```
+
+```mermaid
+graph LR
+    A[$items] --> B[$sum]
+    B --> C[$average]
+    A -.-> C
+    C --> D[$formatted]
+    D --> E[Effect]
+```
+
+### Disposing with `.dispose()`
+
+Derivations can be disposed to free resources and prevent memory leaks:
+
+```typescript
+const $doubled = derivation((t) => $count.get(t) * 2)
+
+// Use the derivation
+effect((t) => {
+  console.log($doubled.get(t))
+})
+
+// Later, clean up
+$doubled.dispose()
+
+// Subsequent operations will throw
+$doubled.get(someContext) // Error: Primitive is disposed
+```
+
+## Lifecycle
+
+Derivations use a lazy, cached evaluation model with dirty checking. Understanding this lifecycle is key to writing efficient reactive code.
+
+When you create a derivation, it doesn't execute immediately. It waits until someone needs its value. Once computed, the value is cached. When dependencies change, the derivation is marked as "dirty" but doesn't recompute until accessed again.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $count as $count (State)
+    participant $doubled as $doubled (Derivation)
+    participant Effect
+    
+    Note over User,$doubled: 1. Creation Phase
+    User->>$doubled: Create derivation
+    Note over $doubled: Store function<br/>NOT executed yet
+    
+    Note over User,Effect: 2. First Access
+    User->>Effect: Create effect
+    activate Effect
+    Effect->>$doubled: get(t)
+    activate $doubled
+    Note over $doubled: Not computed yet<br/>Need to compute!
+    
+    $doubled->>$count: get(t)
+    activate $count
+    Note over $count: Register $doubled as dependent
+    $count-->>$doubled: 0
+    deactivate $count
+    
+    Note over $doubled: Compute: 0 * 2 = 0<br/>Cache result
+    $doubled-->>Effect: 0
+    deactivate $doubled
+    Note over Effect: Log: "Doubled: 0"
+    deactivate Effect
+    
+    Note over User,Effect: 3. Dependency Change
+    User->>$count: set(5)
+    activate $count
+    Note over $count: Value changed
+    
+    $count->>$doubled: Notify (mark dirty)
+    activate $doubled
+    Note over $doubled: Mark as dirty<br/>NO recompute yet!
+    deactivate $doubled
+    
+    $count->>Effect: Schedule execution
+    deactivate $count
+    
+    Note over User,Effect: 4. Recompute on Access
+    activate Effect
+    Effect->>$doubled: get(t)
+    activate $doubled
+    Note over $doubled: Dirty? YES<br/>Recompute now!
+    
+    $doubled->>$count: get(t)
+    activate $count
+    $count-->>$doubled: 5
+    deactivate $count
+    
+    Note over $doubled: Compute: 5 * 2 = 10<br/>Cache new result
+    $doubled-->>Effect: 10
+    deactivate $doubled
+    Note over Effect: Log: "Doubled: 10"
+    deactivate Effect
+    
+    Note over User,Effect: 5. Cached Access
+    User->>$doubled: pick()
+    activate $doubled
+    Note over $doubled: Not dirty<br/>Return cache
+    $doubled-->>User: 10
+    deactivate $doubled
+```
+
+### Key Lifecycle Points
+
+1. **Creation**: The derivation function is stored but not executed
+2. **First Access**: Computes the value, tracks dependencies, and caches the result
+3. **Dependency Change**: Marked as "dirty" but doesn't recompute immediately
+4. **Dirty Access**: Recomputes because it's dirty, caches new result
+5. **Clean Access**: Returns cached value without recomputation
+
+This lazy + cached approach means:
+- **Unused derivations never compute** (no wasted CPU)
+- **Multiple reads use the cache** (efficient)
+- **Multiple dependency changes = one recompute** (optimized)
+
+## Best Practices
+
+### Keep Derivations Pure
+
+Derivations should be pure functions with no side effects:
+
+```typescript
+// ✅ Good - pure function
+const $total = derivation((t) => {
+  return $items.get(t).reduce((sum, item) => sum + item.price, 0)
+})
+
+// ❌ Bad - side effect
+const $total = derivation((t) => {
+  const total = $items.get(t).reduce((sum, item) => sum + item.price, 0)
+  console.log('Total:', total) // Side effect!
+  return total
+})
+```
+
+**Why pure?** PicoFlow may skip recomputation if it thinks the result hasn't changed. Side effects would be unpredictable!
+
+### Name Derivations Clearly
+
+Use names that describe the computed value:
+
+```typescript
+// ✅ Good - clear what it computes
+const $totalPrice = derivation((t) => ...)
+const $filteredUsers = derivation((t) => ...)
+const $formattedDate = derivation((t) => ...)
+
+// ❌ Bad - unclear purpose
+const $result = derivation((t) => ...)
+const $temp = derivation((t) => ...)
+```
+
+## Common Pitfalls
+
+### Side Effects in Derivations
+
+**Problem**: Adding side effects (logging, API calls, DOM updates) in a derivation.
+
+```typescript
+// ❌ Wrong - side effect in derivation
+const $count = state(0)
+const $logged = derivation((t) => {
+  const value = $count.get(t)
+  console.log('Count:', value) // Side effect!
+  return value * 2
+})
+```
+
+**Solution**: Move side effects to an effect:
+
+```typescript
+// ✅ Correct - side effect in effect
+const $count = state(0)
+
+effect((t) => {
+  const value = $count.get(t)
+  console.log('Count:', value) // Side effect here is fine
+})
+
+const $doubled = derivation((t) => {
+  return $count.get(t) * 2 // Pure computation
+})
+```
+
+### Using `.pick()` Instead of `.get(t)`
+
+**Problem**: Using `.pick()` inside a derivation breaks doesn't trigger the reactivity system.
+
+```typescript
+// ❌ Derivation doesn't track $count
+const $count = state(10)
+const $doubled = derivation((t) => {
+  return $count.pick() * 2 // No dependency tracking!
+})
+
+effect((t) => {
+  console.log($doubled.get(t))
+})
+
+$count.set(20) // Effect won't run - no dependency!
+```
+
+**Solution**: Always use `.get(t)` to track dependencies:
+
+```typescript
+// ✅ Correct - tracks $count
+const $doubled = derivation((t) => {
+  return $count.get(t) * 2
+})
+```
+
+### Mutating Returned Values
+
+**Problem**: Mutating arrays or objects returned from derivations doesn't trigger the reactivity system.
+
+```typescript
+// ❌ Mutating the array
+const $items = state([1, 2, 3])
+const $doubled = derivation((t) => {
+  const items = $items.get(t)
+  items.forEach((v, i) => items[i] = v * 2) // Mutation!
+  return items
+})
+```
+
+**Solution**: Always return new values:
+
+```typescript
+// ✅ Return new array
+const $doubled = derivation((t) => {
+  return $items.get(t).map(v => v * 2)
+})
+```