@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/api/functions/from.md

@@ -2,58 +2,15 @@
 
 # Function: from()
 
-Converts a FlowObservable or getter function into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
-
-## Param
-
-The FlowObservable or getter function to convert.
-
-## Remarks
-
-This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
-PicoFlow observables within Solid components. The conversion is automatic based on
-whether the value is a Promise or not:
-
-- **FlowObservable of non-Promise value** → SolidDerivation (reactive signal)
-- **FlowObservable of Promise** → SolidResource (async resource)
-- **Getter function returning non-Promise** → SolidDerivation (computed signal)
-- **Getter function returning Promise** → SolidResource (async computed resource)
-
-The created Solid primitives automatically subscribe to the PicoFlow observables and
-update when changes occur. The subscription is properly cleaned up when the Solid
-component unmounts.
-
-## Example
-
-```typescript
-import { from } from 'picoflow/solid';
-import { state } from 'picoflow';
-
-// Convert a PicoFlow state to a Solid signal
-const $count = state(0);
-const solidCount = from($count);
-
-// Use in a Solid component
-function Counter() {
-  const count = solidCount.get(); // Solid's reactive get
-  return <div>Count: {count}</div>;
-}
-
-// Or convert a computation function
-const solidDerived = from((t) => {
-  return $count.get(t) * 2;
-});
-```
-
 ## Call Signature
 
 ```ts
-function from<T>(flow): SolidResource<NotPromise<T>>;
+function from<T>(flow): Resource<T>;
 ```
 
