@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/guide/advanced/migration-v2.md

@@ -0,0 +1,204 @@
+# Migration Guide: v1.x.x → v2.0.0
+
+PicoFlow v2 introduces several breaking changes that improve consistency, performance, and API clarity. This guide will help you migrate your codebase from v1.x.x to v2.0.0.
+
+## Quick Summary
+
+- **Effect API removed** - replaced with `subscribe()` and `.subscribe()`
+- **FlowMap tracking simplified** - single `$lastAction` signal instead of three separate signals
+- **FlowArray method renamed** - `setItem()` → `update()`
+- **Constant always lazy** - must use function initializer
+- **Improved terminology** - "effects" → "subscriptions", clearer naming
+
+
+## Breaking Changes
+
+### 1. Effect API Removed
+
+The global `effect()` function has been removed in favor of `subscribe()` and `.subscribe()` methods.
+
+**v1.x.x:**
+```typescript
+import { effect } from '@ersbeth/picoflow'
+
+effect((t) => {
+  const value = $state.get(t)
+  console.log(value)
+})
+```
+
+**v2.0.0:**
+```typescript
+// Option A: Single primitive - use .subscribe()
+$state.subscribe((value) => {
+  console.log(value)
+})
+
+// Option B: Multiple primitives - use subscribe()
+import { subscribe } from '@ersbeth/picoflow'
+
+subscribe(
+  (t) => ({ a: $state1.get(t), b: $state2.get(t) }),
+  (data) => {
+    console.log(data.a, data.b)
+  }
+)
+```
+
+### 2. FlowMap Fine-Grained Tracking Changed
+
+FlowMap now uses a single `$lastAction` signal instead of three separate signals.
+
+**v1.x.x:**
+```typescript
+const $users = map<number, User>()
+
+// Three separate signals
+$users.$lastAdded.subscribe((added) => {
+  console.log(added.key, added.value)
+})
+
+$users.$lastUpdated.subscribe((updated) => {
+  console.log(updated.key, updated.value)
+})
+
+$users.$lastDeleted.subscribe((deleted) => {
+  console.log(deleted.key, deleted.value)
+})
+```
+
+**v2.0.0:**
+```typescript
+const $users = map<number, User>()
+
+// Single $lastAction signal
+$users.$lastAction.subscribe((action) => {
+  if (!action) return
+  
+  switch (action.type) {
+    case 'add':
+      console.log(action.key, action.addedValue)
+      break
+    case 'update':
+      console.log(action.key, action.setValue, action.clearedValue)
+      break
+    case 'delete':
+      console.log(action.key, action.removedValue)
+      break
+  }
+})
+```
+
+### 3. FlowArray: `setItem()` → `update()`
+
+The `setItem()` method has been renamed to `update()` for consistency.
+
+**v1.x.x:**
+```typescript
+const $items = array([1, 2, 3])
+$items.setItem(0, 10)
+```
+
+**v2.0.0:**
+```typescript
+const $items = array([1, 2, 3])
+$items.update(0, 10)
+```
+
+### 4. Constant Always Requires Function Initializer
+
+Constants now always require a function initializer, enforcing lazy evaluation.
+
+**v1.x.x (if direct values were allowed):**
+```typescript
+const $config = constant({ api: 'https://api.com' })
+const $version = constant('1.0.0')
+```
+
+**v2.0.0:**
+```typescript
+const $config = constant(() => ({ api: 'https://api.com' }))
+const $version = constant(() => '1.0.0')
+```
+
+### 5. Terminology Updates
+
+Some terminology has been clarified for better understanding.
+
+#### Changes
+
+| v1 Term | v2 Term | Notes |
+|---------|---------|-------|
+| "Effects" | "Side Effects" or "Subscriptions" | More precise |
+| "TrackingContext" | "FlowTracker" | Official type name |
+| `effect()` | `subscribe()` / `.subscribe()` | API change |
+
+#### Migration
+
+No code changes required - these are documentation updates. However, updating your comments and variable names to match the new terminology is recommended.
+
+**Example:**
+```typescript
+// Before
+const fx = effect((t) => { ... }) // Create effect
+
+// After
+const effect = $state.subscribe((value) => { ... }) // Create subscription
+```
+
+## Step-by-Step Migration Guide
+
+Follow these steps for a smooth migration:
+
+### 1. Update Dependencies
+
+```bash
+npm install @ersbeth/picoflow@^2.0.0
+# or
+pnpm add @ersbeth/picoflow@^2.0.0
+```
+
+### 2. Migrate Effects (Highest Priority)
+
+Search for all `effect(` usages and migrate them:
+- Single primitive → `.subscribe()`
+- Multiple primitives → `subscribe()`
+- Signals → `$signal.subscribe()`
+
+**Tip**: Use your editor's "Find All" to locate all occurrences.
+
+### 3. Update FlowMap Tracking
+
+Search for:
+- `$lastAdded` → migrate to `$lastAction` with type check
+- `$lastUpdated` → migrate to `$lastAction` with type check  
+- `$lastDeleted` → migrate to `$lastAction` with type check
+
+Update property names in action handlers.
+
+### 4. Rename FlowArray Methods
+
+Search and replace: `.setItem(` → `.update(`
+
+### 5. Fix Constant Initialization
+
+Search for `constant(` and ensure all have function initializers.
+
+### 6. Test Thoroughly
+
+Run your test suite and manually test reactive behaviors.
+
+### 7. Update Documentation
+
+Update internal docs, comments, and variable names to use v2 terminology.
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [API documentation](/api/)
+2. Review the [primitives guide](/guide/primitives/overview)
+3. See the [side effects guide](/guide/primitives/effects)
+4. Open an issue on GitHub with a minimal reproduction
+
+Happy migrating! 🚀

