@ersbeth/picoflow 0.2.4 → 1.0.1

package/docs/guide/advanced/upgrading.md

@@ -0,0 +1,464 @@
+# Upgrading from v0.x
+
+PicoFlow v1.0.0 introduces a new API based on an explicit tracking context instead of getter and watcher functions. This change brings several benefits:
+
+1. **More intuitive:** The method-based API (`$state.get(t)`) is more natural than `get($state)`
+2. **Better chaining:** Nested access is much more readable: `$a.get(t).b.get(t)` vs `get(get($a).b)`
+3. **Explicit control:** Clear distinction between reactive (`.get(t)`) and non-reactive (`.pick()`) reads
+4. **Simpler architecture:** Fewer internal abstractions make the library easier to understand and maintain
+5. **More flexible:** Fine-grained control over dependencies within a single effect
+
+We believe this change makes PicoFlow better for both new and experienced users, and we're excited for you to try it!
+
+## Quick Start
+
+The core change is simple:
+
+**Before (v0.x):**
+```typescript
+effect((get, watch) => {
+    const value = get($state);
+    watch($signal);
+});
+```
+
+**After (v1.0.0):**
+```typescript
+effect((t) => {
+    const value = $state.get(t);
+    $signal.watch(t);
+});
+```
+
+## Breaking Changes Summary
+
+| v0.x | v1.0.0 | Notes |
+|------|--------|-------|
+| `effect((get, watch) => {})` | `effect((t) => {})` | Single tracking context parameter |
+| `derivation((get, watch) => {})` | `derivation((t) => {})` | Single tracking context parameter |
+| `get($observable)` | `$observable.get(t)` | Method-based API |
+| `watch($signal)` | `$signal.watch(t)` | Method-based API |
+| `FlowGetter` type | `TrackingContext` type | New type for tracking context |
+| `FlowWatcher` type | `TrackingContext` type | New type for tracking context |
+| N/A | `$observable.pick()` | New: non-reactive reads |
+
+## TypeScript Type Changes
+
+If you've imported these types, update them:
+
+**Before:**
+```typescript
+import type { FlowGetter, FlowWatcher } from '@ersbeth/picoflow';
+
+function myHelper(get: FlowGetter, watch: FlowWatcher) {
+    // ...
+}
+```
+
+**After:**
+```typescript
+import type { TrackingContext } from '@ersbeth/picoflow';
+
+function myHelper(t: TrackingContext) {
+    // ...
+}
+```
+
+## Step-by-Step Migration
+
+### 1. Update PicoFlow
+
+```bash
+npm install @ersbeth/picoflow@1.0.0
+```
+
+### 2. Replace Effect and Derivation Parameters
+
+Find all `effect()` and `derivation()` calls in your codebase:
+
+**Pattern to find:** `(get, watch) =>` or `(get) =>`  
+**Replace with:** `(t) =>`
+
+### 3. Update Observable Reads
+
+Replace getter function calls with method calls:
+
+**Pattern to find:** `get($observable)`  
+**Replace with:** `$observable.get(t)`
+
+### 4. Update Signal Watches
+
+Replace watcher function calls with method calls:
+
+**Pattern to find:** `watch($signal)`  
+**Replace with:** `$signal.watch(t)`
+
+### 5. Test Your Application
+
+Run your tests and verify everything works as expected.
+
+## Common Migration Patterns
+
+### Pattern 1: Simple Effect with State
+
+**Before:**
+```typescript
+import { state, effect } from '@ersbeth/picoflow';
+
+const $count = state(0);
+
+const $effect = effect((get) => {
+    console.log('Count:', get($count));
+});
+
+$count.set(42);
+```
+
+**After:**
+```typescript
+import { state, effect } from '@ersbeth/picoflow';
+
+const $count = state(0);
+
+const $effect = effect((t) => {
+    console.log('Count:', $count.get(t));
+});
+
+$count.set(42);
+```
+
+### Pattern 2: Effect with Signal Watch
+
+**Before:**
+```typescript
+import { signal, effect } from '@ersbeth/picoflow';
+
+const $signal = signal();
+
+const $effect = effect((get, watch) => {
+    watch($signal);
+    console.log('Signal triggered!');
+});
+
+$signal.trigger();
+```
+
+**After:**
+```typescript
+import { signal, effect } from '@ersbeth/picoflow';
+
+const $signal = signal();
+
+const $effect = effect((t) => {
+    $signal.watch(t);
+    console.log('Signal triggered!');
+});
+
+$signal.trigger();
+```
+
+### Pattern 3: Derivations
+
+**Before:**
+```typescript
+import { state, derivation } from '@ersbeth/picoflow';
+
+const $firstName = state('John');
+const $lastName = state('Doe');
+
+const $fullName = derivation((get) => {
+    return `${get($firstName)} ${get($lastName)}`;
+});
+```
+
+**After:**
+```typescript
+import { state, derivation } from '@ersbeth/picoflow';
+
+const $firstName = state('John');
+const $lastName = state('Doe');
+
+const $fullName = derivation((t) => {
+    return `${$firstName.get(t)} ${$lastName.get(t)}`;
+});
+```
+
+### Pattern 4: Nested States (Chained Access)
+
+This is where the new API really shines!
+
+**Before:**
+```typescript
+const $user = state({
+    profile: $profile,
+    settings: $settings
+});
+
+effect((get) => {
+    const name = get(get($user).profile).name;
+    console.log(name);
+});
+```
+
+**After:**
+```typescript
+const $user = state({
+    profile: $profile,
+    settings: $settings
+});
+
+effect((t) => {
+    const name = $user.get(t).profile.get(t).name;
+    console.log(name);
+});
+```
+
+Much more readable!
+
+### Pattern 5: Non-Reactive Reads (NEW CAPABILITY!)
+
+v1.0.0 introduces `pick()` for reading values without creating dependencies:
+
+```typescript
+const $data = state({ count: 0 });
+const $trigger = signal();
+
+effect((t) => {
+    // Only react to $trigger, not to $data
+    $trigger.watch(t);
+    const snapshot = $data.pick();  // Non-reactive read!
+    console.log('Triggered, current data:', snapshot);
+});
+```
+
+You can also use `get(null)` for the same effect:
+```typescript
+const snapshot = $data.get(null);  // Equivalent to pick()
+```
+
+### Pattern 6: Arrays and Collections
+
+**Before:**
+```typescript
+import { array, effect } from '@ersbeth/picoflow';
+
+const $items = array([1, 2, 3]);
+
+effect((get) => {
+    const items = get($items);
+    console.log('Items:', items);
+});
+
+$items.push(4);
+```
+
+**After:**
+```typescript
+import { array, effect } from '@ersbeth/picoflow';
+
+const $items = array([1, 2, 3]);
+
+effect((t) => {
+    const items = $items.get(t);
+    console.log('Items:', items);
+});
+
+$items.push(4);
+```
+
+### Pattern 7: Reactive Maps
+
+**Before:**
+```typescript
+import { map, effect } from '@ersbeth/picoflow';
+
+const $map = map({ foo: 'bar' });
+
+effect((get) => {
+    const data = get($map);
+    console.log('Map:', data);
+});
+
+$map.setAt('key', 'value');
+```
+
+**After:**
+```typescript
+import { map, effect } from '@ersbeth/picoflow';
+
+const $map = map({ foo: 'bar' });
+
+effect((t) => {
+    const data = $map.get(t);
+    console.log('Map:', data);
+});
+
+$map.setAt('key', 'value');
+```
+
+### Pattern 8: Async Resources
+
+**Before:**
+```typescript
+import { resource, effect } from '@ersbeth/picoflow';
+
+const $data = resource(fetchData, {});
+
+effect((get) => {
+    const data = get($data);
+    console.log('Data loaded:', data);
+});
+```
+
+**After:**
+```typescript
+import { resource, effect } from '@ersbeth/picoflow';
+
+const $data = resource(fetchData, {});
+
+effect((t) => {
+    const data = $data.get(t);
+    console.log('Data loaded:', data);
+});
+```
+
+### Pattern 9: Streams
+
+**Before:**
+```typescript
+import { stream, effect } from '@ersbeth/picoflow';
+
+const $messages = stream((set) => {
+    const ws = new WebSocket('ws://...');
+    ws.onmessage = (e) => set(e.data);
+    return () => ws.close();
+});
+
+effect((get) => {
+    console.log('Message:', get($messages));
+});
+```
+
+**After:**
+```typescript
+import { stream, effect } from '@ersbeth/picoflow';
+
+const $messages = stream((set) => {
+    const ws = new WebSocket('ws://...');
+    ws.onmessage = (e) => set(e.data);
+    return () => ws.close();
+});
+
+effect((t) => {
+    console.log('Message:', $messages.get(t));
+});
+```
+
+### Pattern 10: SolidJS Integration
+
+If you're using `picoflow/solid`:
+
+**Before:**
+```typescript
+import { from } from '@ersbeth/picoflow/solid';
+import { state } from '@ersbeth/picoflow';
+
+const $picoState = state(42);
+
+// Convert to SolidJS signal
+const solidSignal = from($picoState);
+
+// Or with a getter function
+const solidDerived = from((get) => {
+    return get($stateA) + get($stateB);
+});
+```
+
+**After:**
+```typescript
+import { from } from '@ersbeth/picoflow/solid';
+import { state } from '@ersbeth/picoflow';
+
+const $picoState = state(42);
+
+// Convert to SolidJS signal
+const solidSignal = from($picoState);
+
+// Or with a getter function
+const solidDerived = from((t) => {
+    return $stateA.get(t) + $stateB.get(t);
+});
+```
+
+## Advanced: Mixed Reactive and Non-Reactive Reads
+
+One powerful new feature is the ability to mix reactive and non-reactive reads in the same effect:
+
+```typescript
+const $config = state({ debug: true });
+const $data = state({ value: 0 });
+
+effect((t) => {
+    // Reactive: effect re-runs when $data changes
+    const data = $data.get(t);
+    
+    // Non-reactive: effect does NOT re-run when $config changes
+    const config = $config.pick();
+    
+    if (config.debug) {
+        console.log('Debug:', data);
+    }
+});
+
+// This triggers the effect:
+$data.set({ value: 1 });
+
+// This does NOT trigger the effect:
+$config.set({ debug: false });
+```
+
+This is useful for:
+- Reading configuration that rarely changes
+- Accessing reference data without creating dependencies
+- Performance optimization by avoiding unnecessary re-runs
+
+## Troubleshooting
+
+### Error: "Cannot read property 'get' of undefined"
+
+Make sure you're passing the tracking context to the `get()` method:
+
+```typescript
+// ❌ Wrong
+effect((t) => {
+    const value = $state.get();  // Missing parameter
+});
+
+// ✅ Correct
+effect((t) => {
+    const value = $state.get(t);
+});
+```
+
+### Error: "watch is not a function"
+
+You're trying to use the old API. Update to the new method-based syntax:
+
+```typescript
+// ❌ Wrong (old API)
+effect((get, watch) => {
+    watch($signal);
+});
+
+// ✅ Correct (new API)
+effect((t) => {
+    $signal.watch(t);
+});
+```
+
+### My effect runs too often / too rarely
+
+Check if you're using `.get(t)` vs `.pick()` correctly:
+- Use `.get(t)` to create a reactive dependency
+- Use `.pick()` or `.get(null)` for snapshot reads without dependencies
+

