@ersbeth/picoflow 2.0.2 → 2.1.0

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

@@ -1,464 +0,0 @@
-# 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/advanced/migration-v2.md

@@ -1,204 +0,0 @@
-# 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! 🚀