@ersbeth/picoflow 0.2.4 → 1.0.0

package/docs/api/functions/constant.md

@@ -0,0 +1,45 @@
+[@ersbeth/picoflow](/api/index.md) / constant
+
+# Function: constant()
+
+```ts
+function constant<T>(value): FlowConstant<T>;
+```
+
+Defined in: [creators.ts:69](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L69)
+
+Creates a new reactive constant.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the constant value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `T` \| () => `T` | The value or a function that returns the value (for lazy initialization). |
+
+## Returns
+
+[`FlowConstant`](/api/classes/FlowConstant.md)\<`T`\>
+
+A new instance of [FlowConstant](/api/classes/FlowConstant.md).
+
+## Remarks
+
+A constant is an immutable reactive value that never changes after initialization.
+It can be initialized eagerly (direct value) or lazily (function). Use constants for
+configuration, computed-once values, or expensive initialization that should only run once.
+
+## Example
+
+```typescript
+// Eager initialization
+const $config = constant({ apiUrl: 'https://api.example.com' });
+
+// Lazy initialization
+const $computed = constant(() => expensiveCalculation());
+```

package/docs/api/functions/derivation.md

@@ -0,0 +1,53 @@
+[@ersbeth/picoflow](/api/index.md) / derivation
+
+# Function: derivation()
+
+```ts
+function derivation<T>(fn): FlowDerivation<T>;
+```
+
+Defined in: [creators.ts:272](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L272)
+
+Creates a new reactive derivation whose value is computed based on other reactive signals.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the derived value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `fn` | (`t`) => `T` | A function that computes the derived value using a tracking context. |
+
+## Returns
+
+[`FlowDerivation`](/api/classes/FlowDerivation.md)\<`T`\>
+
+A new instance of [FlowDerivation](/api/classes/FlowDerivation.md).
+
+## Remarks
+
+A derivation is a computed reactive value that automatically tracks its dependencies and
+recomputes when they change. The computation is lazy - it runs only when the value is
+accessed, not on construction. Use derivations to create derived state without manual
+dependency management.
+
+## Example
+
+```typescript
+const $firstName = state('John');
+const $lastName = state('Doe');
+
+const $fullName = derivation((t) => {
+  return `${$firstName.get(t)} ${$lastName.get(t)}`;
+});
+
+effect((t) => {
+  console.log($fullName.get(t)); // Logs: "John Doe"
+});
+
+$firstName.set('Jane'); // Logs: "Jane Doe"
+```

package/docs/api/functions/effect.md