-Defined in: [solid/converters.ts:159](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L159)
+Defined in: [converters/solid.ts:97](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/converters/solid.ts#L97)
 
-Converts a FlowObservable of a Promise value into a SolidResource.
+Converts a PicoFlow observable or getter function into a SolidJS resource.
 
 ### Type Parameters
 
@@ -65,82 +22,58 @@ Converts a FlowObservable of a Promise value into a SolidResource.
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `flow` | [`FlowObservable`](/api/classes/FlowObservable.md)\<`Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>\> | The FlowObservable to convert. |
+| `flow` | [`FlowObservable`](/api/interfaces/FlowObservable.md)\<`T`\> | The FlowObservable or getter function to convert. |
 
 ### Returns
 
-[`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
-
-A SolidResource wrapping the observable.
-
-## Call Signature
-
-```ts
-function from<T>(flow): SolidDerivation<NotPromise<T>>;
-```
+`Resource`\<`T`\>
 
-Defined in: [solid/converters.ts:170](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L170)
+A SolidJS Resource that wraps the value or computation.
 
-Converts a FlowObservable of a non-Promise value into a SolidDerivation.
+### Remarks
 
-### Type Parameters
+This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+PicoFlow primitives and computations within Solid components. All conversions return a
+SolidJS Resource, which can handle both synchronous and asynchronous values seamlessly.
 
-| Type Parameter |
-| ------ |
-| `T` |
+The conversion works with:
+- **FlowObservable**: Any PicoFlow reactive primitive (e.g., from `state()`, `derivation()`, `stateAsync()`, `derivationAsync()`)
+- **Getter functions**: Computation functions that use a FlowTracker to access reactive values
 
-### Parameters
+The created Resource automatically subscribes to the PicoFlow observables and updates
+when their values change. The subscription is properly cleaned up when the Solid
+component unmounts.
 
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | [`FlowObservable`](/api/classes/FlowObservable.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The FlowObservable to convert. |
+### Example
 
-### Returns
-
-[`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+```typescript
+import { from } from 'picoflow/solid';
+import { state, derivation } from 'picoflow';
 
-A SolidDerivation wrapping the observable.
+// Convert a PicoFlow state to a Solid resource
+const $count = state(0);
+const solidCount = from($count);
 
-## Call Signature
+// Use in a Solid component
+function Counter() {
+  return <div>Count: {solidCount()}</div>;
+}
 
-```ts
-function from<T>(flow): 
-  | SolidDerivation<NotPromise<T>>
-| SolidResource<NotPromise<T>>;
+// Or convert a computation function
+const solidDerived = from((t) => {
+  return $count.get(t) * 2;
+});
 ```
 
-Defined in: [solid/converters.ts:181](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L181)
-
-Converts a FlowObservable into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | \| [`FlowObservable`](/api/classes/FlowObservable.md)\<`Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>\> \| [`FlowObservable`](/api/classes/FlowObservable.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The FlowObservable to convert. |
-
-### Returns
-
-  \| [`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
-  \| [`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
-
-A SolidDerivation or SolidResource, depending on the input type.
-
 ## Call Signature
 
 ```ts
-function from<T>(flow): SolidDerivation<NotPromise<T>>;
+function from<T>(flow): Resource<T>;
 ```
 
-Defined in: [solid/converters.ts:192](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L192)
+Defined in: [converters/solid.ts:98](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/converters/solid.ts#L98)
 
-Converts a getter function returning a non-Promise value into a SolidDerivation.
+Converts a PicoFlow observable or getter function into a SolidJS resource.
 
 ### Type Parameters
 
@@ -152,69 +85,45 @@ Converts a getter function returning a non-Promise value into a SolidDerivation.
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `flow` | (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | The getter function to convert. |
+| `flow` | (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | The FlowObservable or getter function to convert. |
 
 ### Returns
 
-[`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
-
-A SolidDerivation wrapping the getter.
-
-## Call Signature
-
-```ts
-function from<T>(flow): SolidResource<NotPromise<T>>;
-```
+`Resource`\<`T`\>
 
-Defined in: [solid/converters.ts:203](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L203)
+A SolidJS Resource that wraps the value or computation.
 
-Converts a getter function returning a Promise into a SolidResource.
+### Remarks
 
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
+This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+PicoFlow primitives and computations within Solid components. All conversions return a
+SolidJS Resource, which can handle both synchronous and asynchronous values seamlessly.
 
-### Parameters
+The conversion works with:
+- **FlowObservable**: Any PicoFlow reactive primitive (e.g., from `state()`, `derivation()`, `stateAsync()`, `derivationAsync()`)
+- **Getter functions**: Computation functions that use a FlowTracker to access reactive values
 
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | (`t`) => `Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The getter function to convert. |
+The created Resource automatically subscribes to the PicoFlow observables and updates
+when their values change. The subscription is properly cleaned up when the Solid
+component unmounts.
 
-### Returns
+### Example
 
-[`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+```typescript
+import { from } from 'picoflow/solid';
+import { state, derivation } from 'picoflow';
 
-A SolidResource wrapping the getter.
+// Convert a PicoFlow state to a Solid resource
+const $count = state(0);
+const solidCount = from($count);
 
-## Call Signature
+// Use in a Solid component
+function Counter() {
+  return <div>Count: {solidCount()}</div>;
+}
 
-```ts
-function from<T>(flow): 
-  | SolidDerivation<T>
-| SolidResource<T>;
+// Or convert a computation function
+const solidDerived = from((t) => {
+  return $count.get(t) * 2;
+});
 ```
-
-Defined in: [solid/converters.ts:214](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L214)
-
-Converts a getter function into a Solid derivation or resource, depending on whether the returned value is synchronous or asynchronous.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `flow` | \| (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> \| (`t`) => `Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The getter function to convert. |
-
-### Returns
-
-  \| [`SolidDerivation`](/api/classes/SolidDerivation.md)\<`T`\>
-  \| [`SolidResource`](/api/classes/SolidResource.md)\<`T`\>
-
-A SolidDerivation or SolidResource, depending on the input type.

package/docs/api/functions/isDisposable.md

@@ -6,44 +6,22 @@
 function isDisposable(obj): obj is FlowDisposable;
 ```
 
-Defined in: [basic/disposable.ts:80](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L80)
+Defined in: [api/base/flowDisposable.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L42)
 
-Type guard that checks whether an object implements the FlowDisposable interface.
+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.
 
 ## Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `obj` | `unknown` | The object to test for disposability. |
+| `obj` | `unknown` | The object to check |
 
 ## Returns
 
 `obj is FlowDisposable`
 
-True if the object has a `dispose` method and is therefore disposable, false otherwise.
-
-## Remarks
-
-This utility function is useful for safely checking if an object needs disposal before
-attempting cleanup operations. It performs a runtime check for the presence of a `dispose`
-method, making it safe to use with unknown types.
-
-**Common Use Cases:**
-- Conditionally disposing items in collections (arrays, maps)
-- Generic cleanup functions that handle both disposable and non-disposable objects
-- Defensive programming when working with mixed types
-
-## Example
-
-```typescript
-function cleanupArray<T>(items: T[]) {
-  items.forEach(item => {
-    if (isDisposable(item)) {
-      item.dispose();
-    }
-  });
-}
-
-const mixed = [state(1), "string", signal(), 42];
-cleanupArray(mixed); // Only disposes the state and signal
-```
+True if the object implements FlowDisposable, false otherwise

package/docs/api/functions/map.md

@@ -6,52 +6,31 @@
 function map<K, V>(initial?): FlowMap<K, V>;
 ```
 
-Defined in: [creators.ts:349](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L349)
+Defined in: [api/nodes/collections/flowMap.ts:110](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowMap.ts#L110)
 
-Creates a new reactive map state with fine-grained tracking of operations.
+Creates a reactive map with mutation methods and fine-grained action tracking.
+
+The map starts with the provided initial entries (or empty if none provided). All mutation methods
+(add, update, delete) notify dependents and emit detailed action information to `$lastAction`.
+Use the map itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
+reactivity to specific mutation types. Useful for entity stores, lookup tables, or any key-value
+data that needs reactive updates.
 
 ## Type Parameters
 
-| Type Parameter | Description |
-| ------ | ------ |
-| `K` *extends* `string` \| `number` \| `symbol` | The type of the keys. |
-| `V` | The type of the values. |
+| Type Parameter |
+| ------ |
+| `K` *extends* `string` \| `number` \| `symbol` |
+| `V` |
 
 ## Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `initial?` | `Record`\<`K`, `V`\> | An optional record of key-value pairs to initialize the map. |
+| `initial?` | `Record`\<`K`, `V`\> \| `Map`\<`K`, `V`\> | Optional initial entries as a Record or Map |
 
 ## Returns
 
-[`FlowMap`](/api/classes/FlowMap.md)\<`K`, `V`\>
-
-A new instance of [FlowMap](/api/classes/FlowMap.md).
-
-## Remarks
-
-A reactive map wraps a native JavaScript Map and provides multiple levels of reactivity:
-tracking the entire map, tracking individual set operations, and tracking individual
-delete operations. The initial record (if provided) is converted to a native Map.
-
-## Example
+[`FlowMap`](/api/interfaces/FlowMap.md)\<`K`, `V`\>
 
-```typescript
-const $users = map<string, User>({
-  'user1': { name: 'John', age: 30 }
-});
-
-// Track the whole map
-effect((t) => {
-  console.log('Users:', $users.get(t).size);
-});
-
-// Track additions
-effect((t) => {
-  const { key, value } = $users.$lastSet.get(t);
-  if (key) console.log(`Added: ${key}`);
-});
-
-$users.setAt('user2', { name: 'Jane', age: 25 });
-```
+A FlowMap with reactive mutation methods

package/docs/api/functions/signal.md

@@ -6,31 +6,16 @@
 function signal(): FlowSignal;
 ```
 
-Defined in: [creators.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L42)
+Defined in: [api/nodes/flowSignal.ts:26](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowSignal.ts#L26)
 
-Creates a new reactive signal.
+Creates a signal that can be manually triggered to notify dependents.
 
-## Returns
-
-[`FlowSignal`](/api/classes/FlowSignal.md)
-
-A new instance of [FlowSignal](/api/classes/FlowSignal.md).
-
-## Remarks
+Signals act as event emitters in the reactive graph. Call `trigger()` to notify all subscribers
+and reactive computations that depend on the signal. Unlike state or derivations, signals don't
+carry data values - they simply represent that an event occurred.
 
-A signal is the simplest reactive primitive - it doesn't hold a value, but can be triggered
-to notify dependent effects and derivations. Use signals when you need event-like notifications
-without associated data.
-
-## Example
-
-```typescript
-const $refresh = signal();
+## Returns
 
-effect((t) => {
-  $refresh.watch(t);
-  console.log('Refreshing...');
-});
+[`FlowSignal`](/api/interfaces/FlowSignal.md)
 
-$refresh.trigger(); // Logs: "Refreshing..."
-```
+A FlowSignal that can be triggered manually and subscribed to

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