@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/guide/primitives/constant.md

@@ -1,50 +1,38 @@
 # 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.
+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.
 
-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
+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:
 
-- ✅ 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:
+Constants always take a function that returns the value. This function is called lazily on first access:
 
 ```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')
+// 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')
 ```
 
-### Lazy Initialization
+### Expensive Computations
 
-Pass a function to defer computation until first access:
+The lazy initialization makes constants perfect for expensive one-time computations:
 
 ```typescript
-// Lazy initialization - computed on first access
 const $expensiveValue = constant(() => {
   console.log('Computing expensive value...')
   return performExpensiveCalculation()
@@ -52,8 +40,7 @@ const $expensiveValue = constant(() => {
 
 // Nothing logged yet - function not called
 
-effect((t) => {
-  const value = $expensiveValue.get(t)
+$expensiveValue.subscribe((value) => {
   // NOW it logs: "Computing expensive value..."
   console.log(value)
 })
@@ -65,92 +52,51 @@ effect((t) => {
 
 Constants provide two ways to read values:
 
-### Reading with `.get(t)`
+### Get
 
-Inside an effect or derivation, use `.get(t)` to read the value and create a dependency:
+Inside a subscription or derivation, use `.get(t)` to read the value and create a dependency:
 
 ```typescript
-import { constant, effect } from '@ersbeth/picoflow'
+import { constant } from '@ersbeth/picoflow'
 
-const $config = constant({ apiUrl: 'https://api.example.com' })
+const $config = constant(() => ({ apiUrl: 'https://api.example.com' }))
+const $merged = derivation((t) => ({url: $config.get(t).apiUrl, data: someOtherData}))
 
