@ersbeth/picoflow 0.2.4 → 1.0.0

package/docs/api/classes/FlowObservable.md

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

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