package/docs/guide/introduction/concepts.md

@@ -0,0 +1,56 @@
+# Concepts
+
+Understand the fundamentals of reactive programming and how it simplifies managing your application's state and behavior.
+
+## What is Reactive Programming?
+
+Imagine a **spreadsheet** where you write `=A1 + B1` in cell C1. When you change A1 or B1, C1 automatically updates. That's reactive programming - values that automatically update when their dependencies change.
+
+## Imperative Approach
+
+In traditional programming, you manually update everything:
+
+```typescript
+// Imperative approach
+let count = 0
+let doubledCount = count * 2
+
+function increment() {
+  count++
+  doubledCount = count * 2 // Must remember to update!
+  updateUI(count, doubledCount) // Must remember to update UI!
+}
+```
+
+
+```mermaid
+flowchart LR
+    A[count = 5] --> B[Manually update doubled]
+    B --> C[Manually update UI]
+```
+
+## Reactive Approach
+
+With reactive programming, dependencies update automatically:
+
+```typescript
+// Reactive approach with PicoFlow
+const $count = state(0)
+const $doubled = derivation((t) => $count.get(t) * 2)
+
+effect((t) => {
+  updateUI($count.get(t), $doubled.get(t)) // Runs automatically!
+})
+
+function increment() {
+  $count.set(n => n + 1) // Everything else updates automatically!
+}
+```
+
+```mermaid
+flowchart LR
+    A2[$count.set 5] --> C2[$doubled updates]
+    C2 --> D2[UI effect runs]
+```
+
+**The benefit:** You define relationships once, and they stay synchronized automatically!

