@ersbeth/picoflow 1.1.2 → 2.0.1

package/docs/api/functions/state.md

@@ -2,46 +2,66 @@
 
 # Function: state()
 
+## Call Signature
+
 ```ts
 function state<T>(value): FlowState<T>;
 ```
 
-Defined in: [creators.ts:98](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L98)
+Defined in: [api/nodes/sync/flowState.ts:41](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L41)
 
-Creates a new reactive state holding a mutable value.
+Creates a mutable reactive state that can be read and updated imperatively.
 
-## Type Parameters
+State can be initialized with a direct value or a lazy initializer function. Changes propagate
+automatically to all reactive computations that depend on this state. Use state for data that
+changes through user actions, external events, or application logic rather than derived computations.
 
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The type of the state value. |
+### Type Parameters
 
-## Parameters
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `value` | `T` \| () => `T` | The initial value for the state, or a function returning the initial value. |
+| `value` | [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | Initial value for the state, or lazy initializer function |
 
-## Returns
+### Returns
 
-[`FlowState`](/api/classes/FlowState.md)\<`T`\>
+[`FlowState`](/api/interfaces/FlowState.md)\<`T`\>
 
-A new instance of [FlowState](/api/classes/FlowState.md).
+A FlowState that can be read and modified
 
-## Remarks
+## Call Signature
 
-State is the most common reactive primitive - a mutable container that notifies dependents
-when its value changes. Use `set()` to update the value and `get(t)` or `pick()` to read it.
+```ts
+function state<T>(initializer): FlowState<T>;
+```
 
-## Example
+Defined in: [api/nodes/sync/flowState.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowState.ts#L42)
 
-```typescript
-const $count = state(0);
+Creates a mutable reactive state that can be read and updated imperatively.
 
-effect((t) => {
-  console.log($count.get(t));
-});
+State can be initialized with a direct value or a lazy initializer function. Changes propagate
+automatically to all reactive computations that depend on this state. Use state for data that
+changes through user actions, external events, or application logic rather than derived computations.
 
-$count.set(1); // Logs: 1
-$count.set(n => n + 1); // Logs: 2
-```
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `initializer` | [`InitFunction`](/api/type-aliases/InitFunction.md)\<`T`\> |
+
+### Returns
+
+[`FlowState`](/api/interfaces/FlowState.md)\<`T`\>
+
+A FlowState that can be read and modified

package/docs/api/functions/stateAsync.md

@@ -0,0 +1,69 @@
+[@ersbeth/picoflow](/api/index.md) / stateAsync
+
+# Function: stateAsync()
+
+## Call Signature
+
+```ts
+function stateAsync<T>(value): FlowStateAsync<T>;
+```
+
+Defined in: [api/nodes/async/flowStateAsync.ts:43](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowStateAsync.ts#L43)
+
+Creates a mutable async reactive state that resolves promises and can be updated imperatively.
+
+State can be initialized with a direct promise or a lazy async initializer function. Update the state by
+calling `set()` with a new promise or an async updater function. Changes propagate automatically to all
+reactive computations that depend on this state. Use for async data that changes through user actions or
+application logic, such as loading user profiles, fetching search results, or any async state updates.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `Promise`\<`T`\> | Initial promise to resolve, or lazy async initializer function |
+
+### Returns
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md)\<`T`\>
+
+A FlowStateAsync that can be read and modified with promises
+
+## Call Signature
+
+```ts
+function stateAsync<T>(initializer): FlowStateAsync<T>;
+```
+
+Defined in: [api/nodes/async/flowStateAsync.ts:44](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowStateAsync.ts#L44)
+
+Creates a mutable async reactive state that resolves promises and can be updated imperatively.
+
+State can be initialized with a direct promise or a lazy async initializer function. Update the state by
+calling `set()` with a new promise or an async updater function. Changes propagate automatically to all
+reactive computations that depend on this state. Use for async data that changes through user actions or
+application logic, such as loading user profiles, fetching search results, or any async state updates.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `initializer` | [`InitFunctionAsync`](/api/type-aliases/InitFunctionAsync.md)\<`T`\> |
+
+### Returns
+
+[`FlowStateAsync`](/api/interfaces/FlowStateAsync.md)\<`T`\>
+
+A FlowStateAsync that can be read and modified with promises

package/docs/api/functions/subscribe.md

@@ -0,0 +1,40 @@
+[@ersbeth/picoflow](/api/index.md) / subscribe
+
+# Function: subscribe()
+
+```ts
+function subscribe<T>(
+   data, 
+   onData, 
+   onError?, 
+   onPending?): FlowEffect;
+```
+
+Defined in: [api/nodes/flowEffect.ts:35](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowEffect.ts#L35)
+
+Creates a reactive effect that runs immediately and automatically re-runs when dependencies change.
+
+The effect function tracks any reactive values accessed and subscribes to their changes.
+When any tracked value changes, the effect re-executes with the new values.
+Optional callbacks handle errors and pending async states.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `data` | [`FlowDataTracker`](/api/type-aliases/FlowDataTracker.md)\<`T`\> | Function that accesses reactive dependencies and returns data |
+| `onData` | [`FlowOnDataListener`](/api/type-aliases/FlowOnDataListener.md)\<`T`\> | Callback invoked with the computed data on each execution |
+| `onError?` | [`FlowOnErrorListener`](/api/type-aliases/FlowOnErrorListener.md) | Optional callback for handling errors during execution |
+| `onPending?` | [`FlowOnPendingListener`](/api/type-aliases/FlowOnPendingListener.md) | Optional callback invoked when async dependencies are pending |
+
+## Returns
+
+[`FlowEffect`](/api/interfaces/FlowEffect.md)
+
+A FlowEffect handle with a `dispose()` method to stop the effect

package/docs/api/functions/writableDerivation.md

@@ -0,0 +1,33 @@
+[@ersbeth/picoflow](/api/index.md) / writableDerivation
+
+# Function: writableDerivation()
+
+```ts
+function writableDerivation<T>(compute): FlowWritableDerivation<T>;
+```
+
+Defined in: [api/nodes/sync/flowWritableDerivation.ts:29](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowWritableDerivation.ts#L29)
+
+Creates a derived value that recomputes automatically but can also be manually overridden.
+
+The compute function tracks dependencies and recomputes when they change, just like a regular derivation.
+However, you can also call `set()` to override the computed value. Use this for values that are normally
+derived but need occasional manual adjustments, such as editable calculated fields or user-correctable totals.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `compute` | [`DerivationFunction`](/api/type-aliases/DerivationFunction.md)\<`T`\> | Function that accesses dependencies and computes the derived value |
+
+## Returns
+
+[`FlowWritableDerivation`](/api/interfaces/FlowWritableDerivation.md)\<`T`\>
+
+A FlowWritableDerivation that provides both reactive computation and manual control

package/docs/api/functions/writableDerivationAsync.md

@@ -0,0 +1,34 @@
+[@ersbeth/picoflow](/api/index.md) / writableDerivationAsync
+
+# Function: writableDerivationAsync()
+
+```ts
+function writableDerivationAsync<T>(compute): FlowWritableDerivationAsync<T>;
+```
+
+Defined in: [api/nodes/async/flowWritableDerivationAsync.ts:31](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowWritableDerivationAsync.ts#L31)
+
+Creates an async derived value that recomputes automatically but can also be manually overridden.
+
+The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
+the function runs again and returns a new promise. However, you can also call `set()` to override the computed
+value with a new promise. Use for async values that are normally derived but need occasional manual adjustments,
+such as editable async calculated fields or user-correctable async totals.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `compute` | [`DerivationFunctionAsync`](/api/type-aliases/DerivationFunctionAsync.md)\<`T`\> | Async function that accesses dependencies and returns a promise of the derived value |
+
+## Returns
+
+[`FlowWritableDerivationAsync`](/api/interfaces/FlowWritableDerivationAsync.md)\<`T`\>
+
+A FlowWritableDerivationAsync that provides both reactive async computation and manual control

package/docs/api/index.md

@@ -1,118 +1,61 @@
 # @ersbeth/picoflow
 
-# PicoFlow
-
-PicoFlow is a lightweight reactive dataflow library that provides a comprehensive set of
-reactive primitives for building reactive applications with explicit dependency tracking.
-
-## Core Concepts
-
-**Reactive Primitives:**
-- [FlowSignal](/api/classes/FlowSignal.md): Event-like notifications without values
-- [FlowState](/api/classes/FlowState.md): Mutable reactive values
-- [FlowConstant](/api/classes/FlowConstant.md): Immutable reactive values (computed once)
-- [FlowDerivation](/api/classes/FlowDerivation.md): Computed values that track dependencies
-- [FlowEffect](/api/classes/FlowEffect.md): Side effects that run when dependencies change
-
-**Advanced Primitives:**
-- [FlowArray](/api/classes/FlowArray.md): Reactive arrays with mutation tracking
-- [FlowMap](/api/classes/FlowMap.md): Reactive maps with operation tracking
-- [FlowResource](/api/classes/FlowResource.md): Async data fetching returning `T | undefined`
-- [FlowResourceAsync](/api/classes/FlowResourceAsync.md): Async data fetching returning `Promise<T>`
-- [FlowStream](/api/classes/FlowStream.md): Event streams from external sources
-- [FlowStreamAsync](/api/classes/FlowStreamAsync.md): Async event streams returning Promises
-
-**Tracking Context:**
-- [TrackingContext](/api/classes/TrackingContext.md): The core mechanism for explicit dependency tracking
-- Use `observable.get(t)` to read with tracking
-- Use `observable.pick()` to read without tracking
-- Use `signal.watch(t)` to track signals without values
-
-## Key Features
-
-- **Explicit tracking**: Full control over what triggers re-execution via TrackingContext
-- **Lazy evaluation**: Derivations compute only when accessed
-- **Fine-grained reactivity**: Track specific operations on collections
-- **Resource management**: Automatic cleanup with dispose patterns
-- **SolidJS integration**: Seamless bridge to SolidJS primitives
-
-## Basic Usage
-
-```typescript
-import { state, effect, derivation } from 'picoflow';
-
-// Create reactive state
-const $count = state(0);
-
-// Create derived value
-const $double = derivation((t) => $count.get(t) * 2);
-
-// Create effect
-effect((t) => {
-  console.log('Count:', $count.get(t), 'Double:', $double.get(t));
-});
-
-// Update state
-$count.set(1); // Logs: "Count: 1 Double: 2"
-```
-
-## See
-
-[GitHub Repository](https://github.com/yourusername/picoflow)
-
-## Classes
-
-| Class | Description |
-| ------ | ------ |
-| [FlowArray](/api/classes/FlowArray.md) | Represents a reactive array. |
-| [FlowConstant](/api/classes/FlowConstant.md) | Represents a reactive and immutable constant value that can be computed lazily upon first access. |
-| [FlowDerivation](/api/classes/FlowDerivation.md) | Represents a reactive derivation whose value is computed based on other reactive signals. |
-| [FlowEffect](/api/classes/FlowEffect.md) | Represents a reactive effect that executes side-effect functions based on its tracked dependencies. |
-| [FlowMap](/api/classes/FlowMap.md) | Represents a reactive map that extends [FlowState](/api/classes/FlowState.md) for tracking key-value pairs. |
-| [FlowObservable](/api/classes/FlowObservable.md) | Represents a reactive observable that holds and tracks a value. |
-| [FlowResource](/api/classes/FlowResource.md) | Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`. |
-| [FlowResourceAsync](/api/classes/FlowResourceAsync.md) | Represents a reactive resource that asynchronously fetches its value and always returns a Promise. |
-| [FlowSignal](/api/classes/FlowSignal.md) | Represents a reactive signal. |
-| [FlowState](/api/classes/FlowState.md) | Represents a reactive state that holds a mutable value. |
-| [FlowStream](/api/classes/FlowStream.md) | Represents a reactive stream that updates its value based on an external updater function. |
-| [FlowStreamAsync](/api/classes/FlowStreamAsync.md) | Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function. |
-| [SolidDerivation](/api/classes/SolidDerivation.md) | Solid-style derivation wrapping SolidJS's createMemo, providing a computed reactive value. |
-| [SolidResource](/api/classes/SolidResource.md) | Solid-style resource wrapping SolidJS's createResource, providing async data loading with reactive state. |
-| [SolidState](/api/classes/SolidState.md) | Solid-style state container wrapping SolidJS's createSignal, providing a writable reactive signal. |
-| [TrackingContext](/api/classes/TrackingContext.md) | Represents a tracking context used to register dependencies during reactive computations. |
-
 ## Interfaces
 
 | Interface | Description |
 | ------ | ------ |
-| [FlowDisposable](/api/interfaces/FlowDisposable.md) | Represents an object with a disposable lifecycle that manages resources requiring cleanup. |
-| [SolidObservable](/api/interfaces/SolidObservable.md) | Interface for a Solid-style observable value. |
+| [FlowArray](/api/interfaces/FlowArray.md) | Reactive array with standard mutation methods and fine-grained change tracking. |
+| [FlowConstant](/api/interfaces/FlowConstant.md) | Read-only reactive value that computes once on initialization and never changes. |
+| [FlowConstantAsync](/api/interfaces/FlowConstantAsync.md) | Read-only reactive value that resolves once from a promise or async initializer. |
+| [FlowDerivation](/api/interfaces/FlowDerivation.md) | Read-only reactive value that recomputes automatically when dependencies change. |
+| [FlowDerivationAsync](/api/interfaces/FlowDerivationAsync.md) | Read-only reactive value that recomputes asynchronously when dependencies change. |
+| [FlowDisposable](/api/interfaces/FlowDisposable.md) | Contract for resources that can be explicitly released to prevent memory leaks. |
+| [FlowEffect](/api/interfaces/FlowEffect.md) | Handle to a reactive effect that automatically tracks dependencies and re-executes when they change. |
+| [FlowMap](/api/interfaces/FlowMap.md) | Reactive map with standard mutation methods and fine-grained change tracking. |
+| [FlowObservable](/api/interfaces/FlowObservable.md) | Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph. |
+| [FlowSignal](/api/interfaces/FlowSignal.md) | Manual trigger that notifies subscribers without carrying data. |
+| [FlowState](/api/interfaces/FlowState.md) | Writable reactive value that can be updated manually and notifies dependents on changes. |
+| [FlowStateAsync](/api/interfaces/FlowStateAsync.md) | Writable reactive value that resolves promises and can be updated with new promises. |
+| [FlowSubscribable](/api/interfaces/FlowSubscribable.md) | Contract for observables that can be subscribed to with lifecycle callbacks. |
+| [FlowTracker](/api/interfaces/FlowTracker.md) | Contract for reactive computations that track dependencies and react to changes in the reactivity graph. |
+| [FlowValue](/api/interfaces/FlowValue.md) | Base interface for reactive values that can be read synchronously or asynchronously. |
+| [FlowWritableDerivation](/api/interfaces/FlowWritableDerivation.md) | Writable reactive value that recomputes automatically when dependencies change, but can be manually overridden. |
+| [FlowWritableDerivationAsync](/api/interfaces/FlowWritableDerivationAsync.md) | Writable reactive value that recomputes asynchronously when dependencies change, but can be manually overridden. |
 
 ## Type Aliases
 
 | Type Alias | Description |
 | ------ | ------ |
-| [FlowArrayAction](/api/type-aliases/FlowArrayAction.md) | Represents the actions that can be performed on a FlowArray. |
-| [FlowStreamDisposer](/api/type-aliases/FlowStreamDisposer.md) | A function type that disposes of a resource. |
-| [FlowStreamSetter](/api/type-aliases/FlowStreamSetter.md) | A function type that sets a new value for the reactive stream. |
-| [FlowStreamUpdater](/api/type-aliases/FlowStreamUpdater.md) | A function type that updates a stream and returns a disposer for cleanup. |
-| [NotPromise](/api/type-aliases/NotPromise.md) | Utility type that excludes Promise types from T. Used to ensure type safety for synchronous derivations/resources. |
-| [SolidGetter](/api/type-aliases/SolidGetter.md) | A getter function or value for Solid state/derivation. |
+| [DerivationFunction](/api/type-aliases/DerivationFunction.md) | Function that derives a value from dependencies and optionally the previous value. |
+| [DerivationFunctionAsync](/api/type-aliases/DerivationFunctionAsync.md) | Function that derives a value asynchronously from dependencies and optionally the previous value. |
+| [FlowArrayAction](/api/type-aliases/FlowArrayAction.md) | Discriminated union representing all possible array mutation operations. |
+| [FlowDataTracker](/api/type-aliases/FlowDataTracker.md) | Function that tracks reactive dependencies and returns data. |
+| [FlowMapAction](/api/type-aliases/FlowMapAction.md) | Discriminated union representing all possible map mutation operations. |
+| [FlowOnDataListener](/api/type-aliases/FlowOnDataListener.md) | Callback invoked when new data is available. |
+| [FlowOnErrorListener](/api/type-aliases/FlowOnErrorListener.md) | Callback invoked when an error occurs during effect execution. |
+| [FlowOnPendingListener](/api/type-aliases/FlowOnPendingListener.md) | Callback invoked when an async computation is pending. |
+| [FlowReadonly](/api/type-aliases/FlowReadonly.md) | Type that restricts mutation methods to create read-only versions of reactive primitives. |
+| [InitFunction](/api/type-aliases/InitFunction.md) | Function that initializes a value. |
+| [InitFunctionAsync](/api/type-aliases/InitFunctionAsync.md) | Function that initializes a value asynchronously. |
+| [NotPromise](/api/type-aliases/NotPromise.md) | Type that excludes Promise values from a type union. |
+| [UpdateFunction](/api/type-aliases/UpdateFunction.md) | Function that updates a value based on the previous value. |
+| [UpdateFunctionAsync](/api/type-aliases/UpdateFunctionAsync.md) | Function that updates a value asynchronously based on the previous value. |
 
 ## Functions
 
 | Function | Description |
 | ------ | ------ |
-| [array](/api/functions/array.md) | Creates a new reactive array with mutation methods and fine-grained action tracking. |
-| [constant](/api/functions/constant.md) | Creates a new reactive constant. |
-| [derivation](/api/functions/derivation.md) | Creates a new reactive derivation whose value is computed based on other reactive signals. |
-| [effect](/api/functions/effect.md) | Creates a new reactive effect that executes a side-effect function based on its dependencies. |
-| [from](/api/functions/from.md) | Converts a FlowObservable or getter function into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous. |
-| [isDisposable](/api/functions/isDisposable.md) | Type guard that checks whether an object implements the FlowDisposable interface. |
-| [map](/api/functions/map.md) | Creates a new reactive map state with fine-grained tracking of operations. |
-| [resource](/api/functions/resource.md) | Creates a new reactive resource that asynchronously fetches its value, returning `T | undefined`. |
-| [resourceAsync](/api/functions/resourceAsync.md) | Creates a new reactive asynchronous resource that always returns a Promise. |
-| [signal](/api/functions/signal.md) | Creates a new reactive signal. |
-| [state](/api/functions/state.md) | Creates a new reactive state holding a mutable value. |
-| [stream](/api/functions/stream.md) | Creates a new reactive stream that bridges external event sources with PicoFlow's reactive system. |
-| [streamAsync](/api/functions/streamAsync.md) | Creates a new reactive asynchronous stream that always returns a Promise. |
+| [array](/api/functions/array.md) | Creates a reactive array with mutation methods and fine-grained action tracking. |
+| [constant](/api/functions/constant.md) | Creates a constant reactive value that initializes lazily and never recomputes. |
+| [constantAsync](/api/functions/constantAsync.md) | Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes. |
+| [derivation](/api/functions/derivation.md) | Creates a derived reactive value that automatically recomputes when dependencies change. |
+| [derivationAsync](/api/functions/derivationAsync.md) | Creates an async derived value that automatically recomputes when dependencies change. |
+| [from](/api/functions/from.md) | Converts a PicoFlow observable or getter function into a SolidJS resource. |
+| [isDisposable](/api/functions/isDisposable.md) | Type guard to check if an object implements the FlowDisposable interface. |
+| [map](/api/functions/map.md) | Creates a reactive map with mutation methods and fine-grained action tracking. |
+| [signal](/api/functions/signal.md) | Creates a signal that can be manually triggered to notify dependents. |
+| [state](/api/functions/state.md) | Creates a mutable reactive state that can be read and updated imperatively. |
+| [stateAsync](/api/functions/stateAsync.md) | Creates a mutable async reactive state that resolves promises and can be updated imperatively. |
+| [subscribe](/api/functions/subscribe.md) | Creates a reactive effect that runs immediately and automatically re-runs when dependencies change. |
+| [writableDerivation](/api/functions/writableDerivation.md) | Creates a derived value that recomputes automatically but can also be manually overridden. |
+| [writableDerivationAsync](/api/functions/writableDerivationAsync.md) | Creates an async derived value that recomputes automatically but can also be manually overridden. |