package/docs/guide/advanced/solidjs.md

@@ -73,7 +73,7 @@ const $count = state(0)
 function Counter() {
   // Convert to Solid primitive
   const count = from($count)
-  return <div>Count: {count.get()}</div>
+  return <div>Count: {count()}</div>
 }
 ```
 
@@ -90,92 +90,6 @@ The `from()` function automatically determines the right Solid primitive based o
 | `(t) => T` (getter function) | `SolidDerivation<T>` | Synchronous computation |
 | `(t) => Promise<T>` (getter function) | `SolidResource<T>` | Asynchronous computation |
 
-## SolidJS Primitives
-
-PicoFlow also provides Solid-style primitives that you can use directly in Solid components. These are thin wrappers around SolidJS's built-in primitives with a class-based API consistent with PicoFlow's style.
-
-### SolidState
-
-`SolidState` wraps SolidJS's `createSignal`:
-
-```typescript
-import { SolidState } from '@ersbeth/picoflow/solid'
-
-// Use in component
-function Counter() {
-
-  // Create Solid state
-  const count = new SolidState(0)
-
-  return (
-    <div>
-      <p>Count: {count.get()}</p>
-      <button onClick={() => count.set(count.get() + 1)}>Increment</button>
-      <button onClick={() => count.set(prev => prev + 1)}>Increment (updater)</button>
-    </div>
-  )
-}
-```
-
-**When to use:** When you want a simple reactive state that's only used in Solid components.
-
-### SolidDerivation
-
-`SolidDerivation` wraps SolidJS's `createMemo`:
-
-```typescript
-import { SolidState, SolidDerivation } from '@ersbeth/picoflow/solid'
-
-// Use in component
-function NameDisplay() {
-  const firstName = new SolidState('John')
-  const lastName = new SolidState('Doe')
-  
-  // Create derived value
-  const fullName = new SolidDerivation(() => {
-    return `${firstName.get()} ${lastName.get()}`
-  })
-  return <div>{fullName.get()}</div> // Automatically updates
-}
-```
-
-**When to use:** When you need computed values that are only used in Solid components.
-
-### SolidResource
-
-`SolidResource` wraps SolidJS's `createResource`:
-
-```typescript
-import { SolidResource } from '@ersbeth/picoflow/solid'
-
-// Use in component
-function UserProfile() {
-
-  // Create resource
-  const user = new SolidResource(async () => {
-    const res = await fetch('/api/user')
-    return res.json()
-  })
-
-  const userData = user.get()
-  
-  return (
-    <div>
-      {user.state() === 'pending' && <p>Loading...</p>}
-      {state.state() === 'ready' && user.latest() && (
-        <>
-          <h1>{user.latest().name}</h1>
-          <p>{user.latest().email}</p>
-        </>
-      )}
-      {user.state() === 'errored' && <p>Error loading user</p>}
-      <button onClick={() => user.refetch()}>Refresh</button>
-    </div>
-  )
-}
-```
-
-**When to use:** When you need async data loading that integrates with SolidJS's Suspense and ErrorBoundary.
 
 ## Complete Examples
 
@@ -196,7 +110,7 @@ function Counter() {
   
   return (
     <div>
-      <p>Count: {count.get()}</p>
+      <p>Count: {count()}</p>
       <p>{isEven.get() ? 'Even' : 'Odd'}</p>
       <button onClick={() => $count.set(prev => prev + 1)}>Increment</button>
       <button onClick={() => $count.set(prev => prev - 1)}>Decrement</button>

package/docs/guide/introduction/concepts.md

@@ -38,9 +38,10 @@ With reactive programming, dependencies update automatically:
 const $count = state(0)
 const $doubled = derivation((t) => $count.get(t) * 2)
 
-effect((t) => {
-  updateUI($count.get(t), $doubled.get(t)) // Runs automatically!
-})
+subscribe(
+  (t) => ({ count: $count.get(t), doubled: $doubled.get(t) }),
+  (data) => updateUI(data.count, data.doubled) // Runs automatically!
+)
 
 function increment() {
   $count.set(n => n + 1) // Everything else updates automatically!

package/docs/guide/introduction/conventions.md

@@ -1,8 +1,4 @@
-# Conventions
-
-PicoFlow follows simple, consistent conventions that make your reactive code easier to read and maintain. These conventions help you quickly identify reactive values and understand data flow at a glance.
-
-## The $ Prefix 
+# Naming Convention
 
 You'll see variables prefixed with `$` throughout PicoFlow examples:
 
@@ -27,35 +23,8 @@ const $userAge = state(25)
 const $isAdult = derivation((t) => $userAge.get(t) >= 18)
 
 // Plain values - no $ prefix
-const currentName = $userName.pick()  // Snapshot of current value
+const currentName = await $userName.pick()  // Snapshot of current value
 const maxAge = 100                     // Constant
 ```
 
