@ersbeth/picoflow 2.0.2 → 2.0.3

package/docs/guide/primitives/overview.md

@@ -1,92 +0,0 @@
-# Primitives Overview
-
-PicoFlow distinguishes between two main concepts:
-- **Primitives**: Reactive values (state, derivation, signal, collections)
-- **Side Effects**: Created by subscribing to primitives 
-
-::: tip
-Looking for naming conventions? Check out the **[Conventions](/guide/introduction/conventions)** guide to learn about the `$` prefix.
-:::
-
-## Primitives
-
-PicoFlow provides several reactive primitives, each with specific capabilities. Primitive may exist in synchrone and asynchrone flavours.
-
-| Primitive | Sync | Async | Purpose |
-|-----------|:----:|:-----:|---------|
-| **Signal** | ✓ | - | Event notifications without values |
-| **State** | ✓ | ✓ | Mutable reactive values |
-| **Constant** | ✓ | ✓ | Immutable reactive values |
-| **Derivation** | ✓ | ✓ | Computed values from dependencies |
-| **Writable Derivation** | ✓ | ✓ | Derivations with custom setters |
-| **Array** | ✓ | - | Reactive lists with fine-grained tracking |
-| **Map** | ✓ | - | Reactive dictionaries with fine-grained tracking |
-
-## Side Effects
-
-You may subscribe to any primitive to perform side effects on change. When you subscribe, you get a `FlowEffect` that can be disposed.
-
-
-When reacting to a single primitive, use the `.subscribe()` method:
-
-```typescript
-const effect = $count.subscribe((value) => {
-  console.log('Count is:', value)
-})
-
-// Later: dispose the effect
-effect.dispose()
-```
-
-
-When combining multiple primitives, use the `subscribe()` function:
-
-```typescript
-const effect = subscribe(
-  (t) => ({ count: $count.get(t), name: $name.get(t) }),
-  (data) => {
-    console.log('Count:', data.count, 'Name:', data.name)
-  }
-)
-```
-
-### Use cases
-
-- Logging and debugging
-- DOM manipulation
-- API calls and data persistence
-- Analytics and tracking
-- Side effects that don't produce values
-
-### Key features
-
-- **Eager execution**: Runs immediately when created
-- **Automatic re-execution**: Runs whenever dependencies change
-- **Returns FlowEffect**: Can be disposed to stop the effect
-- **Error handling**: Optional `onError` and `onPending` callbacks
-
-## Derivations vs Side Effects
-
-What's the difference between a derivation and a side effect? Both react to changes, but they serve different purposes:
-
-| Feature | Derivation | Side Effect (subscribe) |
-|---------|-----------|---------|
-| Purpose | **Compute a value** | **Perform side effects** |
-| Returns | A reactive value | FlowEffect (disposable) |
-| Should be pure? | ✅ Yes | ❌ No |
-| Side effects allowed? | ❌ No | ✅ Yes |
-| When it runs | Lazily (when accessed) | Immediately and on changes |
-| How to create | `derivation()` | `subscribe()` or `.subscribe()` |
-| Use case | Calculate totals, filter lists | Update DOM, save data, log |
-
-```mermaid
-flowchart LR
-    A[Reactive Values] --> B[Derivation]
-    A --> C[Effect]
-    B --> D[New Computed Value]
-    C --> E[Side Effects<br/>DOM, API, Storage]
-    D -.-> F[Can be used by<br/>other derivations]
-    D -.-> G[Can be used by<br/>effects]
-```
-
-**Key insight:** Use derivations for **calculations**, use effects for **actions**.

package/docs/guide/primitives/signal.md

