@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/.vitepress/config.mts

@@ -0,0 +1,110 @@
+import { defineConfig } from "vitepress";
+import { withMermaid } from "vitepress-plugin-mermaid";
+import typedocSidebar from "../api/typedoc-sidebar.json";
+
+export default withMermaid(
+	defineConfig({
+		title: "PicoFlow",
+		description: "Lightweight reactive dataflow library for TypeScript",
+		base: "/picoflow/",
+
+		mermaid: {},
+
+		head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
+
+		themeConfig: {
+			logo: "/logo.svg",
+
+			nav: [
+				{ text: "Guide", link: "/guide/introduction/getting-started" },
+				{ text: "Examples", link: "/examples/patterns" },
+				{ text: "API Reference", link: "/api/" },
+			],
+
+			sidebar: {
+				"/guide/": [
+					{
+						text: "Introduction",
+						items: [
+							{
+								text: "Getting Started",
+								link: "/guide/introduction/getting-started",
+							},
+							{ text: "Conventions", link: "/guide/introduction/conventions" },
+							{ text: "Concepts", link: "/guide/introduction/concepts" },
+							{ text: "Lifecycle", link: "/guide/introduction/lifecycle" },
+						],
+					},
+					{
+						text: "Primitives",
+						items: [
+							{ text: "Overview", link: "/guide/primitives/overview" },
+							{ text: "Signals", link: "/guide/primitives/signal" },
+							{ text: "States", link: "/guide/primitives/state" },
+							{ text: "Derivations", link: "/guide/primitives/derivations" },
+							{ text: "Effects", link: "/guide/primitives/effects" },
+							// { text: "Resources", link: "/guide/primitives/resources" },
+							// { text: "Streams", link: "/guide/primitives/streams" },
+							{ text: "Maps", link: "/guide/primitives/map" },
+							{ text: "Arrays", link: "/guide/primitives/array" },
+							// { text: "Constants", link: "/guide/primitives/constant" },
+						],
+					},
+					{
+						text: "Advanced",
+						items: [
+							{
+								text: "Disposal",
+								link: "/guide/advanced/disposal",
+							},
+							{
+								text: "Use with SolidJS",
+								link: "/guide/advanced/solidjs",
+							},
+							{
+								text: "Upgrade from v0.x",
+								link: "/guide/advanced/upgrading",
+							}
+						],
+					},
+				],
+
+				"/examples/": [
+					{
+						text: "Examples",
+						items: [
+							{ text: "Common Patterns", link: "/examples/patterns" },
+							{ text: "Code Examples", link: "/examples/examples" },
+						],
+					},
+				],
+
+				"/api/": [
+					{
+						text: "API Reference",
+						items: typedocSidebar,
+					},
+				],
+			},
+
+			socialLinks: [
+				{ icon: "gitlab", link: "https://gitlab.com/ersbeth-web/picoflow" },
+			],
+
+			search: {
+				provider: "local",
+			},
+
+			editLink: {
+				pattern:
+					"https://gitlab.com/ersbeth-web/picoflow/-/edit/main/docs/:path",
+				text: "Edit this page on GitLab",
+			},
+
+			footer: {
+				copyright:
+					"Copyright ©2025 <a href='https://gitlab.com/ersbeth/'>Ersbeth</a>",
+			},
+		},
+	}),
+);

package/docs/api/classes/FlowArray.md

