@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/api/classes/FlowObservable.md

@@ -1,306 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / FlowObservable
-
-# Abstract Class: FlowObservable\<T\>
-
-Defined in: [basic/observable.ts:23](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/observable.ts#L23)
-
-Represents a reactive observable that holds and tracks a value.
-
-## Remarks
-
-FlowObservable is the base class for all reactive values in PicoFlow. It provides two ways
-to access the current value:
-
-1. **Tracked access** via `get(context)`: Registers the observable as a dependency in the
-   tracking context, so changes trigger re-execution of the effect or derivation.
-
-2. **Untracked access** via `pick()` or `get(null)`: Reads the current value without registering
-   a dependency, useful for reading values within effects that shouldn't trigger re-runs.
-
-Subclasses must implement the [FlowObservable.\_getRaw](#) method to provide the actual value.
-
-## Extends
-
-- [`FlowSignal`](/api/classes/FlowSignal.md)
-
-## Extended by
-
-- [`FlowArray`](/api/classes/FlowArray.md)
-- [`FlowResource`](/api/classes/FlowResource.md)
-- [`FlowResourceAsync`](/api/classes/FlowResourceAsync.md)
-- [`FlowStream`](/api/classes/FlowStream.md)
-- [`FlowStreamAsync`](/api/classes/FlowStreamAsync.md)
-- [`FlowConstant`](/api/classes/FlowConstant.md)
-- [`FlowDerivation`](/api/classes/FlowDerivation.md)
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The type of the value held by the observable. |
-
-## Constructors
-
-### Constructor
-
-```ts
-new FlowObservable<T>(): FlowObservable<T>;
-```
-
-#### Returns
-
-`FlowObservable`\<`T`\>
-
-#### Inherited from
-
-[`FlowSignal`](/api/classes/FlowSignal.md).[`constructor`](/api/classes/FlowSignal.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
-
-[`FlowSignal`](/api/classes/FlowSignal.md).[`disposed`](/api/classes/FlowSignal.md#disposed)
-
-## Methods
-
-### dispose()
-
-```ts
-dispose(options?): void;
-```
-
-Defined in: [basic/signal.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L69)
-
-Disposes the FlowSignal.
-Cleans up all registered effects, listeners, and dependencies.
-Once disposed, further usage of the signal will throw an error.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `options?` | \{ `self`: `boolean`; \} |
-| `options.self?` | `boolean` |
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowSignal is already disposed.
-
-#### Inherited from
-
-[`FlowSignal`](/api/classes/FlowSignal.md).[`dispose`](/api/classes/FlowSignal.md#dispose)
-
-***
-
-### get()
-
-```ts
-get(context): T;
-```
-
-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
-
-`T`
-
-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
-});
-```
-
-***
-
-### pick()
-
-```ts
-pick(): T;
-```
-
-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
-
-`T`
-
-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);
-});
-```
-
-***
-
-### 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`
-
-***
-
-### 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
-
-[`FlowSignal`](/api/classes/FlowSignal.md).[`trigger`](/api/classes/FlowSignal.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
-
-[`FlowSignal`](/api/classes/FlowSignal.md).[`watch`](/api/classes/FlowSignal.md#watch)

package/docs/api/classes/FlowResource.md

@@ -1,380 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / FlowResource
-
-# Class: FlowResource\<T\>
-
-Defined in: [advanced/resource.ts:56](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/resource.ts#L56)
-
-Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`.
-
-## Remarks
-
-FlowResource extends FlowObservable to manage asynchronous data fetching with reactive updates.
-Unlike [FlowResourceAsync](/api/classes/FlowResourceAsync.md) which always returns a Promise, FlowResource returns the resolved
-value directly (or `undefined` if not yet fetched), making it more convenient for synchronous access
-patterns in effects and derivations.
-
-**Key Characteristics:**
-- The value is `undefined` initially, before the first fetch
-- Call `fetch()` to trigger the asynchronous fetch operation
-- When fetched, the value is compared to the current value; only different values trigger updates
-- Reading via `get(t)` or `pick()` returns the current value (possibly `undefined`) without triggering a fetch
-
-**Fetch Behavior:**
-The fetch function is NOT called automatically on construction. You must explicitly call the
-`fetch()` method to retrieve the resource. This gives you control over when network requests
-or expensive async operations occur.
-
-**Use Cases:**
-- API data fetching where you want synchronous access to the cached value
-- Lazy-loaded data that shouldn't fetch on construction
-- Resources that need manual refresh control
-- Data that may or may not be available (hence `T | undefined`)
-
-## Example
-
-```typescript
-const $user = resource(() => fetchUserFromAPI());
-
-// Initially undefined
-console.log($user.pick()); // undefined
-
-// Trigger the fetch
-await $user.fetch();
-console.log($user.pick()); // { id: 1, name: 'John' }
-
-// Use in an effect
-effect((t) => {
-  const user = $user.get(t);
-  if (user) {
-    console.log(`Hello, ${user.name}`);
-  }
-});
-
-// Refetch to update
-await $user.fetch();
-```
-
-## Extends
-
-- [`FlowObservable`](/api/classes/FlowObservable.md)\<`T` \| `undefined`\>
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The type of the resource value (not including the undefined case). |
-
-## Constructors
-
-### Constructor
-
-```ts
-new FlowResource<T>(fetch): FlowResource<T>;
-```
-
-Defined in: [advanced/resource.ts:66](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/resource.ts#L66)
-
-Creates a new FlowResource.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `fetch` | () => `Promise`\<`T`\> | An asynchronous function that retrieves the resource's value. This function is not invoked on construction; you must call the `fetch()` method to execute it. |
-
-#### Returns
-
-`FlowResource`\<`T`\>
-
-#### 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(options?): void;
-```
-
-Defined in: [basic/signal.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/signal.ts#L69)
-
-Disposes the FlowSignal.
-Cleans up all registered effects, listeners, and dependencies.
-Once disposed, further usage of the signal will throw an error.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `options?` | \{ `self`: `boolean`; \} |
-| `options.self?` | `boolean` |
-
-#### Returns
-
-`void`
-
-#### Throws
-
-If the FlowSignal is already disposed.
-
-#### Inherited from
-
-[`FlowObservable`](/api/classes/FlowObservable.md).[`dispose`](/api/classes/FlowObservable.md#dispose)
-
-***
-
-### fetch()
-
-```ts
-fetch(): Promise<void>;
-```
-
-Defined in: [advanced/resource.ts:89](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/resource.ts#L89)
-
-Asynchronously fetches a new value for the resource.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-A Promise that resolves when the fetch operation is complete.
-
-#### Remarks
-
-Executes the internal fetch function. If the fetched value differs from the current one,
-updates the resource's value and notifies subscribers.
-
-#### Throws
-
-Error if the resource is disposed.
-
-***
-
-### get()
-
-```ts
-get(context): T | undefined;
-```
-
-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
-
-`T` \| `undefined`
-
-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(): T | undefined;
-```
-
-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
-
-`T` \| `undefined`
-
-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)