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 v1.x? See the Upgrade Guide for migration instructions.

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"
effect.dispose(); // stop reacting

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.

Installation

# npm
npm install @ersbeth/picoflow

# pnpm
pnpm add @ersbeth/picoflow

# yarn
yarn add @ersbeth/picoflow

Documentation

For comprehensive guides and API documentation, visit the official website

Development

pnpm install
pnpm playwright:install   # once — downloads Chromium for the browser tests
pnpm test                 # watch Node tests
pnpm test:browser         # watch browser tests

See CONTRIBUTING.md for the full setup, the conventions and the release procedure. Known issues and their status are tracked in audits/FINDINGS.md; planned breaking changes in ROADMAP.md; vulnerability reporting in SECURITY.md.

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.