Picoflow

Picoflow is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, (asynchronous) derivations, effects, and reactive maps/arrays. Picoflow uses an explicit tracking context to automatically track reactive dependencies.

Upgrading from v2.x? See the v2 → v3 migration guide. Coming from v1.x, take the v1 → v2 guide first.

import { derivation, state, 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) }),
    ({ count, even }) => console.log(`${count} is ${even ? "even" : "odd"}`),
);
// logs "0 is even"

$count.set(1); // logs "1 is odd", on the next task
effect.dispose(); // stop reacting

Reactivity is flushed asynchronously: a write schedules a flush rather than running effects on the spot, so writes made in one turn are batched and an assertion placed directly after .set() sees the old value. Await the value (await $count.pick()) when you need the graph settled.

Dependencies are tracked explicitly: $count.get(t) both reads the value and registers it as a dependency of the enclosing derivation/subscribe, using the t (tracker) each one receives. Nothing is tracked implicitly and there is no untrack() to opt back out of — if a read doesn't go through .get(t), it isn't a dependency. That is the library's main departure from most reactive libraries, and its main safety property: what an effect depends on is always visible at the call site.

Requirements

The schedulers use Promise.withResolvers(), so picoflow needs Node ≥ 22, or Chrome ≥ 119, Safari ≥ 17.4, Firefox ≥ 121 in the browser. There is no fallback: on an older runtime the failure is immediate, on the first primitive you create.

On the type side, the published declarations reference TypeScript's esnext.disposable lib, which is what types the using support: they need TypeScript ≥ 5.5, where the reference is honoured whatever your own lib setting is. On TypeScript 5.2 to 5.4 the lib exists but the reference is ignored, so add esnext.disposable to your lib if you pin it and keep skipLibCheck: false.

Installation

# npm
npm install @ersbeth/picoflow

# pnpm
pnpm add @ersbeth/picoflow

# yarn
yarn add @ersbeth/picoflow

Entry points

| Import | What it gives you | Needs | |---|---|---| | @ersbeth/picoflow | the reactive core — every primitive, and the whole everyday API | nothing | | @ersbeth/picoflow/solid | from(), adapting a picoflow value into a SolidJS Resource | the optional solid-js peer | | @ersbeth/picoflow/inspect | inspect(), graphSnapshot(), formatGraph(), enableTrace() — reading the graph to answer "why did this not update?" | nothing |

The root never resolves solid-js, so an application that does not use the converter installs nothing but picoflow. The inspector is a separate subpath so that an application that never inspects anything never bundles it.

import { formatGraph } from "@ersbeth/picoflow/inspect";

console.log(formatGraph()); // every live node, its status and its edges

Documentation

For comprehensive guides and API documentation, visit the official website

Project

Picoflow is developed at gitlab.com/ersbeth-web/picoflow. Known issues and their status are tracked as GitLab issues, and vulnerability reporting is covered by the repository's SECURITY.md. Contributions are welcome — its CONTRIBUTING.md has the setup and conventions.

AI Coding Agents

Picoflow ships a SKILL.md with the npm package, matching the exact version you have installed. If you use an agent skill tool (e.g. npx skills), install it straight from node_modules after installing the package:

npx skills add ./node_modules/@ersbeth/picoflow

License

This project is licensed under the MIT License.