-## Benefits
-
-**1. Visual Clarity**
-
-```typescript
-// Clear distinction between reactive and non-reactive
-function updateProfile(newName: string) {
-  $userName.set(newName)  // $ = reactive, will trigger effects
-  const timestamp = Date.now()  // no $ = plain value
-}
-```
-
-**2. Prevents Confusion**
-
-```typescript
-// Easy to see what's reactive
-effect((t) => {
-  const user = $currentUser.get(t)      // $ = will re-run on change
-  const config = appConfig               // no $ = static value
-  
-  fetchUserData(user.id, config)
-})
-```
-
-**3. Code Review**
-
-When reviewing code, the `$` prefix makes it immediately obvious which variables should be part of the reactive system and which should be regular JavaScript values.
 

package/docs/guide/introduction/getting-started.md

@@ -54,13 +54,13 @@ yarn add solid-js
 Import the primitives you need:
 
 ```typescript
-import { state, effect, derivation, signal } from '@ersbeth/picoflow'
+import { state, derivation, subscribe } from '@ersbeth/picoflow'
 ```
 
 For SolidJS integration:
 
 ```typescript
-import { from } from '@ersbeth/picoflow/solid'
+import { from } from '@ersbeth/picoflow'
 ```
 
 ## Your First PicoFlow App
@@ -68,7 +68,7 @@ import { from } from '@ersbeth/picoflow/solid'
 Let's build a simple counter with PicoFlow:
 
 ```typescript
-import { state, derivation, effect } from '@ersbeth/picoflow'
+import { state, derivation, subscribe } from '@ersbeth/picoflow'
 
 // Create reactive state (prefix with $ by convention)
 const $count = state(0)
@@ -79,12 +79,13 @@ const $isEven = derivation((t) => {
 })
 
 // React to changes
-effect((t) => {
-  const count = $count.get(t)
-  const even = $isEven.get(t)
-  console.log(`Count is ${count}, which is ${even ? 'even' : 'odd'}`)
-})
-// Logs "Count is 0, wich is even"
+subscribe(
+  (t) => ({ count:$count.get(t), even:$isEven.get(t)}),
+  (data) => {
+    console.log(`Count is ${data.count}, which is ${data.even ? 'even' : 'odd'}`)
+  }
+)
+// Logs "Count is 0, which is even"
 
 // Update the state
 $count.set(1) // Logs: "Count is 1, which is odd"
@@ -96,9 +97,11 @@ $count.set(3) // Logs: "Count is 3, which is odd"
 
 1. **State** (`$count`) - Holds a mutable value
 2. **Derivation** (`$isEven`) - Computes a value based on state
-3. **Effect** - Runs automatically when dependencies change
-4. **`.get(t)`** - Reads a value AND creates a dependency
-5. **`.set()`** - Updates state, triggering effects
+3. **Subscribe** - Creates an effect that runs automatically when dependencies change
+4. **Data function** `(t) => ...` - Tracks dependencies and returns data
+5. **Callback** `(data) => ...` - Performs side effects with the data
+6. **`.get(t)`** - Reads a value AND creates a dependency
+7. **`.set()`** - Updates state, triggering subscribers
 
 ### Data Flow
 
@@ -109,26 +112,28 @@ sequenceDiagram
     participant User
     participant $count
     participant $isEven
-    participant Effect
+    participant Subscribe
     
     User->>$count: set(1)
     activate $count
-    Note over $count: Updates value<br/>0 → 1
+    Note over $count: Updates value 0 → 1
     $count->>$isEven: notify()
-    Note over $isEven: Marks as dirty<br/>(lazy recompute)
-    $count->>Effect: notify()
+    Note over $isEven: Marks as dirty (lazy recompute)
+    $count->>Subscribe: notify()
     deactivate $count
     
-    activate Effect
-    Effect->>$count: get(t)
-    $count-->>Effect: 1
-    Effect->>$isEven: get(t)
+    activate Subscribe
+    Note over Subscribe: Execute data function
+    Subscribe->>$count: get(t)
+    $count-->>Subscribe: 1
+    Subscribe->>$isEven: get(t)
     activate $isEven
     Note over $isEven: Recomputes because dirty
     $isEven->>$count: get(t)
     $count-->>$isEven: 1
-    $isEven-->>Effect: false
+    $isEven-->>Subscribe: false
     deactivate $isEven
-    Note over Effect: Logs: "Count is 1,<br/>which is odd"
-    deactivate Effect
+    Note over Subscribe: Call callback with {count: 1, even: false}
+    Note over Subscribe: Logs: "Count is 1, which is odd"
+    deactivate Subscribe
 ```

