@ersbeth/picoflow 2.0.2 → 2.0.3

package/README.md

@@ -21,6 +21,16 @@ yarn add @ersbeth/picoflow
 
 For comprehensive guides and API documentation, visit the [official website](https://ersbeth-web.gitlab.io/picoflow/)
 
+## AI Coding Agents
+
+Picoflow ships a [`SKILL.md`](SKILL.md) with the npm package, matching the exact version you have
+installed. If you use an agent skill tool (e.g. [`npx skills`](https://github.com/vercel-labs/skills)),
+install it straight from `node_modules` after installing the package:
+
+```bash
+npx skills add ./node_modules/@ersbeth/picoflow
+```
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

package/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: picoflow
+description: Use when writing, reviewing, or debugging TypeScript code that uses @ersbeth/picoflow's reactive primitives (signal, state, constant, derivation, writableDerivation, array, map, subscribe). Covers the explicit tracking model (get(t) vs pick()), disposal, and the mistakes that silently break reactivity.
+---
+
+# PicoFlow
+
+PicoFlow is a reactive dataflow library with **explicit tracking** — there is no automatic dependency
+detection like in Vue, MobX or Solid. Follow the rules below whenever you write or review code that
+imports from `@ersbeth/picoflow`.
+
+## The core rule: `.get(t)` vs `.pick()`
+
+Every primitive is read one of two ways:
+
+- **`.get(t)`** — tracked read. `t` is a `FlowTracker`, only available inside a `derivation()` callback
+  or a `subscribe()` data function. Registers the caller as a dependent.
+- **`.pick()`** — untracked async read (`Promise<T>`). Use outside reactive contexts (event handlers,
+  one-off reads) when you don't want to react to future changes.
+
+Never call `.get(t)` outside a derivation/subscribe callback — `t` isn't available there. Never use
+`.pick()` inside a derivation/subscribe when you actually want reactivity — it silently creates no
+dependency, which is a common source of "why doesn't this update" bugs.
+
+Reactive values are named with a `$` prefix (`$count`, `$user`) by convention — keep this when writing
+new code in a PicoFlow codebase, and use it to tell reactive values apart from plain ones at a glance.
+
+## Choosing a primitive
+
+| Need | Use | Not |
+|---|---|---|
+| Event with no payload (trigger a refresh, coordinate actions) | `signal()` | `state()` for a flag no one reads |
+| Mutable value that changes over time | `state(value)` | `constant` (if it truly never changes) |
+| Expensive one-time computation, never changes | `constant(() => ...)` — **always a function**, computed lazily on first access | a plain top-level `const` if nothing reactive reads it |
+| Pure computed value from other primitives | `derivation((t) => ...)` | putting side effects in it — use `subscribe` |
+| A derivation that occasionally needs manual override | `writableDerivation((t) => ...)` | — |
+| List with fine-grained mutation tracking | `array(initial?)` | `state(someArray)` if you need per-operation tracking |
+| Key-value store with fine-grained mutation tracking | `map(initial?)` | `state(someMap)` if you need per-operation tracking |
+| Running side effects (DOM, network, storage, logging) in reaction to changes | `.subscribe()` (single primitive) or `subscribe()` (multiple) | `derivation` — derivations must stay pure |
+
+Async variants exist for state/constant/derivation/writableDerivation (`stateAsync`, `constantAsync`,
+`derivationAsync`, `writableDerivationAsync`) — same rules, the held value is a `Promise<T>`, and reads
+of a still-pending value are handled automatically (surfaced via `subscribe()`'s optional `onPending`
+callback) rather than needing manual `await`/try-catch inside a derivation.
+
+## Mistakes to catch when reviewing PicoFlow code
+
+- **Side effects inside `derivation()`** (logging, API calls, mutating outside state) — derivations must
+  be pure; move the side effect into a `subscribe()`.
+- **Mutating a collection returned by `.get(t)`/`.pick()` in place**, e.g. `items.push(x)` on a picked
+  array, or `user.name = 'x'` on a picked object, then relying on it to update — this changes nothing
+  observable. Always produce a new array/object (`items.map(...)`, `{ ...user, name: 'x' }`), or use the
+  primitive's own mutation methods (`$array.push(x)`, `$map.update(k, v)`).
+- **`constant(value)` with a direct value instead of a function** — constants always take an initializer
+  function (`constant(() => value)`), enforcing lazy evaluation. A direct value is a v1 pattern (see below).
+- **Not disposing subscriptions/primitives** (`.dispose()`) when they're no longer needed — every
+  `subscribe()`/`.subscribe()` call keeps running until disposed; forgetting this in code that creates
+  subscriptions repeatedly (e.g. once per component instance, once per request) is a memory leak.
+- **Creating a subscription inside another subscription's callback** — it re-creates one on every run
+  and leaks. Combine into a single `subscribe()` whose data function reads all the needed primitives.
+- **A `subscribe()`/`.subscribe()` callback that calls `.set()` on a primitive it also reads** — infinite
+  loop.
+- **Using `add()`/`update()` on `array`/`map` without checking preconditions** — `array.update(index, x)`
+  throws if the index is out of bounds; `map.add(key, x)` throws if the key exists; `map.update(key, x)`
+  throws if it doesn't. Check first (`.pick()`) or branch on it, don't assume.
+- **Tracking the whole `array`/`map` (`.subscribe()`/`.get(t)`) when only specific operations matter** —
+  prefer `$collection.$lastAction.subscribe(...)` (a discriminated union with a `type` field) to react
+  only to the mutation kind you care about, instead of re-running on every change.
+
+## Recognizing pre-v2 (deprecated) API usage
+
+If existing code uses any of these, it predates PicoFlow v2 — flag it and suggest migrating (full guide:
+https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html):
+
+- `effect((t) => ...)` — removed. Replace with `.subscribe()` (single primitive) or `subscribe()` (multiple).
+- `$map.$lastAdded` / `$lastUpdated` / `$lastDeleted` — replaced by a single `$map.$lastAction` signal
+  with a `type` discriminant.
+- `$array.setItem(index, value)` — renamed to `$array.update(index, value)`.
+- `constant(value)` with a direct (non-function) value.
+
+## Minimal example (the shape most PicoFlow code follows)
+
+```typescript
+import { state, derivation, subscribe } from '@ersbeth/picoflow'
+
+const $count = state(0)
+const $isEven = derivation((t) => $count.get(t) % 2 === 0)
+
+const effect = subscribe(
+  (t) => ({ count: $count.get(t), even: $isEven.get(t) }),
+  (data) => console.log(`Count is ${data.count}, which is ${data.even ? 'even' : 'odd'}`),
+)
+
+$count.set((n) => n + 1) // atomic updater form, prefer it when the new value depends on the current one
+
+// when done:
+effect.dispose()
+$count.dispose()
+```
+
+## Further reference
+
+This file covers the rules needed to write and review correct PicoFlow code. For the full generated API
+reference (every method, accessor, inherited member) or the guide with longer walkthroughs, see
+https://ersbeth-web.gitlab.io/picoflow/ (or its condensed single-file form at
+https://ersbeth-web.gitlab.io/picoflow/llms-full.txt).

package/package.json

@@ -1,8 +1,12 @@
 {
     "name": "@ersbeth/picoflow",
-    "version": "2.0.2",
+    "version": "2.0.3",
     "description": "Minimal Dataflow library for TypeScript",
     "type": "module",
+    "files": [
+        "dist",
+        "SKILL.md"
+    ],
     "exports": {
         "types": "./dist/types/index.d.ts",
         "default": "./dist/picoflow.js"

package/.gitlab-ci.yml

@@ -1,24 +0,0 @@
-image: node:20
-
-cache:
-  paths:
-    - node_modules/
-    - .pnpm-store/
-
-variables:
-  PNPM_VERSION: 8
-
-before_script:
-  - npm install -g pnpm@${PNPM_VERSION}
-  - pnpm install
-
-pages:
-  stage: deploy
-  script:
-    - pnpm docs:build
-    - cp -r docs/.vitepress/dist public
-  artifacts:
-    paths:
-      - public
-  rules:
-    - if: $CI_COMMIT_BRANCH == "main"

package/.vscode/settings.json

@@ -1,5 +0,0 @@
-{
-    "files.associations": {
-        "*.json": "jsonc"
-    }
-}

package/CHANGELOG.md

@@ -1,94 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [2.0.0] - 2026-01-11
-
-### 🚨 BREAKING CHANGES
-
-This is a major API refinement focusing on consistency, performance, and clarity. **This release is not backward compatible with v1.x.**
-
-**Migration required:** Please see the [Migration Guide](docs/guide/advanced/migration-v2.md) for detailed migration instructions. Most projects can be migrated in 30-60 minutes.
-
-### Changed
-
-- **`effect()` API removed:** The global `effect()` function has been replaced with `subscribe()` and `.subscribe()` methods for better consistency and clarity
-  - Single primitive subscriptions: use `$primitive.subscribe((value) => { ... })`
-  - Multiple dependencies: use `subscribe((t) => ({ ... }), (data) => { ... })`
-- **FlowMap fine-grained tracking simplified:** Replaced three separate signals (`$lastAdded`, `$lastUpdated`, `$lastDeleted`) with a single unified `$lastAction` signal
-  - Actions now use a discriminated union type with `type` field
-  - Action properties renamed for clarity: `value` → `addedValue`, `setValue`, `removedValue`
-  - Added `set` and `clear` action types
-- **FlowArray method renamed:** `setItem()` → `update()` for consistency with FlowMap
-- **Constant initialization:** Constants now always require a function initializer `constant(() => value)`, enforcing lazy evaluation
-- **Improved type naming:** Internal `TrackingContext` is now properly exported as `FlowTracker` interface
-
-### Added
-
-- **`subscribe()` function:** New global function for creating side effects with multiple dependencies
-- **`.subscribe()` method:** Convenient method on primitives for single-value subscriptions
-- **`FlowEffect` interface:** Return type for all subscription operations, providing consistent disposal pattern
-- **Enhanced FlowMap actions:** Added `set` and `clear` action types to `$lastAction` for complete operation tracking
-
-### Removed
-
-- **`effect()` function:** Replaced by `subscribe()` and `.subscribe()` methods
-- **FlowMap separate signals:** `$lastAdded`, `$lastUpdated`, `$lastDeleted` replaced by unified `$lastAction`
-- **FlowArray `setItem()` method:** Renamed to `update()`
-
-### Benefits
-
-- **Clearer API:** Distinction between primitives and side effects (subscriptions) is more explicit
-- **Better performance:** Single `$lastAction` signal reduces overhead in collection tracking
-- **More consistent:** Unified naming across FlowArray and FlowMap operations
-- **Simpler mental model:** `subscribe()` clearly indicates side effects vs pure derivations
-
----
-
-## [1.0.0] - 2025-11-29
-
-### 🚨 BREAKING CHANGES
-
-This is a major rewrite of PicoFlow's API. The library now uses an explicit tracking context instead of getter/watcher functions. **This release is not backward compatible with v0.x.**
-
-**Migration required:** Please see [UPGRADING.md](UPGRADING.md) for detailed migration instructions. Most projects can be migrated in 15-30 minutes.
-
-### Changed
-
-- **Complete API overhaul:** Effects and derivations now receive a `TrackingContext` parameter (`t`) instead of separate `get` and `watch` functions
-- **New method-based API:** Observables use `.get(t)` for reactive reads instead of `get(observable)`
-- **Signals use `.watch(t)`:** Signal tracking now uses `$signal.watch(t)` instead of `watch($signal)`
-- **Chained syntax:** Enable natural chaining like `$parent.get(t).child.get(t)` instead of nested `get(get($parent).child)`
-- **Simpler architecture:** Removed internal methods (`_watch`, `_watchFrom`, `_getFrom`) in favor of direct method overrides
-
-### Added
-
-- **`TrackingContext` class:** New explicit tracking context for reactive computations
-- **`pick()` method:** Read observable values without creating dependencies - `$state.pick()` is equivalent to `$state.get(null)`
-- **Explicit control:** Granular control over what is tracked vs. untracked in the same reactive scope
-- **Mixed reactive/non-reactive reads:** Use `.get(t)` for reactive dependencies and `.pick()` for snapshot reads in the same effect
-
-### Removed
-
-- **`FlowGetter` type:** Replaced by `TrackingContext` parameter
-- **`FlowWatcher` type:** Replaced by `TrackingContext` parameter
-- **Implicit getter/watcher functions:** No longer passed to effects and derivations
-
-### Benefits
-
-- **More readable:** Code is more explicit about what creates dependencies
-- **Better chaining:** Natural fluent API for nested observables
-- **Simpler codebase:** Cleaner internal architecture with fewer abstractions
-- **More flexible:** Fine-grained control over reactive tracking per read operation
-
----
-
-## [0.2.4] - Previous Release
-
-(Version 0.x releases used the getter/watcher API)
-

package/biome.json

@@ -1,47 +0,0 @@
-{
-    "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
-    "vcs": {
-        "enabled": true,
-        "clientKind": "git",
-        "useIgnoreFile": true
-    },
-    "files": {
-        "includes": ["**", "!!**/dist"]
-    },
-    "formatter": {
-        "enabled": true,
-        "indentStyle": "space",
-        "indentWidth": 4,
-        "lineWidth": 120
-    },
-    "linter": {
-        "enabled": true,
-        "rules": {
-            "recommended": true,
-            "complexity": {
-                "noStaticOnlyClass": "off"
-            },
-            "nursery": {
-                "useExhaustiveSwitchCases": "error",
-                "noFloatingPromises": "error",
-                "noMisusedPromises": "error"
-            },
-            "suspicious": {
-                "useAwait": "error"
-            }
-        }
-    },
-    "javascript": {
-        "formatter": {
-            "quoteStyle": "double"
-        }
-    },
-    "assist": {
-        "enabled": true,
-        "actions": {
-            "source": {
-                "organizeImports": "on"
-            }
-        }
-    }
-}

package/docs/.vitepress/config.mts

@@ -1,145 +0,0 @@
-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: "Primitives",
-                        items: [
-                            {
-                                text: "Overview",
-                                link: "/guide/primitives/overview",
-                            },
-                            {
-                                text: "Signals",
-                                link: "/guide/primitives/signal",
-                            },
-                            { text: "Constants", link: "/guide/primitives/constant" },
-
-                            { text: "States", link: "/guide/primitives/state" },
-                            {
-                                text: "Derivations",
-                                link: "/guide/primitives/derivations",
-                            },
-                            { text: "Maps", link: "/guide/primitives/map" },
-                            { text: "Arrays", link: "/guide/primitives/array" },
-                            {
-                                text: "Side Effects",
-                                link: "/guide/primitives/effects",
-                            },
-                        ],
-                    },
-                    {
-                        text: "Advanced",
-                        items: [
-                            {
-                                text: "Use with SolidJS",
-                                link: "/guide/advanced/solidjs",
-                            },
-                            {
-                                text: "Upgrade to v2",
-                                link: "/guide/advanced/migration-v2",
-                            },
-                            {
-                                text: "Upgrade to v1",
-                                link: "/guide/advanced/migration-v1",
-                            },
-                            // {
-                            //     text: "Lifecycle",
-                            //     link: "/guide/introduction/lifecycle",
-                            // },
-                            // {
-                            //     text: "Disposal",
-                            //     link: "/guide/advanced/disposal",
-                            // },
-                            // {
-                            //     text: "Architecture",
-                            //     link: "/guide/advanced/architecture",
-                            // },
-                        ],
-                    },
-                ],
-
-                // "/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/functions/array.md

@@ -1,35 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / array
-
-# Function: array()
-
-```ts
-function array<T>(initial?): FlowArray<T>;
-```
-
-Defined in: [api/nodes/collections/flowArray.ts:153](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/collections/flowArray.ts#L153)
-
-Creates a reactive array with mutation methods and fine-grained action tracking.
-
-The array starts with the provided initial items (or empty if none provided). All mutation methods
-(push, pop, splice, etc.) notify dependents and emit detailed action information to `$lastAction`.
-Use the array itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
-reactivity to specific mutation types. Useful for reactive lists, collections, or any data that
-needs array-like operations with automatic change propagation.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initial?` | `T`[] | Optional initial array of items |
-
-## Returns
-
-[`FlowArray`](/api/interfaces/FlowArray.md)\<`T`\>
-
-A FlowArray with reactive mutation methods

package/docs/api/functions/constant.md

@@ -1,33 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / constant
-
-# Function: constant()
-
-```ts
-function constant<T>(initializer): FlowConstant<T>;
-```
-
-Defined in: [api/nodes/sync/flowConstant.ts:31](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowConstant.ts#L31)
-
-Creates a constant reactive value that initializes lazily and never recomputes.
-
-The initializer function runs once on first access, and the result is cached permanently.
-Unlike state or derivations, constants never react to changes - they represent immutable values
-in the reactive graph. Useful for expensive one-time computations or static configuration.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `initializer` | [`InitFunction`](/api/type-aliases/InitFunction.md)\<`T`\> | Function that computes the constant value on first access |
-
-## Returns
-
-[`FlowConstant`](/api/interfaces/FlowConstant.md)\<`T`\>
-
-A FlowConstant that provides read-only access to the cached value

package/docs/api/functions/constantAsync.md

@@ -1,69 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / constantAsync
-
-# Function: constantAsync()
-
-## Call Signature
-
-```ts
-function constantAsync<T>(value): FlowConstantAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowConstantAsync.ts:32](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowConstantAsync.ts#L32)
-
-Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
-
-The promise or async initializer executes once on first access, and the resolved value is cached permanently.
-While the promise is pending, any reactive computation that accesses the value will receive PendingError and
-automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
-reactive values, such as loading configuration or fetching initial data.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | `Promise`\<`T`\> | Promise to resolve, or async function that returns a promise on first access |
-
-### Returns
-
-[`FlowConstantAsync`](/api/interfaces/FlowConstantAsync.md)\<`T`\>
-
-A FlowConstantAsync that provides read-only access to the resolved value
-
-## Call Signature
-
-```ts
-function constantAsync<T>(initializer): FlowConstantAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowConstantAsync.ts:33](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowConstantAsync.ts#L33)
-
-Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
-
-The promise or async initializer executes once on first access, and the resolved value is cached permanently.
-While the promise is pending, any reactive computation that accesses the value will receive PendingError and
-automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
-reactive values, such as loading configuration or fetching initial data.
-
-### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `initializer` | [`InitFunctionAsync`](/api/type-aliases/InitFunctionAsync.md)\<`T`\> |
-
-### Returns
-
-[`FlowConstantAsync`](/api/interfaces/FlowConstantAsync.md)\<`T`\>
-
-A FlowConstantAsync that provides read-only access to the resolved value

package/docs/api/functions/derivation.md

@@ -1,34 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / derivation
-
-# Function: derivation()
-
-```ts
-function derivation<T>(compute): FlowDerivation<T>;
-```
-
-Defined in: [api/nodes/sync/flowDerivation.ts:39](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/sync/flowDerivation.ts#L39)
-
-Creates a derived reactive value that automatically recomputes when dependencies change.
-
-The compute function runs when any tracked dependency changes, and the result is cached until the next change.
-Access reactive values within the compute function to establish dependencies automatically. The derivation
-computes lazily on first access and then reactively thereafter. Use for derived data that should stay
-synchronized with source state.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `compute` | [`DerivationFunction`](/api/type-aliases/DerivationFunction.md)\<`T`\> | Function that accesses dependencies and computes the derived value |
-
-## Returns
-
-[`FlowDerivation`](/api/interfaces/FlowDerivation.md)\<`T`\>
-
-A FlowDerivation that provides read-only access to the computed value

package/docs/api/functions/derivationAsync.md

@@ -1,34 +0,0 @@
-[@ersbeth/picoflow](/api/index.md) / derivationAsync
-
-# Function: derivationAsync()
-
-```ts
-function derivationAsync<T>(compute): FlowDerivationAsync<T>;
-```
-
-Defined in: [api/nodes/async/flowDerivationAsync.ts:40](https://gitlab.com/ersbeth-web/picoflow/-/blob/4e864254f0eac72524c3be40b9e41d799a16e020/src/api/nodes/async/flowDerivationAsync.ts#L40)
-
-Creates an async derived value that automatically recomputes when dependencies change.
-
-The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
-the function runs again and returns a new promise. The resolved value is cached until the next change.
-While the promise is pending, reactive computations that access this value receive PendingError and automatically
-retry once resolved. Use for derived data from async sources like filtered API results or computed database queries.
-
-## Type Parameters
-
-| Type Parameter |
-| ------ |
-| `T` |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `compute` | [`DerivationFunctionAsync`](/api/type-aliases/DerivationFunctionAsync.md)\<`T`\> | Async function that accesses dependencies and returns a promise of the derived value |
-
-## Returns
-
-[`FlowDerivationAsync`](/api/interfaces/FlowDerivationAsync.md)\<`T`\>
-
-A FlowDerivationAsync that provides read-only access to the resolved computed value