@ersbeth/picoflow 1.1.1 → 2.0.0

package/docs/api/interfaces/FlowDerivationAsync.md

@@ -0,0 +1,242 @@
+[@ersbeth/picoflow](/api/index.md) / FlowDerivationAsync
+
+# Interface: FlowDerivationAsync\<T\>
+
+Defined in: [api/nodes/async/flowDerivationAsync.ts:20](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L20)
+
+Read-only reactive value that recomputes asynchronously when dependencies change.
+
+Async derivations track reactive values accessed during computation and automatically recompute when any
+tracked dependency changes. The compute function returns a promise, and the resolved value is cached until
+dependencies change. While recomputing, accessing the value throws PendingError. Use for values derived from
+async operations like API calls, database queries, or any computation that depends on reactive state and
+requires async work.
+
+## Extends
+
+- [`FlowValue`](/api/interfaces/FlowValue.md)\<`T`\>
+
+## Extended by
+
+- [`FlowWritableDerivationAsync`](/api/interfaces/FlowWritableDerivationAsync.md)
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Accessors
+
+### disposed
+
+#### Get Signature
+
+```ts
+get disposed(): boolean;
+```
+
+Defined in: [api/base/flowDisposable.ts:17](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L17)
+
+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.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`disposed`](/api/interfaces/FlowValue.md#disposed)
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(): void;
+```
+
+Defined in: [api/base/flowDisposable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L27)
+
+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.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`dispose`](/api/interfaces/FlowValue.md#dispose)
+
+***
+
+### get()
+
+```ts
+get(tracker): T;
+```
+
+Defined in: [api/nodes/flowValue.ts:24](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowValue.ts#L24)
+
+Gets the current value and establishes a reactive dependency.
+
+When called from within a reactive computation, this method registers the value as a dependency,
+ensuring the computation re-executes when the value changes. The value is computed on first access
+(if lazy) and then cached. For async values, throws PendingError while the value is resolving.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) | Tracker that records this value as a dependency |
+
+#### Returns
+
+`T`
+
+The current value
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`get`](/api/interfaces/FlowValue.md#get)
+
+***
+
+### pick()
+
+```ts
+pick(): Promise<T>;
+```
+
+Defined in: [api/nodes/flowValue.ts:35](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowValue.ts#L35)
+
+Asynchronously gets the current value without establishing a reactive dependency.
+
+This method reads the value non-reactively, meaning it won't trigger re-execution of the calling
+computation when the value changes. The value is computed on first access (if lazy) and then cached.
+For async values, the promise resolves once the value is available.
+
+#### Returns
+
+`Promise`\<`T`\>
+
+Promise that resolves with the current value
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`pick`](/api/interfaces/FlowValue.md#pick)
+
+***
+
+### refresh()
+
+```ts
+refresh(): void;
+```
+
+Defined in: [api/nodes/async/flowDerivationAsync.ts:24](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L24)
+
+Forces the derivation to recompute even if dependencies haven't changed.
+
+#### Returns
+
+`void`
+
+***
+
+### subscribe()
+
+```ts
+subscribe(
+   onData, 
+   onError?, 
+   onPending?): FlowEffect;
+```
+
+Defined in: [api/base/flowSubscribable.ts:82](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowSubscribable.ts#L82)
+
+Subscribes to this observable with lifecycle callbacks.
+
+Creates an active subscription that executes immediately and then re-executes whenever
+the observable's dependencies change. The subscription remains active until the returned
+disposal function is called. The `onData` callback receives the computed value, while
+`onError` handles errors and `onPending` signals async operations in progress.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `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 function to dispose the subscription and stop receiving updates
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`subscribe`](/api/interfaces/FlowValue.md#subscribe)
+
+***
+
+### trigger()
+
+```ts
+trigger(): void;
+```
+
+Defined in: [api/base/flowObservable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowObservable.ts#L27)
+
+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.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`trigger`](/api/interfaces/FlowValue.md#trigger)
+
+***
+
+### watch()
+
+```ts
+watch(tracker): void;
+```
+
+Defined in: [api/base/flowObservable.ts:18](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowObservable.ts#L18)
+
+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.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `tracker` | [`FlowTracker`](/api/interfaces/FlowTracker.md) | Tracker that records this observable as a dependency |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowValue`](/api/interfaces/FlowValue.md).[`watch`](/api/interfaces/FlowValue.md#watch)

package/docs/api/interfaces/FlowDisposable.md

@@ -2,64 +2,58 @@
 
 # Interface: FlowDisposable
 
-Defined in: [basic/disposable.ts:35](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L35)
+Defined in: [api/base/flowDisposable.ts:10](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L10)
 
-Represents an object with a disposable lifecycle that manages resources requiring cleanup.
+Contract for resources that can be explicitly released to prevent memory leaks.
 
-## Remarks
+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.
 
-FlowDisposable is the interface for PicoFlow primitives that hold resources needing
-explicit cleanup. Implementing this interface ensures that objects can properly release
-resources such as subscriptions, event listeners, and dependent effects.
+## Extended by
 
-**Disposal Behavior:**
-All PicoFlow reactive primitives (signals, states, effects, derivations, etc.) implement
-this interface. When disposed:
-- The primitive becomes unusable and throws errors on further access
-- All subscriptions and dependencies are cleaned up
-- Memory is freed for garbage collection
+- [`FlowObservable`](/api/interfaces/FlowObservable.md)
+- [`FlowTracker`](/api/interfaces/FlowTracker.md)
+- [`FlowEffect`](/api/interfaces/FlowEffect.md)
 
-**Options:**
-The optional `options` parameter controls disposal behavior:
-- `{ self: true }`: Dispose only this object, leaving dependent effects/listeners active
-- `{ self: false }` or omitted: Dispose this object AND all dependent effects/listeners (cascade)
+## Accessors
 
-## Example
+### disposed
 
-```typescript
-const $state = state(0);
-const fx = effect((t) => console.log($state.get(t)));
+#### Get Signature
 
-// Cascade disposal - disposes $state and all its effects
-$state.dispose();
-
-// Self-only disposal - disposes $state but leaves effects intact
-$state.dispose({ self: true });
+```ts
+get disposed(): boolean;
 ```
 
+Defined in: [api/base/flowDisposable.ts:17](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L17)
+
+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.
+
+##### Returns
+
+`boolean`
+
 ## Methods
 
 ### dispose()
 
 ```ts
-dispose(options?): void;
+dispose(): void;
 ```
 
-Defined in: [basic/disposable.ts:45](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L45)
-
-Disposes resources held by this object.
+Defined in: [api/base/flowDisposable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L27)
 
-#### Parameters
+Releases all resources held by this disposable object.
 
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options?` | \{ `self`: `boolean`; \} | Optional configuration for disposal behavior. |
-| `options.self?` | `boolean` | When true, disposes only this object without cascading to dependents. When false or omitted, disposes this object and all its dependent effects and listeners. |
+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.
 
 #### Returns
 
 `void`
-
-#### Throws
-
-Error if the object has already been disposed (behavior may vary by implementation).

package/docs/api/interfaces/FlowEffect.md

@@ -0,0 +1,64 @@
+[@ersbeth/picoflow](/api/index.md) / FlowEffect
+
+# Interface: FlowEffect
+
+Defined in: [api/nodes/flowEffect.ts:18](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/flowEffect.ts#L18)
+
+Handle to a reactive effect that automatically tracks dependencies and re-executes when they change.
+
+Effects run immediately upon creation and then reactively respond to changes in any reactive values
+accessed during execution. Call `dispose()` to stop the effect and clean up its subscriptions.
+
+## Extends
+
+- [`FlowDisposable`](/api/interfaces/FlowDisposable.md)
+
+## Accessors
+
+### disposed
+
+#### Get Signature
+
+```ts
+get disposed(): boolean;
+```
+
+Defined in: [api/base/flowDisposable.ts:17](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L17)
+
+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.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+[`FlowDisposable`](/api/interfaces/FlowDisposable.md).[`disposed`](/api/interfaces/FlowDisposable.md#disposed)
+
+## Methods
+
+### dispose()
+
+```ts
+dispose(): void;
+```
+
+Defined in: [api/base/flowDisposable.ts:27](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/base/flowDisposable.ts#L27)
+
+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.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`FlowDisposable`](/api/interfaces/FlowDisposable.md).[`dispose`](/api/interfaces/FlowDisposable.md#dispose)