@@ -0,0 +1,489 @@
+[@ersbeth/picoflow](/api/index.md) / FlowArray
+
+# Class: FlowArray\<T\>
+
+Defined in: [advanced/array.ts:46](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L46)
+
+Represents a reactive array.
+
+## Extends
+
+- [`FlowObservable`](/api/classes/FlowObservable.md)\<`T`[]\>
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Constructors
+
+### Constructor
+
+```ts
+new FlowArray<T>(value): FlowArray<T>;
+```
+
+Defined in: [advanced/array.ts:58](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L58)
+
+Creates an instance of FlowArray.
+
+#### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `value` | `T`[] | `[]` | Initial array value. |
+
+#### Returns
+
+`FlowArray`\<`T`\>
+
+#### Overrides
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`constructor`](/api/classes/FlowObservable.md#constructor)
+
+## Properties
+
+| Property | Modifier | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="lastaction"></a> `$lastAction` | `public` | [`FlowState`](/api/classes/FlowState.md)\<[`FlowArrayAction`](/api/type-aliases/FlowArrayAction.md)\<`T`\>\> | Last action performed on the FlowArray. | [advanced/array.ts:51](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L51) |
+
+## 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)
+
+***
+
+### length
+
+#### Get Signature
+
+```ts
+get length(): number;
+```
+
+Defined in: [advanced/array.ts:72](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L72)
+
+Gets the current length of the array.
+
+##### Returns
+
+`number`
+
+The length of the array.
+
+## Methods
+
+### clear()
+
+```ts
+clear(): void;
+```
+
+Defined in: [advanced/array.ts:195](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L195)
+
+Clears all items from the array.
+
+#### Returns
+
+`void`
+
+***
+
+### dispose()
+
+```ts
+dispose(options?): void;
+```
+
+Defined in: [advanced/array.ts:211](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L211)
+
+Disposes the FlowArray and its items.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | \{ `self`: `boolean`; \} | Disposal options. |
+| `options.self?` | `boolean` | - |
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`dispose`](/api/classes/FlowObservable.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
+});
+```
+
+#### Inherited from
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`get`](/api/classes/FlowObservable.md#get)
+
+***
+
+### 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);
+});
+```
+
+#### Inherited from
+
+[`FlowObservable`](/api/classes/FlowObservable.md).[`pick`](/api/classes/FlowObservable.md#pick)
+
+***
+
+### pop()
+
+```ts
+pop(): void;
+```
+
+Defined in: [advanced/array.ts:133](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L133)
+
+Removes the last item from the array.
+
+#### Returns
+
+`void`
+
+***
+
+### push()
+
+```ts
+push(item): void;
+```
+
+Defined in: [advanced/array.ts:122](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L122)
+
+Appends an item to the end of the array.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `item` | `T` | The item to append. |
+
+#### Returns
+
+`void`
+
+***
+
+### set()
+
+```ts
+set(items): void;
+```
+
+Defined in: [advanced/array.ts:91](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L91)
+
+Replaces the entire array with new items.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `items` | `T`[] | The new array of items. |
+
+#### Returns
+
+`void`
+
+***
+
+### setItem()
+
+```ts
+setItem(index, item): void;
+```
+
+Defined in: [advanced/array.ts:107](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L107)
+
+Replaces an item at a specific index.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `index` | `number` | The index of the item to replace. |
+| `item` | `T` | The new item. |
+
+#### Returns
+
+`void`
+
+***
+
+### shift()
+
+```ts
+shift(): void;
+```
+
+Defined in: [advanced/array.ts:159](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L159)
+
+Removes the first item from the array.
+
+#### Returns
+
+`void`
+
+***
+
+### splice()
+
+```ts
+splice(
+   start, 
+   deleteCount, ...
+   newItems): void;
+```
+
+Defined in: [advanced/array.ts:176](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L176)
+
+Changes the content of the array.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `start` | `number` | The starting index. |
+| `deleteCount` | `number` | Number of items to remove. |
+| ...`newItems` | `T`[] | New items to add. |
+
+#### Returns
+
+`void`
+
+***
+
+### 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)
+
+***
+
+### unshift()
+
+```ts
+unshift(item): void;
+```
+
+Defined in: [advanced/array.ts:148](https://gitlab.com/ersbeth-web/picoflow/-/blob/a6cd2e5702b60b87a8efe22e2fe7d2ce3b0ccca4/src/advanced/array.ts#L148)
+
+Inserts an item at the beginning of the array.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `item` | `T` | The item to insert. |
+
+#### Returns
+
+`void`
+
+***
+
+### 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)