package/docs/guide/introduction/conventions.md

@@ -0,0 +1,61 @@
+# 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 
+
+You'll see variables prefixed with `$` throughout PicoFlow examples:
+
+```typescript
+const $count = state(0)
+const $double = derivation((t) => $count.get(t) * 2)
+```
+
+This is a **naming convention** to make reactive values stand out. It helps you quickly identify:
+- Which values are reactive
+- Which values will cause re-executions when changed
+- Where your state lives
+
+Think of `$` as a visual marker: "This value is special - it's reactive!"
+
+### Examples
+
+```typescript
+// Reactive values - use $ prefix
+const $userName = state('Alice')
+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 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

@@ -0,0 +1,134 @@
+# Getting Started
+
+Welcome to PicoFlow! This guide will help you install PicoFlow and build your first reactive application in just a few minutes.
+
+## Why PicoFlow?
+
+PicoFlow is a lightweight reactive library with a focus on **explicit control** and **simplicity**. Unlike some reactive libraries that track everything automatically, PicoFlow gives you precise control over what is reactive and what isn't.
+
+### Key Philosophy
+
+1. **Explicit Tracking** - You decide what to track with `.get(t)`
+2. **Fine-grained Control** - React to specific operations, not just "something changed"
+3. **No Magic** - Simple, predictable behavior
+4. **TypeScript First** - Full type safety and inference
+
+## Installation
+
+Install PicoFlow using your preferred package manager:
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @ersbeth/picoflow
+```
+
+```bash [npm]
+npm install @ersbeth/picoflow
+```
+
+```bash [yarn]
+yarn add @ersbeth/picoflow
+```
+
+:::
+
+If you plan to use the SolidJS integration, install SolidJS as a peer dependency:
+
+::: code-group
+
+```bash [pnpm]
+pnpm add solid-js
+```
+
+```bash [npm]
+npm install solid-js
+```
+
+```bash [yarn]
+yarn add solid-js
+```
+
+:::
+
+Import the primitives you need:
+
+```typescript
+import { state, effect, derivation, signal } from '@ersbeth/picoflow'
+```
+
+For SolidJS integration:
+
+```typescript
+import { from } from '@ersbeth/picoflow/solid'
+```
+
+## Your First PicoFlow App
+
+Let's build a simple counter with PicoFlow:
+
+```typescript
+import { state, derivation, effect } from '@ersbeth/picoflow'
+
+// Create reactive state (prefix with $ by convention)
+const $count = state(0)
+
+// Create a computed value
+const $isEven = derivation((t) => {
+  return $count.get(t) % 2 === 0
+})
+
+// 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"
+
+// Update the state
+$count.set(1) // Logs: "Count is 1, which is odd"
+$count.set(2) // Logs: "Count is 2, which is even"
+$count.set(3) // Logs: "Count is 3, which is odd"
+```
+
+### What Just Happened?
+
+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
+
+### Data Flow
+
+Here's what happens when you call `$count.set(1)`:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant $count
+    participant $isEven
+    participant Effect
+    
+    User->>$count: set(1)
+    activate $count
+    Note over $count: Updates value<br/>0 → 1
+    $count->>$isEven: notify()
+    Note over $isEven: Marks as dirty<br/>(lazy recompute)
+    $count->>Effect: notify()
+    deactivate $count
+    
+    activate Effect
+    Effect->>$count: get(t)
+    $count-->>Effect: 1
+    Effect->>$isEven: get(t)
+    activate $isEven
+    Note over $isEven: Recomputes because dirty
+    $isEven->>$count: get(t)
+    $count-->>$isEven: 1
+    $isEven-->>Effect: false
+    deactivate $isEven
+    Note over Effect: Logs: "Count is 1,<br/>which is odd"
+    deactivate Effect
+```