@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/guide/primitives/constant.md

@@ -1,207 +0,0 @@
-# Constants
-
-A **constant** is a reactive primitive that holds an immutable value computed lazily on first access. Constants integrate immutable values into the reactive system, allowing them to be tracked as dependencies while ensuring they never change.
-
-The key benefit of constants is **lazy initialization** - the value isn't computed until it's first accessed, making them perfect for expensive one-time computations like parsing configuration files or building lookup tables.
-
-## When to Use Constants
-
-Use constants when you need to:
-
-- ✅ Cache expensive computations that only run once
-
-Don't use constants when:
-
-- ❌ The value needs to change (use state instead)
-- ❌ The value isn't reactive (use plain `const` instead)
-
-## Creating Constants
-
-Constants always take a function that returns the value. This function is called lazily on first access:
-
-```typescript
-import { constant } from '@ersbeth/picoflow'
-
-// Function is required - value computed on first access
-const $apiUrl = constant(() => 'https://api.example.com')
-const $config = constant(() => ({ apiUrl: 'https://api.example.com', timeout: 5000 }))
-const $version = constant(() => '1.0.0')
-```
-
-### Expensive Computations
-
-The lazy initialization makes constants perfect for expensive one-time computations:
-
-```typescript
-const $expensiveValue = constant(() => {
-  console.log('Computing expensive value...')
-  return performExpensiveCalculation()
-})
-
-// Nothing logged yet - function not called
-
-$expensiveValue.subscribe((value) => {
-  // 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:
-
-### Get
-
-Inside a subscription or derivation, use `.get(t)` to read the value and create a dependency:
-
-```typescript
-import { constant } from '@ersbeth/picoflow'
-
-const $config = constant(() => ({ apiUrl: 'https://api.example.com' }))
-const $merged = derivation((t) => ({url: $config.get(t).apiUrl, data: someOtherData}))
-
-$merged.subscribe((merged) => {
-  console.log('Merged data', merged)
-})
-```
-
-### 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 a subscription or derivation)
-const currentConfig = await $config.pick()
-console.log(currentConfig.apiUrl)
-
-```
-
-### 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.pick() // Error: Primitive is disposed
-```
-
-## Lifecycle
-
-Constants use lazy initialization - the function you provide is executed only 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**: Store the initializer function, mark as not initialized
-
-2. **First access**: When `.get(t)` or `.pick()` is called
-   - Check if initialized
-   - If not, execute the function
-   - Cache result and mark as initialized
-
-3. **Subsequent access**: Always return cached value (function never called again)
-
-## Best Practices
-
-### Use Constants for Expensive Computations
-
-Constants defer expensive work until it's actually needed:
-
-```typescript
-// ✅ Good - lazy evaluation with constant
-const $parsedData = constant(() => JSON.parse(largeDataString))
-
-// ❌ Eager - runs immediately (plain JavaScript)
-const parsedData = JSON.parse(largeDataString)
-```
-
-### Prefer Plain const for Non-Reactive Values
-
-If no subscriptions or derivations will read it, use plain JavaScript:
-
-```typescript
-// ❌ Unnecessary - no reactivity needed
-const $localConfig = constant(() => ({ timeout: 5000 }))
-function async fetch() {
-  const config = await $localConfig.pick() // Never tracked
-  return doFetch(config)
-}
-
-// ✅ Better - plain const
-const localConfig = { timeout: 5000 }
-function fetch() {
-  return doFetch(localConfig)
-}
-```
-
-## Common Pitfalls
-
-### 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
-$config.subscribe((config) => {
-  console.log('Config loaded:', config)
-  localStorage.setItem('loaded', 'true')
-})
-```
-

package/docs/guide/primitives/derivations.md

@@ -1,281 +0,0 @@
-# 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
-
-## When to Use Derivations
-
-Use derivations when you need to:
-
-- ✅ Compute values from other reactive primitives
-- ✅ Transform or filter data reactively
-- ✅ Build complex reactive data flows
-
-Don't use derivations when:
-
-- ❌ You need to perform side effects (use subscribe instead)
-
-::: tip
-Not sure whether to use a derivation or a side effect? See the [Derivations vs Side Effects](./overview.md#derivations-vs-side-effects) section for a detailed comparison and guidance.
-:::
-
-
-## Creating Derivations
-
-Creating a derivation is straightforward:
-
-```typescript
-import { derivation } from '@ersbeth/picoflow'
-
-const $count = state(1);
-
-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.
-
-### Get
-
-Inside a subscription 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)
-const $result = derivation(t)=> $doubled.get(t) + 2)
-
-$result.subscribe((value) => {
-  console.log('Result:', value)
-})
-
-$count.set(20) // Logs: "Result: 42"
-```
-
-### Pick
-
-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()
-```
-
-### Dispose
-
-Derivations can be disposed to free resources and prevent memory leaks:
-
-```typescript
-const $doubled = derivation((t) => $count.get(t) * 2)
-
-// Use the derivation
-$doubled.subscribe((value) => {
-  console.log(value)
-})
-
-// Later, clean up
-$doubled.dispose()
-
-// Subsequent operations will throw
-await $doubled.pick() // Error: Primitive is disposed
-```
-
-## 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.get(t).length
-  return sum / count
-})
-
-// Third derivation: formatted (depends on $average)
-const $formatted = derivation((t) => {
-  const avg = $average.get(t)
-  return `Average: ${avg.toFixed(2)}`
-})
-
-$formatted.subscribe((value) => {
-  console.log(value)
-})
-
-$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[Subscription]
-```
-
-
-
-## 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 Subscription
-    
-    Note over User,$doubled: 1. Creation Phase
-    User->>$doubled: Create derivation
-    Note over $doubled: Store function<br/>NOT executed yet
-    
-    Note over User,Subscription: 2. First Access
-    User->>Subscription: Create subscription
-    activate Subscription
-    Subscription->>$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-->>Subscription: 0
-    deactivate $doubled
-    Note over Subscription: Log: "Doubled: 0"
-    deactivate Subscription
-    
-    Note over User,Subscription: 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->>Subscription: Schedule execution
-    deactivate $count
-    
-    Note over User,Subscription: 4. Recompute on Access
-    activate Subscription
-    Subscription->>$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-->>Subscription: 10
-    deactivate $doubled
-    Note over Subscription: Log: "Doubled: 10"
-    deactivate Subscription
-    
-    Note over User,Subscription: 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)
-
-## 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 a subscription:
-
-```typescript
-// ✅ Correct - side effect in subscription
-const $count = state(0)
-
-$count.subscribe((value) => {
-  console.log('Count:', value) // Side effect here is fine
-})
-
-const $doubled = derivation((t) => {
-  return $count.get(t) * 2 // Pure computation
-})
-```
-
-### 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)
-})
-```