-effect((t) => {
-  const config = $config.get(t) // Read and track
-  console.log('API URL:', config.apiUrl)
+$merged.subscribe((merged) => {
+  console.log('Merged data', merged)
 })
 ```
 
-### Reading with `.pick()`
+### Pick
 
 Use `.pick()` when you want the current value without creating a dependency:
 
 ```typescript
-const $config = constant({ apiUrl: 'https://api.example.com' })
+const $config = constant(() => ({ apiUrl: 'https://api.example.com' }))
 
-// Read without tracking (e.g., outside an effect)
-const currentConfig = $config.pick()
+// Read without tracking (e.g., outside a subscription or derivation)
+const currentConfig = await $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()`
+### Dispose
 
 Constants can be disposed to free resources:
 
 ```typescript
-const $config = constant({ apiUrl: 'https://api.example.com' })
+const $config = constant(() => ({ apiUrl: 'https://api.example.com' }))
 
 // Later, clean up
 $config.dispose()
 
 // Subsequent operations will throw
-$config.get(t) // Error: Primitive is disposed
+$config.pick() // 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:
+Constants use lazy initialization - the function you provide is executed only on first access:
 
 ```mermaid
 sequenceDiagram
@@ -189,77 +135,38 @@ sequenceDiagram
 
 **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
+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 stored function
+   - If not, execute the function
    - Cache result and mark as initialized
 
-3. **Subsequent access**: Always return cached value
+3. **Subsequent access**: Always return cached value (function never called again)
 
 ## 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
+### Use Constants for Expensive Computations
 
-Perfect for application configuration:
+Constants defer expensive work until it's actually needed:
 
 ```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
+// ✅ Good - lazy evaluation with constant
+const $parsedData = constant(() => JSON.parse(largeDataString))
 
-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')
+// ❌ Eager - runs immediately (plain JavaScript)
+const parsedData = JSON.parse(largeDataString)
 ```
 
 ### Prefer Plain const for Non-Reactive Values
 
-If no effects or derivations will read it, use plain JavaScript:
+If no subscriptions 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
+const $localConfig = constant(() => ({ timeout: 5000 }))
+function async fetch() {
+  const config = await $localConfig.pick() // Never tracked
   return doFetch(config)
 }
 
@@ -272,85 +179,6 @@ function fetch() {
 
 ## 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.
@@ -371,8 +199,7 @@ const $config = constant(() => {
 const $config = constant(() => loadConfig())
 
 // Handle side effects separately
-effect((t) => {
-  const config = $config.get(t)
+$config.subscribe((config) => {
   console.log('Config loaded:', config)
   localStorage.setItem('loaded', 'true')
 })

package/docs/guide/primitives/derivations.md

@@ -6,9 +6,6 @@ Derivations are **reactive formulas** that compute values based on other reactiv
 
 - **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
 
@@ -16,17 +13,14 @@ 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
+- ❌ You need to perform side effects (use subscribe instead)
 
 ::: 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.
+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.
 :::
 
 
@@ -37,6 +31,8 @@ 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
@@ -49,23 +45,23 @@ TypeScript automatically infers the return type based on what your function retu
 
 Derivations have several methods for reading values and managing lifecycle.
 
-### Reading with `.get(t)` (Reactive)
+### Get
 
-Inside an effect or another derivation, use `.get(t)` to read the value and track the dependency:
+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)
 
-effect((t) => {
-  const value = $doubled.get(t) // Tracks dependency
-  console.log('Doubled:', value)
+$result.subscribe((value) => {
+  console.log('Result:', value)
 })
 
-$count.set(20) // Logs: "Doubled: 40"
+$count.set(20) // Logs: "Result: 42"
 ```
 
-### Reading with `.pick()` (Non-Reactive)
+### Pick
 
 Use `.pick()` to read the current value without tracking:
 
@@ -81,7 +77,26 @@ $count.set(20)
 // No reaction because we used .pick()
 ```
 
-### Chaining Derivations
+### 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:
 
@@ -96,7 +111,7 @@ const $sum = derivation((t) => {
 // Second derivation: average (depends on $sum)
 const $average = derivation((t) => {
   const sum = $sum.get(t)
-  const count = $items.pick().length
+  const count = $items.get(t).length
   return sum / count
 })
 
@@ -106,8 +121,8 @@ const $formatted = derivation((t) => {
   return `Average: ${avg.toFixed(2)}`
 })
 
-effect((t) => {
-  console.log($formatted.get(t))
+$formatted.subscribe((value) => {
+  console.log(value)
 })
 
 $items.set([15, 25, 35]) // All derivations update in sequence
@@ -119,27 +134,10 @@ graph LR
     B --> C[$average]
     A -.-> C
     C --> D[$formatted]
-    D --> E[Effect]
+    D --> E[Subscription]
 ```
 
-### 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
 
@@ -152,16 +150,16 @@ sequenceDiagram
     participant User
     participant $count as $count (State)
     participant $doubled as $doubled (Derivation)
-    participant Effect
+    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,Effect: 2. First Access
-    User->>Effect: Create effect
-    activate Effect
-    Effect->>$doubled: get(t)
+    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!
     
@@ -172,12 +170,12 @@ sequenceDiagram
     deactivate $count
     
     Note over $doubled: Compute: 0 * 2 = 0<br/>Cache result
-    $doubled-->>Effect: 0
+    $doubled-->>Subscription: 0
     deactivate $doubled
-    Note over Effect: Log: "Doubled: 0"
-    deactivate Effect
+    Note over Subscription: Log: "Doubled: 0"
+    deactivate Subscription
     
-    Note over User,Effect: 3. Dependency Change
+    Note over User,Subscription: 3. Dependency Change
     User->>$count: set(5)
     activate $count
     Note over $count: Value changed
@@ -187,12 +185,12 @@ sequenceDiagram
     Note over $doubled: Mark as dirty<br/>NO recompute yet!
     deactivate $doubled
     
-    $count->>Effect: Schedule execution
+    $count->>Subscription: Schedule execution
     deactivate $count
     
-    Note over User,Effect: 4. Recompute on Access
-    activate Effect
-    Effect->>$doubled: get(t)
+    Note over User,Subscription: 4. Recompute on Access
+    activate Subscription
+    Subscription->>$doubled: get(t)
     activate $doubled
     Note over $doubled: Dirty? YES<br/>Recompute now!
     
@@ -202,12 +200,12 @@ sequenceDiagram
     deactivate $count
     
     Note over $doubled: Compute: 5 * 2 = 10<br/>Cache new result
-    $doubled-->>Effect: 10
+    $doubled-->>Subscription: 10
     deactivate $doubled
-    Note over Effect: Log: "Doubled: 10"
-    deactivate Effect
+    Note over Subscription: Log: "Doubled: 10"
+    deactivate Subscription
     
-    Note over User,Effect: 5. Cached Access
+    Note over User,Subscription: 5. Cached Access
     User->>$doubled: pick()
     activate $doubled
     Note over $doubled: Not dirty<br/>Return cache
@@ -228,43 +226,6 @@ This lazy + cached approach means:
 - **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
@@ -281,14 +242,13 @@ const $logged = derivation((t) => {
 })
 ```
 
-**Solution**: Move side effects to an effect:
+**Solution**: Move side effects to a subscription:
 
 ```typescript
-// ✅ Correct - side effect in effect
+// ✅ Correct - side effect in subscription
 const $count = state(0)
 
-effect((t) => {
-  const value = $count.get(t)
+$count.subscribe((value) => {
   console.log('Count:', value) // Side effect here is fine
 })
 
@@ -297,33 +257,6 @@ const $doubled = derivation((t) => {
 })
 ```
 
-### 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.