@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/api/classes/FlowStreamAsync.md

@@ -1,364 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / FlowStreamAsync
-
-# Class: FlowStreamAsync\<T\>
-
-Defined in: [advanced/streamAsync.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/streamAsync.ts#L69)
-
-Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function.
-
-## Remarks
-
-FlowStreamAsync extends FlowObservable to bridge external async event sources with PicoFlow's
-reactive system. Unlike [FlowStream](/api/classes/FlowStream.md) which returns `T | undefined`, FlowStreamAsync always
-returns a `Promise<T>`, making it suitable for use with async/await patterns.
-
-**How It Works:**
-1. On construction, creates an initial Promise that resolves when the first value arrives
-2. Your updater function receives a setter callback and sets up event subscriptions
-3. When the setter is called with a value, the Promise resolves (first call) or a new Promise is created (subsequent calls)
-4. The updater returns a disposer function for cleanup
-
-**Promise Behavior:**
-- **First call to setter**: Resolves the initial Promise created at construction
-- **Subsequent calls**: Creates a new `Promise.resolve(value)` for immediate resolution
-- **Reading the value**: Always returns a Promise, either pending (initial) or resolved
-
-**Change Detection:**
-After the first value is set, the stream only notifies subscribers when the new value
-differs from the previous value (using strict equality `===`). This prevents unnecessary
-updates for duplicate values.
-
-**Resource Management:**
-The disposer function returned by your updater is automatically called when the stream
-is disposed. Use it to clean up subscriptions, close connections, or clear timers.
-
-**Use Cases:**
-- Async WebSocket message streams
-- Server-sent events that you want to await
-- Async event handlers
-- Integration with async iterators
-- Any push-based async data source
-
-## Example
-
-```typescript
-// Async WebSocket stream
-const $messages = streamAsync<string>((set) => {
-  const ws = new WebSocket('ws://example.com');
-  ws.onmessage = (event) => set(event.data);
-  return () => ws.close();
-});
-
-// Use with async/await
-effect(async (t) => {
-  const message = await $messages.get(t);
-  console.log('Received:', message);
-});
-
-// Wait for the first message
-const firstMessage = await $messages.pick();
-console.log('First message:', firstMessage);
-
-// Async timer stream
-const $asyncTick = streamAsync<number>((set) => {
-  let count = 0;
-  const id = setInterval(() => set(count++), 1000);
-  return () => clearInterval(id);
-});
-```
-
-## Extends
-
-- [`FlowObservable`](/api/classes/FlowObservable.md)\<`Promise`\<`T`\>\>
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The type of the values emitted by the stream (not the Promise itself). |
-
-## Constructors
-
-### Constructor
-
-```ts
-new FlowStreamAsync<T>(updater): FlowStreamAsync<T>;
-```
-
-Defined in: [advanced/streamAsync.ts:84](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/streamAsync.ts#L84)
-
-Creates a new asynchronous FlowStream.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `updater` | [`FlowStreamUpdater`](/api/type-aliases/FlowStreamUpdater.md)\<`T`\> | A function that receives a setter callback and returns a disposer. The setter should be called whenever new data is available (can be called asynchronously). The disposer will be invoked when the stream is disposed to clean up resources. |
-
-#### Returns
-
-`FlowStreamAsync`\<`T`\>
-
-#### Remarks
-
-The updater is invoked immediately during construction. An initial Promise is created
-that will resolve when the setter is first called. Make sure to return a proper cleanup
-function to avoid resource leaks.
-
-#### Overrides
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`constructor`](/api/classes/FlowObservable.md#constructor)
-
-## Accessors
-
-### disposed
-
-#### Get Signature
-
-```ts
-get disposed(): boolean;
-```
-
-Defined in: [basic/signal.ts:97](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L97)
-
-Indicates whether the FlowSignal has been disposed.
-
-##### Remarks
-
-Once disposed, the signal should not be used.
-
-##### Returns
-
-`boolean`
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`disposed`](/api/classes/FlowObservable.md#disposed)
-
-## Methods
-
-### dispose()
-
-```ts
-dispose(): void;
-```
-
-Defined in: [advanced/streamAsync.ts:110](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/streamAsync.ts#L110)
-
-Disposes the stream, releasing all resources.
-
-#### Returns
-
-`void`
-
-#### Remarks
-
-In addition to disposing the underlying observable, this method calls the disposer
-returned by the updater.
-
-#### Overrides
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`dispose`](/api/classes/FlowObservable.md#dispose)
-
-***
-
-### get()
-
-```ts
-get(context): Promise;
-```
-
-Defined in: [basic/observable.ts:47](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L47)
-
-Gets the current value with optional dependency tracking.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `context` | [`TrackingContext`](/api/classes/TrackingContext.md) \| `null` | The tracking context for reactive tracking, or null for untracked access. When a context is provided, this observable is registered as a dependency. When null, the value is read without any tracking. |
-
-#### Returns
-
-`Promise`
-
-The current value of type T.
-
-#### Remarks
-
-Use `get(t)` within effects and derivations to create reactive dependencies.
-Use `get(null)` when you need to read a value without tracking (though `pick()` is more idiomatic).
-
-#### Example
-
-```typescript
-effect((t) => {
-  const tracked = $state.get(t);     // Dependency registered
-  const untracked = $other.get(null); // No dependency
-});
-```
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`get`](/api/classes/FlowObservable.md#get)
-
-***
-
-### pick()
-
-```ts
-pick(): Promise;
-```
-
-Defined in: [basic/observable.ts:82](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L82)
-
-Gets the current value without any dependency tracking.
-
-#### Returns
-
-`Promise`
-
-The current value of type T.
-
-#### Remarks
-
-This method is equivalent to calling `get(null)` but provides a more semantic and readable API.
-Use `pick()` when you want to read a snapshot of the current value without creating a reactive
-dependency. This is useful for:
-- Reading initial values
-- Accessing configuration that shouldn't trigger updates
-- Mixing tracked and untracked reads in the same effect
-
-#### Example
-
-```typescript
-// Read a snapshot outside reactive context
-const currentValue = $state.pick();
-
-// Mix tracked and untracked reads
-effect((t) => {
-  const tracked = $reactive.get(t);    // Triggers re-runs
-  const snapshot = $config.pick();     // Doesn't trigger re-runs
-  processData(tracked, snapshot);
-});
-```
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`pick`](/api/classes/FlowObservable.md#pick)
-
-***
-
-### subscribe()
-
-```ts
-subscribe(listener): () => void;
-```
-
-Defined in: [basic/observable.ts:103](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L103)
-
-Subscribes a listener function to changes of the observable.
-The listener is executed immediately with the current value and on subsequent updates.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `listener` | (`value`) => `void` | A callback function that receives the new value. |
-
-#### Returns
-
-A disposer function to cancel the subscription.
-
-```ts
-(): void;
-```
-
-##### Returns
-
-`void`
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`subscribe`](/api/classes/FlowObservable.md#subscribe)
-
-***
-
-### trigger()
-
-```ts
-trigger(): void;
-```
-
-Defined in: [basic/signal.ts:19](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L19)
-
-Triggers the FlowSignal.
-Notifies all registered listeners and schedules execution of associated effects.
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowSignal has already been disposed.
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`trigger`](/api/classes/FlowObservable.md#trigger)
-
-***
-
-### watch()
-
-```ts
-watch(context): void;
-```
-
-Defined in: [basic/signal.ts:57](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L57)
-
-Watches the signal, registering it as a dependency in the tracking context.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `context` | [`TrackingContext`](/api/classes/TrackingContext.md) | The tracking context in which to register this signal as a dependency. |
-
-#### Returns
-
-`void`
-
-#### Remarks
-
-Use `watch()` when you want to track a signal without reading its value (signals don't
-have values to read). This is useful for triggering effects based on signal events
-without needing associated data.
-
-When the signal is triggered via `trigger()`, any effects or derivations that have
-watched this signal will automatically re-execute.
-
-This method must be called within an effect or derivation context where a TrackingContext
-is available. For observables (which hold values), use `.get(t)` instead, which both
-reads the value and watches for changes.
-
-#### Throws
-
-Error if the signal has been disposed.
-
-#### Example
-
-```typescript
-const $signal = signal();
-
-effect((t) => {
-  $signal.watch(t);  // Track the signal
-  console.log('Signal triggered!');
-});
-
-$signal.trigger(); // Logs: "Signal triggered!"
-```
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`watch`](/api/classes/FlowObservable.md#watch)

package/docs/api/classes/SolidDerivation.md

@@ -1,75 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / SolidDerivation
-
-# Class: SolidDerivation\<T\>
-
-Defined in: [solid/primitives.ts:114](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L114)
-
-Solid-style derivation wrapping SolidJS's createMemo, providing a computed reactive value.
-
-## Remarks
-
-SolidDerivation is a thin wrapper around SolidJS's `createMemo` that provides a class-based
-interface consistent with PicoFlow's API style. It creates a memoized computation that
-automatically tracks its dependencies and recomputes only when they change.
-
-Unlike PicoFlow's [FlowDerivation](/api/classes/FlowDerivation.md) which uses explicit tracking context, SolidDerivation
-relies on SolidJS's automatic dependency tracking. The computation function runs within
-SolidJS's reactive scope and automatically subscribes to any signals accessed during execution.
-
-**Memoization:**
-The computed value is cached and only recomputed when tracked dependencies change,
-providing efficient derived state management.
-
-## Example
-
-```typescript
-const firstName = new SolidState('John');
-const lastName = new SolidState('Doe');
-
-const fullName = new SolidDerivation(() => {
-  return `${firstName.get()} ${lastName.get()}`;
-});
-
-// In a Solid component
-function Display() {
-  return <div>{fullName.get()}</div>; // Automatically updates
-}
-```
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The value type. |
-
-## Implements
-
-- [`SolidObservable`](/api/interfaces/SolidObservable.md)\<`T`\>
-
-## Constructors
-
-### Constructor
-
-```ts
-new SolidDerivation<T>(calculator): SolidDerivation<T>;
-```
-
-Defined in: [solid/primitives.ts:124](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L124)
-
-Creates a new SolidDerivation from a getter function or value.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `calculator` | [`SolidGetter`](/api/type-aliases/SolidGetter.md)\<`T`\> | The getter function or value. |
-
-#### Returns
-
-`SolidDerivation`\<`T`\>
-
-## Properties
-
-| Property | Modifier | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ | ------ |
-| <a id="get"></a> `get` | `readonly` | () => `T` | Returns the current derived value. | [solid/primitives.ts:118](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L118) |

package/docs/api/classes/SolidResource.md

@@ -1,91 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / SolidResource
-
-# Class: SolidResource\<T\>
-
-Defined in: [solid/primitives.ts:177](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L177)
-
-Solid-style resource wrapping SolidJS's createResource, providing async data loading with reactive state.
-
-## Remarks
-
-SolidResource is a thin wrapper around SolidJS's `createResource` that provides a class-based
-interface consistent with PicoFlow's API style. It manages asynchronous data fetching with
-built-in loading states, error handling, and automatic reactivity.
-
-Unlike PicoFlow's [FlowResource](/api/classes/FlowResource.md) or [FlowResourceAsync](/api/classes/FlowResourceAsync.md), SolidResource integrates
-directly with SolidJS's Suspense and ErrorBoundary mechanisms, providing a first-class async
-data loading experience in Solid applications.
-
-**Resource States:**
-- `unresolved`: Initial state before first fetch
-- `pending`: Fetch is in progress
-- `ready`: Data has been successfully loaded
-- `refreshing`: Refetching while previous data is still available
-- `errored`: Fetch failed with an error
-
-**Properties:**
-- `get()`: Returns the current value (or undefined if not ready)
-- `state()`: Returns the current loading state
-- `latest()`: Returns the most recent successfully loaded value
-- `refetch()`: Triggers a new fetch operation
-
-## Example
-
-```typescript
-const user = new SolidResource(async () => {
-  const res = await fetch('/api/user');
-  return res.json();
-});
-
-// In a Solid component
-function UserProfile() {
-  return (
-    <div>
-      {user.state() === 'pending' && <p>Loading...</p>}
-      {user.state() === 'ready' && <p>Name: {user.get()?.name}</p>}
-      <button onClick={() => user.refetch()}>Refresh</button>
-    </div>
-  );
-}
-```
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The value type. |
-
-## Implements
-
-- [`SolidObservable`](/api/interfaces/SolidObservable.md)\<`T` \| `undefined`\>
-
-## Constructors
-
-### Constructor
-
-```ts
-new SolidResource<T>(fetcher): SolidResource<T>;
-```
-
-Defined in: [solid/primitives.ts:204](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L204)
-
-Creates a new SolidResource from a fetcher function.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `fetcher` | `ResourceFetcher`\<`true`, `T`, `unknown`\> | The async fetcher function. |
-
-#### Returns
-
-`SolidResource`\<`T`\>
-
-## Properties
-
-| Property | Modifier | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ | ------ |
-| <a id="get"></a> `get` | `readonly` | () => `T` \| `undefined` | Returns the current value (or undefined if not yet loaded). | [solid/primitives.ts:181](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L181) |
-| <a id="latest"></a> `latest` | `readonly` | () => `T` \| `undefined` | Returns the latest successfully loaded value (or undefined). | [solid/primitives.ts:194](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L194) |
-| <a id="refetch"></a> `refetch` | `readonly` | () => `void` | Triggers a refetch of the resource. | [solid/primitives.ts:198](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L198) |
-| <a id="state"></a> `state` | `readonly` | () => `"unresolved"` \| `"pending"` \| `"errored"` \| `"ready"` \| `"refreshing"` | Returns the current resource state. | [solid/primitives.ts:185](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L185) |

package/docs/api/classes/SolidState.md

@@ -1,71 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / SolidState
-
-# Class: SolidState\<T\>
-
-Defined in: [solid/primitives.ts:58](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L58)
-
-Solid-style state container wrapping SolidJS's createSignal, providing a writable reactive signal.
-
-## Remarks
-
-SolidState is a thin wrapper around SolidJS's `createSignal` that provides a class-based
-interface consistent with PicoFlow's API style. It's used internally by PicoFlow's Solid
-integration but can also be used directly in Solid components.
-
-Unlike PicoFlow's [FlowState](/api/classes/FlowState.md) which uses explicit tracking context, SolidState
-relies on SolidJS's automatic dependency tracking within reactive contexts like
-`createEffect` or component render functions.
-
-## Example
-
-```typescript
-const count = new SolidState(0);
-
-// In a Solid component
-function Counter() {
-  return <div>{count.get()}</div>; // Automatically reactive
-}
-
-// Update the value
-count.set(1);
-count.set(prev => prev + 1);
-```
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The value type. |
-
-## Implements
-
-- [`SolidObservable`](/api/interfaces/SolidObservable.md)\<`T`\>
-
-## Constructors
-
-### Constructor
-
-```ts
-new SolidState<T>(initialValue): SolidState<T>;
-```
-
-Defined in: [solid/primitives.ts:72](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L72)
-
-Creates a new SolidState with the given initial value.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initialValue` | `T` | The initial value. |
-
-#### Returns
-
-`SolidState`\<`T`\>
-
-## Properties
-
-| Property | Modifier | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ | ------ |
-| <a id="get"></a> `get` | `readonly` | () => `T` | Returns the current value. | [solid/primitives.ts:62](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L62) |
-| <a id="set"></a> `set` | `readonly` | (`param`) => `void` | Sets the value or updates it using a getter function. | [solid/primitives.ts:66](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/primitives.ts#L66) |

package/docs/api/classes/TrackingContext.md

@@ -1,33 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / TrackingContext
-
-# Class: TrackingContext
-
-Defined in: [basic/trackingContext.ts:34](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/trackingContext.ts#L34)
-
-Represents a tracking context used to register dependencies during reactive computations.
-
-## Remarks
-
-TrackingContext is the core mechanism that enables automatic dependency tracking in PicoFlow's
-reactive system. When you create an effect or derivation, PicoFlow automatically creates and
-manages a TrackingContext instance for you. This context is passed as a parameter (typically
-named `t`) to your computation functions.
-
-You use the tracking context to explicitly mark which observables should be tracked as dependencies:
-- Call `observable.get(t)` to read a value AND register it as a dependency
-- Call `observable.pick()` to read a value WITHOUT registering it as a dependency
-- Call `signal.watch(t)` to register a signal as a dependency without reading a value
-
-End-users typically don't instantiate TrackingContext directly; instead, they receive it as
-a parameter in effect and derivation callbacks.
-
-## Example
-
-```typescript
-// TrackingContext passed as parameter 't'
-effect((t) => {
-  const value = $state.get(t);  // Tracked dependency
-  const snapshot = $other.pick(); // Not tracked
-  console.log(value, snapshot);
-});
-```

package/docs/api/functions/effect.md

@@ -1,49 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / effect
-
-# Function: effect()
-
-```ts
-function effect(fn): FlowEffect;
-```
-
-Defined in: [creators.ts:310](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L310)
-
-Creates a new reactive effect that executes a side-effect function based on its dependencies.
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `fn` | (`t`) => `void` | A function that performs side effects using a tracking context. |
-
-## Returns
-
-[`FlowEffect`](/api/classes/FlowEffect.md)
-
-A new instance of [FlowEffect](/api/classes/FlowEffect.md).
-
-## Remarks
-
-An effect is a reactive computation that runs immediately and re-runs whenever its tracked
-dependencies change. Use effects for side effects like logging, DOM updates, network requests,
-or any operation that should respond to reactive state changes.
-
-The effect executes immediately upon creation and provides a tracking context (`t`) that you
-use to explicitly mark dependencies via `observable.get(t)`. Use `observable.pick()` for
-reads that shouldn't trigger re-runs.
-
-## Example
-
-```typescript
-const $count = state(0);
-
-const fx = effect((t) => {
-  console.log('Count is:', $count.get(t));
-});
-
-$count.set(1); // Logs: "Count is: 1"
-$count.set(2); // Logs: "Count is: 2"
-
-// Clean up when done
-fx.dispose();
-```