@ersbeth/picoflow 0.2.4 → 1.0.0

package/docs/api/classes/FlowStreamAsync.md

@@ -0,0 +1,364 @@
+[@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

@@ -0,0 +1,75 @@
+[@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

@@ -0,0 +1,91 @@
+[@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

@@ -0,0 +1,71 @@
+[@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

@@ -0,0 +1,33 @@
+[@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/array.md

@@ -0,0 +1,58 @@
+[@ersbeth/picoflow](/api/index.md) / array
+
+# Function: array()
+
+```ts
+function array<T>(initial?): FlowArray<T>;
+```
+
+Defined in: [creators.ts:393](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L393)
+
+Creates a new reactive array with mutation methods and fine-grained action tracking.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the array elements. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `initial?` | `T`[] | An optional array of initial values. |
+
+## Returns
+
+[`FlowArray`](/api/classes/FlowArray.md)\<`T`\>
+
+A new instance of [FlowArray](/api/classes/FlowArray.md).
+
+## Remarks
+
+A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
+and tracks the last operation performed via `$lastAction`. This enables both whole-array
+reactivity and fine-grained tracking of specific mutations.
+
+The array automatically disposes disposable items when they are removed (if they implement
+the FlowDisposable interface).
+
+## Example
+
+```typescript
+const $items = array([1, 2, 3]);
+
+// Track the whole array
+effect((t) => {
+  console.log('Items:', $items.get(t));
+});
+
+// Track the last action
+effect((t) => {
+  const action = $items.$lastAction.get(t);
+  console.log('Action:', action.type);
+});
+
+$items.push(4); // Logs action: "push"
+$items.pop();   // Logs action: "pop"
+```