@@ -0,0 +1,49 @@
+[@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();
+```

package/docs/api/functions/from.md

@@ -0,0 +1,220 @@
+[@ersbeth/picoflow](/api/index.md) / from
+
+# Function: from()
+
+Converts a FlowObservable or getter function into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
+
+## Param
+
+The FlowObservable or getter function to convert.
+
+## Remarks
+
+This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+PicoFlow observables within Solid components. The conversion is automatic based on
+whether the value is a Promise or not:
+
+- **FlowObservable of non-Promise value** → SolidDerivation (reactive signal)
+- **FlowObservable of Promise** → SolidResource (async resource)
+- **Getter function returning non-Promise** → SolidDerivation (computed signal)
+- **Getter function returning Promise** → SolidResource (async computed resource)
+
+The created Solid primitives automatically subscribe to the PicoFlow observables and
+update when changes occur. The subscription is properly cleaned up when the Solid
+component unmounts.
+
+## Example
+
+```typescript
+import { from } from 'picoflow/solid';
+import { state } from 'picoflow';
+
+// Convert a PicoFlow state to a Solid signal
+const $count = state(0);
+const solidCount = from($count);
+
+// Use in a Solid component
+function Counter() {
+  const count = solidCount.get(); // Solid's reactive get
+  return <div>Count: {count}</div>;
+}
+
+// Or convert a computation function
+const solidDerived = from((t) => {
+  return $count.get(t) * 2;
+});
+```
+
+## Call Signature
+
+```ts
+function from<T>(flow): SolidResource<NotPromise<T>>;
+```
+
+Defined in: [solid/converters.ts:159](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L159)
+
+Converts a FlowObservable of a Promise value into a SolidResource.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | [`FlowObservable`](/api/classes/FlowObservable.md)\<`Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>\> | The FlowObservable to convert. |
+
+### Returns
+
+[`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+
+A SolidResource wrapping the observable.
+
+## Call Signature
+
+```ts
+function from<T>(flow): SolidDerivation<NotPromise<T>>;
+```
+
+Defined in: [solid/converters.ts:170](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L170)
+
+Converts a FlowObservable of a non-Promise value into a SolidDerivation.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | [`FlowObservable`](/api/classes/FlowObservable.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The FlowObservable to convert. |
+
+### Returns
+
+[`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+
+A SolidDerivation wrapping the observable.
+
+## Call Signature
+
+```ts
+function from<T>(flow): 
+  | SolidDerivation<NotPromise<T>>
+| SolidResource<NotPromise<T>>;
+```
+
+Defined in: [solid/converters.ts:181](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L181)
+
+Converts a FlowObservable into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | \| [`FlowObservable`](/api/classes/FlowObservable.md)\<`Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>\> \| [`FlowObservable`](/api/classes/FlowObservable.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The FlowObservable to convert. |
+
+### Returns
+
+  \| [`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+  \| [`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+
+A SolidDerivation or SolidResource, depending on the input type.
+
+## Call Signature
+
+```ts
+function from<T>(flow): SolidDerivation<NotPromise<T>>;
+```
+
+Defined in: [solid/converters.ts:192](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L192)
+
+Converts a getter function returning a non-Promise value into a SolidDerivation.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> | The getter function to convert. |
+
+### Returns
+
+[`SolidDerivation`](/api/classes/SolidDerivation.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+
+A SolidDerivation wrapping the getter.
+
+## Call Signature
+
+```ts
+function from<T>(flow): SolidResource<NotPromise<T>>;
+```
+
+Defined in: [solid/converters.ts:203](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L203)
+
+Converts a getter function returning a Promise into a SolidResource.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | (`t`) => `Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The getter function to convert. |
+
+### Returns
+
+[`SolidResource`](/api/classes/SolidResource.md)\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\>
+
+A SolidResource wrapping the getter.
+
+## Call Signature
+
+```ts
+function from<T>(flow): 
+  | SolidDerivation<T>
+| SolidResource<T>;
+```
+
+Defined in: [solid/converters.ts:214](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/solid/converters.ts#L214)
+
+Converts a getter function into a Solid derivation or resource, depending on whether the returned value is synchronous or asynchronous.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `flow` | \| (`t`) => [`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\> \| (`t`) => `Promise`\<[`NotPromise`](/api/type-aliases/NotPromise.md)\<`T`\>\> | The getter function to convert. |
+
+### Returns
+
+  \| [`SolidDerivation`](/api/classes/SolidDerivation.md)\<`T`\>
+  \| [`SolidResource`](/api/classes/SolidResource.md)\<`T`\>
+
+A SolidDerivation or SolidResource, depending on the input type.

package/docs/api/functions/isDisposable.md

@@ -0,0 +1,49 @@
+[@ersbeth/picoflow](/api/index.md) / isDisposable
+
+# Function: isDisposable()
+
+```ts
+function isDisposable(obj): obj is FlowDisposable;
+```
+
+Defined in: [basic/disposable.ts:80](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/basic/disposable.ts#L80)
+
+Type guard that checks whether an object implements the FlowDisposable interface.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `obj` | `unknown` | The object to test for disposability. |
+
+## Returns
+
+`obj is FlowDisposable`
+
+True if the object has a `dispose` method and is therefore disposable, false otherwise.
+
+## Remarks
+
+This utility function is useful for safely checking if an object needs disposal before
+attempting cleanup operations. It performs a runtime check for the presence of a `dispose`
+method, making it safe to use with unknown types.
+
+**Common Use Cases:**
+- Conditionally disposing items in collections (arrays, maps)
+- Generic cleanup functions that handle both disposable and non-disposable objects
+- Defensive programming when working with mixed types
+
+## Example
+
+```typescript
+function cleanupArray<T>(items: T[]) {
+  items.forEach(item => {
+    if (isDisposable(item)) {
+      item.dispose();
+    }
+  });
+}
+
+const mixed = [state(1), "string", signal(), 42];
+cleanupArray(mixed); // Only disposes the state and signal
+```

package/docs/api/functions/map.md

@@ -0,0 +1,57 @@
+[@ersbeth/picoflow](/api/index.md) / map
+
+# Function: map()
+
+```ts
+function map<K, V>(initial?): FlowMap<K, V>;
+```
+
+Defined in: [creators.ts:349](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L349)
+
+Creates a new reactive map state with fine-grained tracking of operations.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `K` *extends* `string` \| `number` \| `symbol` | The type of the keys. |
+| `V` | The type of the values. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `initial?` | `Record`\<`K`, `V`\> | An optional record of key-value pairs to initialize the map. |
+
+## Returns
+
+[`FlowMap`](/api/classes/FlowMap.md)\<`K`, `V`\>
+
+A new instance of [FlowMap](/api/classes/FlowMap.md).
+
+## Remarks
+
+A reactive map wraps a native JavaScript Map and provides multiple levels of reactivity:
+tracking the entire map, tracking individual set operations, and tracking individual
+delete operations. The initial record (if provided) is converted to a native Map.
+
+## Example
+
+```typescript
+const $users = map<string, User>({
+  'user1': { name: 'John', age: 30 }
+});
+
+// Track the whole map
+effect((t) => {
+  console.log('Users:', $users.get(t).size);
+});
+
+// Track additions
+effect((t) => {
+  const { key, value } = $users.$lastSet.get(t);
+  if (key) console.log(`Added: ${key}`);
+});
+
+$users.setAt('user2', { name: 'Jane', age: 25 });
+```

package/docs/api/functions/resource.md

@@ -0,0 +1,52 @@
+[@ersbeth/picoflow](/api/index.md) / resource
+
+# Function: resource()
+
+```ts
+function resource<T>(fn): FlowResource<T>;
+```
+
+Defined in: [creators.ts:132](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L132)
+
+Creates a new reactive resource that asynchronously fetches its value, returning `T | undefined`.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the resource value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `fn` | () => `Promise`\<`T`\> | An asynchronous function that fetches the resource value. |
+
+## Returns
+
+[`FlowResource`](/api/classes/FlowResource.md)\<`T`\>
+
+A new instance of [FlowResource](/api/classes/FlowResource.md).
+
+## Remarks
+
+A resource manages async data fetching with reactive updates. Unlike [resourceAsync](/api/functions/resourceAsync.md),
+this returns the resolved value directly (or `undefined` if not fetched yet), making it
+easier to work with in synchronous contexts. Call `fetch()` to trigger the async operation.
+
+## Example
+
+```typescript
+const $user = resource(() => fetch('/api/user').then(r => r.json()));
+
+// Trigger fetch
+await $user.fetch();
+
+// Use in effect
+effect((t) => {
+  const user = $user.get(t);
+  if (user) {
+    console.log(user.name);
+  }
+});
+```

package/docs/api/functions/resourceAsync.md

@@ -0,0 +1,50 @@
+[@ersbeth/picoflow](/api/index.md) / resourceAsync
+
+# Function: resourceAsync()
+
+```ts
+function resourceAsync<T>(fn): FlowResourceAsync<T>;
+```
+
+Defined in: [creators.ts:164](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L164)
+
+Creates a new reactive asynchronous resource that always returns a Promise.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the resource value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `fn` | () => `Promise`\<`T`\> | An asynchronous function that fetches the resource value. |
+
+## Returns
+
+[`FlowResourceAsync`](/api/classes/FlowResourceAsync.md)\<`T`\>
+
+A new instance of [FlowResourceAsync](/api/classes/FlowResourceAsync.md).
+
+## Remarks
+
+An async resource manages async data fetching and always returns a Promise, making it
+ideal for async/await patterns. Unlike [resource](/api/functions/resource.md), the Promise is created lazily
+on first access and cached. Call `fetch()` to create a new Promise and trigger a refetch.
+
+## Example
+
+```typescript
+const $data = resourceAsync(() => fetch('/api/data').then(r => r.json()));
+
+// Use with async/await
+effect(async (t) => {
+  const data = await $data.get(t);
+  console.log(data);
+});
+
+// Refetch
+await $data.fetch();
+```

package/docs/api/functions/signal.md

@@ -0,0 +1,36 @@
+[@ersbeth/picoflow](/api/index.md) / signal
+
+# Function: signal()
+
+```ts
+function signal(): FlowSignal;
+```
+
+Defined in: [creators.ts:42](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L42)
+
+Creates a new reactive signal.
+
+## Returns
+
+[`FlowSignal`](/api/classes/FlowSignal.md)
+
+A new instance of [FlowSignal](/api/classes/FlowSignal.md).
+
+## Remarks
+
+A signal is the simplest reactive primitive - it doesn't hold a value, but can be triggered
+to notify dependent effects and derivations. Use signals when you need event-like notifications
+without associated data.
+
+## Example
+
+```typescript
+const $refresh = signal();
+
+effect((t) => {
+  $refresh.watch(t);
+  console.log('Refreshing...');
+});
+
+$refresh.trigger(); // Logs: "Refreshing..."
+```

package/docs/api/functions/state.md

@@ -0,0 +1,47 @@
+[@ersbeth/picoflow](/api/index.md) / state
+
+# Function: state()
+
+```ts
+function state<T>(value): FlowState<T>;
+```
+
+Defined in: [creators.ts:98](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/creators.ts#L98)
+
+Creates a new reactive state holding a mutable value.
+
+## Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the state value. |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `T` \| () => `T` | The initial value for the state, or a function returning the initial value. |
+
+## Returns
+
+[`FlowState`](/api/classes/FlowState.md)\<`T`\>
+
+A new instance of [FlowState](/api/classes/FlowState.md).
+
+## Remarks
+
+State is the most common reactive primitive - a mutable container that notifies dependents
+when its value changes. Use `set()` to update the value and `get(t)` or `pick()` to read it.
+
+## Example
+
+```typescript
+const $count = state(0);
+
+effect((t) => {
+  console.log($count.get(t));
+});
+
+$count.set(1); // Logs: 1
+$count.set(n => n + 1); // Logs: 2
+```