package/docs/guide/introduction/lifecycle.md

@@ -10,7 +10,7 @@ Throughout this guide, we'll use this simple but complete example:
 const $a = state(1)
 const $b = state(2)
 const $c = derivation((t) => $a.get(t) + $b.get(t))
-effect((t) => console.log('C =', $c.get(t)))
+$c.subscribe((c) => console.log('C =', c))
 ```
 
 This example demonstrates:
@@ -39,22 +39,21 @@ When you run the example code, here's the exact sequence of events:
 3. **`derivation(...)` creates `$c`**
    - A new `FlowDerivation` instance is created
    - The compute function is stored but **NOT executed** (lazy evaluation)
-   - A `TrackingContext` is created for the derivation
+   - A `FlowTracker` will be created when the derivation is first accessed
    - Still no computed value yet
 
-4. **`effect(...)` creates the effect**
+4. **`$c.subscribe(...)` creates the effect**
    - A new `FlowEffect` instance is created
-   - A `TrackingContext` is created for the effect
    - **The effect executes immediately** (not lazy!)
    - During execution:
-     - Effect calls `$c.get(t)`
+     - The subscribe method internally calls `$c.get(t)` with a `FlowTracker`
      - This triggers `$c` to initialize (first access)
-     - `$c` runs its compute function with its tracking context
+     - `$c` creates its own `FlowTracker` and runs its compute function
      - Compute calls `$a.get(t)` → returns `1`, registers `$a` as dependency of `$c`
      - Compute calls `$b.get(t)` → returns `2`, registers `$b` as dependency of `$c`
      - Compute returns `3`
-     - Effect's `$c.get(t)` returns `3`, registers `$c` as dependency of effect
-   - Effect logs: `"C = 3"`
+     - The value `3` is registered as a dependency of the effect
+   - Callback is called with `3` and logs: `"C = 3"`
 
 ### Creation Sequence Diagram
 
@@ -82,7 +81,7 @@ sequenceDiagram
     Note over $c: Store compute fn<br/>NOT executed yet<br/>(lazy)
     deactivate $c
     
-    User->>Effect: effect((t) => ...)
+    User->>Effect: $c.subscribe(...)
     activate Effect
     Note over Effect: Create & execute<br/>immediately
     
@@ -333,14 +332,12 @@ const $expensive = derivation((t) => {
   return expensiveCalculation($data.get(t))
 })
 
-const fx = effect((t) => {
-  if (shouldDisplay) {
-    display($expensive.get(t)) // Only computes when accessed
-  }
+const effect = $expensive.subscribe((value) => {
+  if (shouldDisplay) display(value)
 })
 
 // When not needed, just dispose the effect
-fx.dispose() // $expensive stops computing
+effect.dispose() // $expensive stops computing
 ```
 
 ### 2. Debug Dependency Issues
@@ -348,12 +345,12 @@ fx.dispose() // $expensive stops computing
 ```typescript
 // If logs don't appear, check:
 // 1. Is the effect created? (runs immediately)
-// 2. Are you using .get(t)? (not .pick())
+// 2. Are you using .subscribe()? (not .pick())
 // 3. Is anything disposed?
 
-effect((t) => {
+$state.subscribe((value) => {
   console.log('Effect created') // Should log immediately
-  console.log('Value:', $state.get(t)) // Creates dependency
+  console.log('Value:', value)
 })
 ```
 
@@ -363,8 +360,8 @@ effect((t) => {
 // Always dispose effects when done
 const disposables: FlowDisposable[] = []
 
-disposables.push(effect((t) => { /* ... */ }))
-disposables.push(effect((t) => { /* ... */ }))
+disposables.push(subscribe((t) => { /* ... */ }, () => { /* ... */ }))
+disposables.push(subscribe((t) => { /* ... */ }, () => { /* ... */ }))
 
 // Clean up
 disposables.forEach(d => d.dispose())