@@ -1,222 +0,0 @@
-# Signals
-
-A **signal** is a reactive primitive that represents an event or notification. Unlike state or derivations, signals don't hold values - they simply notify watchers that something has happened.
-
-## When to Use Signals
-
-Use signals when you need to:
-
-- ✅ Trigger manual refreshes or updates
-- ✅ Coordinate actions between independent parts of your app
-- ✅ Signal that an event has occurred without sending data
-- ✅ Create synchronization points in reactive flows
-
-Don't use signals when:
-
-- ❌ You need to pass data (use state instead)
-
-## Creating Signals
-
-Creating a signal is straightforward:
-
-```typescript
-import { signal } from '@ersbeth/picoflow'
-
-const $refreshTrigger = signal()
-const $saveComplete = signal()
-const $userLoggedOut = signal()
-```
-
-Signals don't take any parameters since they don't hold values.
-
-## Using Signals
-
-Signals have three main operations: watching, triggering, and disposing.
-
-### Watch
-
-Inside a subscription or derivation, use `.watch(t)` to track a signal:
-
-```typescript
-import { signal, subscribe } from '@ersbeth/picoflow'
-
-const $refresh = signal()
-
-subscribe(
-  (t) => { $refresh.watch(t) },
-  () => { console.log('Refresh triggered!') }
-)
-
-$refresh.trigger() // Logs: "Refresh triggered!"
-$refresh.trigger() // Logs: "Refresh triggered!" again
-```
-
-Every time the signal is triggered, the subscription re-executes.
-
-### Trigger
-
-Call `.trigger()` to notify all watchers:
-
-```typescript
-const $notification = signal()
-
-// Setup a subscription that watches the signal
-subscribe(
-  (t) => { $notification.watch(t) },
-  () => { showNotification('New activity!') }
-)
-
-// Trigger from anywhere
-function onNewMessage() {
-  $notification.trigger()
-}
-
-function onNewLike() {
-  $notification.trigger()
-}
-```
-
-### Dispose
-
-Signals can be disposed to free resources and prevent memory leaks:
-
-```typescript
-const $mySignal = signal()
-
-// Use the signal
-subscribe(
-  (t) => { $mySignal.watch(t) },
-  () => { console.log('Signal triggered!') }
-)
-
-// Later, clean up
-$mySignal.dispose()
-
-// Subsequent operations will throw
-$mySignal.trigger() // Error: Primitive is disposed
-```
-
-## Lifecyle
-
-When you create a subscription that watches a signal:
-
-1. **Registration**: The signal registers the subscription as a watcher
-2. **Waiting**: The signal waits for `.trigger()` to be called
-3. **Notification**: When triggered, all watching subscriptions are scheduled to run
-4. **Re-execution**: Each watching subscription re-executes its function
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Signal as $refresh (Signal)
-    participant Subscription
-    
-    Note over User,Subscription: 1. Setup Phase
-    User->>Subscription: Create subscription
-    activate Subscription
-    Subscription->>Signal: watch(t)
-    Note over Signal: Register Subscription as watcher
-    Signal-->>Subscription: Registered
-    Subscription->>Subscription: Execute function
-    Note over Subscription: Log: "Ready to refresh"
-    deactivate Subscription
-    
-    Note over User,Subscription: 2. Trigger Phase
-    User->>Signal: trigger()
-    activate Signal
-    Note over Signal: Notify all watchers
-    Signal->>Subscription: Schedule execution
-    deactivate Signal
-    
-    activate Subscription
-    Note over Subscription: Re-execute function
-    Subscription->>Subscription: Perform refresh
-    Note over Subscription: Log: "Refreshing..."
-    deactivate Subscription
-```
-
-## Best Practices
-
-### Name Signals Clearly
-
-Use names that describe the event, not the action:
-
-```typescript
-// ✅ Good - describes the event
-const $refreshRequested = signal()
-const $saveComplete = signal()
-const $validationFailed = signal()
-
-// ❌ Bad - describes the handler
-const $doRefresh = signal()
-const $handleSave = signal()
-```
-
-## Common Pitfalls
-
-### Using Signals When State Would Be Better
-
-**Problem**: Using a signal when you actually need to track a value.
-
-```typescript
-// ❌ Bad - should use state
-const $userUpdated = signal()
-let currentUser: User | null = null
-
-subscribe(
-  (t) => {
-    $userUpdated.watch(t)
-    return currentUser
-  },
-  (user) => {
-    if (user) {
-      renderUser(user)
-    }
-  }
-)
-
-function setUser(user: User) {
-  currentUser = user
-  $userUpdated.trigger()
-}
-```
-
-**Solution**: Use state to hold the value:
-
-```typescript
-// ✅ Good - state holds the value
-const $currentUser = state<User | null>(null)
-
-$currentUser.subscribe((user) => {
-  if (user) {
-    renderUser(user)
-  }
-})
-
-function setUser(user: User) {
-  $currentUser.set(user)
-}
-```
-
-### Over-Triggering
-
-**Problem**: Triggering a signal in a loop or too frequently.
-
-```typescript
-// ❌ Bad - triggers in a loop
-for (let i = 0; i < 100; i++) {
-  processItem(i)
-  $itemProcessed.trigger() // 100 triggers!
-}
-```
-
-**Solution**: Trigger once after the batch:
-
-```typescript
-// ✅ Good - single trigger after batch
-for (let i = 0; i < 100; i++) {
-  processItem(i)
-}
-$batchProcessed.trigger() // 1 trigger
-```
-

package/docs/guide/primitives/state.md

@@ -1,272 +0,0 @@
-# State
-
-**State** is a reactive primitive that holds a mutable value. 
-
-### Key Characteristics
-
-- **Mutable**: Can be updated with `.set()`
-- **Reactive**: Automatically notifies watchers on changes
-- **Equality checking**: Only notifies if the new value differs from the current value
-
-## When to Use State
-
-Use state when you need to:
-
-- ✅ Track values that change over time
-
-Don't use state when:
-
-- ❌ The value never changes (use constants instead)
-- ❌ The value is derived from other reactive values (use derivations instead)
-- ❌ You're tracking events without data (use signals instead)
-
-## Creating State
-
-Creating state is straightforward:
-
-```typescript
-import { state } from '@ersbeth/picoflow'
-
-const $count = state(0)
-const $name = state('Alice')
-const $user = state({ id: 1, name: 'Bob', age: 25 })
-const $items = state<string[]>([])
-```
-
-The value you pass becomes the initial value. It can be any type: numbers, strings, objects, arrays, etc.
-
-## Using State
-
-State provides methods for reading, updating, and disposing.
-
-### Get
-
-Inside a subscription or derivation, use `.get(t)` to read the value and create a dependency:
-
-```typescript
-const $count = state(0)
-const $double = derivation((t) => $count.get(t) * 2)
-
-$double.subscribe((value) => {
-  console.log('Double is:', value)
-})
-
-$count.set(1) // Console logs: "Double is: 2"
-$count.set(2) // Console logs: "Double is: 4"
-```
-
-### Pick
-
-Use `.pick()` when you want the current value without creating a dependency:
-
-```typescript
-const $count = state(0)
-
-// Read without tracking (e.g., outside a subscription)
-const currentValue = await $count.pick()
-console.log(currentValue) // 0
-```
-
-### Update
-
-Pass the new value directly to `.set()`:
-
-```typescript
-const $count = state(0)
-
-$count.set(5)   // Set to 5
-$count.set(10)  // Set to 10
-```
-
-Pass a function that receives the current value and returns the new value:
-
-```typescript
-const $count = state(0)
-
-$count.set(n => n + 1)  // Increment by 1
-$count.set(n => n * 2)  // Double the value
-$count.set(n => Math.max(0, n - 1)) // Decrement, min 0
-```
-
-**When to use updater functions:**
-- When the new value depends on the current value
-- To guarantee you're working with the latest value
-- For atomic updates (important in concurrent scenarios)
-
-### Dispose
-
-State can be disposed to free resources and prevent memory leaks:
-
-```typescript
-const $count = state(0)
-
-// Use the state
-$count.subscribe((value) => {
-  console.log(value)
-})
-
-// Later, clean up
-$count.dispose()
-
-// Subsequent operations will throw
-$count.set(5) // Error: Primitive is disposed
-```
-
-## Lifecycle
-
-When you update state, a specific flow occurs to ensure efficiency and consistency.
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant $count as $count (State)
-    participant $double as $double (Derivation)
-    participant Subscription
-    
-    User->>$count: set(n => n + 1)
-    activate $count
-    Note over $count: Get current: 0<br/>Compute new: 0 + 1 = 1
-    Note over $count: Check: 1 !== 0 ✓
-    Note over $count: Update: 0 → 1
-    
-    $count->>$double: Notify (mark dirty)
-    activate $double
-    Note over $double: Mark as dirty<br/>NO recompute yet
-    deactivate $double
-    
-    $count->>Subscription: Schedule execution
-    deactivate $count
-    
-    activate Subscription
-    Note over Subscription: Execute function
-    
-    Subscription->>$count: get(t)
-    activate $count
-    $count-->>Subscription: 1
-    deactivate $count
-    
-    Subscription->>$double: get(t)
-    activate $double
-    Note over $double: Dirty? YES<br/>Recompute now
-    
-    $double->>$count: get(t)
-    activate $count
-    $count-->>$double: 1
-    deactivate $count
-    
-    Note over $double: Compute: 1 * 2 = 2
-    $double-->>Subscription: 2
-    deactivate $double
-    
-    Note over Subscription: Log: "Count: 1, Double: 2"
-    deactivate Subscription
-```
-
-**How it works:**
-
-1. **Compute new value**: If updater function, call it with current value
-2. **Equality check**: Compare new value with current using `===`
-3. **Early return**: If equal, skip notification entirely
-4. **Update value**: Store the new value
-5. **Notify dependents**: 
-   - Derivations are marked dirty (not recomputed yet)
-   - Subscriptions are scheduled for execution
-6. **Pull-based recompute**: When subscriptions run and read derivations, they recompute
-
-### Equality Check Example
-
-State only notifies when the value actually changes:
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant $count as $count (State)
-    participant Subscription
-    
-    Note over User,Subscription: Initial state: $count = 5
-    
-    User->>$count: set(5)
-    activate $count
-    Note over $count: Check: 5 === 5?<br/>YES - no change
-    Note over $count: Skip notification
-    deactivate $count
-    Note over Subscription: Subscription does NOT run
-    
-    User->>$count: set(10)
-    activate $count
-    Note over $count: Check: 10 === 5?<br/>NO - value changed
-    Note over $count: Update: 5 → 10
-    $count->>Subscription: Notify & schedule
-    deactivate $count
-    
-    activate Subscription
-    Note over Subscription: Subscription runs
-    deactivate Subscription
-```
-
-## Best Practices
-
-### Use Updater Functions for Computed Updates
-
-Always use updater functions when the new value depends on the current value:
-
-```typescript
-// ❌ Bad - race condition risk
-const current = $count.pick()
-$count.set(current + 1)
-
-// ✅ Good - atomic update
-$count.set(n => n + 1)
-```
-
-### Immutable Updates for Objects
-
-Create new objects instead of mutating:
-
-```typescript
-// ❌ Bad - mutation
-$user.set(user => {
-  user.name = 'Bob' // Mutates the object!
-  return user
-})
-
-// ✅ Good - immutable
-$user.set(user => ({
-  ...user,
-  name: 'Bob'
-}))
-```
-
-### Granular State Over Large Objects
-
-Prefer multiple small state values when fields update independently:
-
-```typescript
-// ❌ Less efficient - entire object tracked
-const $form = state({
-  email: '',
-  password: '',
-  confirmPassword: ''
-})
-
-// ✅ More efficient - independent tracking
-const form = {
-  $email: state(''),
-  $password = state(''),
-  $confirmPassword = state(''),
-}
-```
-
-
-Use the `$` prefix for all reactive values:
-
-```typescript
-// ✅ Good - clear reactive naming
-const $count = state(0)
-const $user = state({...})
-const $isLoading = state(false)
-
-// ❌ Less clear
-const count = state(0)
-const user = state({...})
-```

package/docs/index.md

@@ -1,47 +0,0 @@
----
-layout: home
-
-hero:
-  name: PicoFlow
-  text: Lightweight Reactive Dataflow
-  tagline: Fine-grained reactive primitives for TypeScript with explicit dependency tracking
-  image:
-    src: /logo.svg
-    alt: PicoFlow
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /guide/introduction/getting-started
-    - theme: alt
-      text: API Reference
-      link: /api/
-    - theme: alt
-      text: View on GitLab
-      link: https://gitlab.com/ersbeth-web/picoflow
-
-features:
-  - icon: 🎯
-    title: Explicit Tracking
-    details: Full control over reactive dependencies with TrackingContext. Choose between reactive reads with get(t) and non-reactive reads with pick().
-  
-  - icon: ⚡
-    title: Lazy Evaluation
-    details: Derivations compute only when accessed, not on construction. Smart caching ensures computations run only when dependencies change.
-  
-  - icon: 🔧
-    title: Fine-grained Reactivity
-    details: Track specific operations on collections with reactive arrays and maps. Subscribe to additions, deletions, or entire collection changes.
-  
-  - icon: 🧹
-    title: Resource Management
-    details: Automatic cleanup with dispose patterns. Manage async resources, streams, and effects with confidence.
-  
-  - icon: 📦
-    title: Lightweight
-    details: Minimal bundle size with zero dependencies. Tree-shakeable exports ensure you only ship what you use.
-  
-  - icon: 🔄
-    title: SolidJS Integration
-    details: Seamless integration with SolidJS through built-in converters. Use PicoFlow primitives directly in Solid components.
----
-

package/docs/public/logo.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 640"><!--!Font Awesome Free v7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.--><path d="M176 120C189.3 120 200 130.7 200 144C200 157.3 189.3 168 176 168C162.7 168 152 157.3 152 144C152 130.7 162.7 120 176 120zM208.4 217.2C236.4 204.8 256 176.7 256 144C256 99.8 220.2 64 176 64C131.8 64 96 99.8 96 144C96 176.8 115.7 205 144 217.3L144 422.6C115.7 435 96 463.2 96 496C96 540.2 131.8 576 176 576C220.2 576 256 540.2 256 496C256 463.2 236.3 435 208 422.7L208 336.1C234.7 356.2 268 368.1 304 368.1L390.7 368.1C403 396.4 431.2 416.1 464 416.1C508.2 416.1 544 380.3 544 336.1C544 291.9 508.2 256.1 464 256.1C431.2 256.1 403 275.8 390.7 304.1L304 304C254.1 304 213 265.9 208.4 217.2zM176 472C189.3 472 200 482.7 200 496C200 509.3 189.3 520 176 520C162.7 520 152 509.3 152 496C152 482.7 162.7 472 176 472zM440 336C440 322.7 450.7 312 464 312C477.3 312 488 322.7 488 336C488 349.3 477.3 360 464 360C450.7 360 440 349.3 440 336z" fill="#5672cd"/></svg>

package/src/api/base/flowDisposable.ts

@@ -1,44 +0,0 @@
-/**
- * Contract for resources that can be explicitly released to prevent memory leaks.
- *
- * All reactive primitives in PicoFlow implement this interface, allowing manual cleanup of subscriptions
- * and dependencies. Once disposed, the resource cannot be reused and will throw errors on further access.
- * Call `dispose()` when you no longer need a reactive primitive to free its resources.
- *
- * @public
- */
-export interface FlowDisposable {
-    /**
-     * Indicates whether this resource has been disposed.
-     *
-     * Returns `true` if `dispose()` has been called, `false` otherwise. Once disposed,
-     * the resource is no longer usable and any operations on it will throw errors.
-     */
-    get disposed(): boolean;
-
-    /**
-     * Releases all resources held by this disposable object.
-     *
-     * Cleans up all subscriptions, dependencies, and internal state. After calling this method,
-     * the resource enters a disposed state and cannot be reused. Any subsequent operations will
-     * throw errors. This method should be called when you no longer need the reactive primitive
-     * to prevent memory leaks.
-     */
-    dispose(): void;
-}
-
-/**
- * Type guard to check if an object implements the FlowDisposable interface.
- *
- * Useful for conditionally disposing objects that may or may not be disposable,
- * such as when cleaning up mixed collections of values. Returns true if the object
- * has a `dispose` method, providing type-safe access to disposal functionality.
- *
- * @param obj - The object to check
- * @returns True if the object implements FlowDisposable, false otherwise
- *
- * @public
- */
-export function isDisposable(obj: unknown): obj is FlowDisposable {
-    return obj !== null && obj !== undefined && typeof (obj as FlowDisposable).dispose === "function";
-}

package/src/api/base/flowObservable.ts

@@ -1,28 +0,0 @@
-import type { FlowDisposable } from "./flowDisposable";
-import type { FlowSubscribable } from "./flowSubscribable";
-import type { FlowTracker } from "./flowTracker";
-
-/**
- * Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph.
- * @public
- */
-export interface FlowObservable<T> extends FlowDisposable, FlowSubscribable<T> {
-    /**
-     * Establishes a reactive dependency without reading the value.
-     *
-     * Registers this observable as a dependency of the given tracker, allowing it to be notified
-     * when changes occur. This enables dependency tracking without accessing the actual value.
-     *
-     * @param tracker - Tracker that records this observable as a dependency
-     */
-    watch(tracker: FlowTracker): void;
-
-    /**
-     * Manually triggers notifications to all dependents.
-     *
-     * Forces all dependents of this observable to be notified and re-executed, even if the
-     * value hasn't actually changed. Useful for imperatively triggering updates when the
-     * reactive system cannot detect changes automatically.
-     */
-    trigger(): void;
-}