@ersbeth/picoflow 2.3.1 → 3.0.0

package/README.md

@@ -2,7 +2,8 @@
 
 **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](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html) for migration instructions.
+> **Upgrading from v2.x?** See the [v2 → v3 migration guide](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v3.html).
+> Coming from v1.x, take the [v1 → v2 guide](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v2.html) first.
 
 ```typescript
 import { derivation, state, subscribe } from "@ersbeth/picoflow";
@@ -16,10 +17,14 @@ const effect = subscribe(
 );
 // logs "0 is even"
 
-$count.set(1); // logs "1 is odd"
+$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
@@ -30,6 +35,11 @@ its main safety property: what an effect depends on is always visible at the cal
 
 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
 
 ```bash
@@ -43,20 +53,35 @@ pnpm add @ersbeth/picoflow
 yarn add @ersbeth/picoflow
 ```
 
-## Documentation
+## Entry points
 
-For comprehensive guides and API documentation, visit the [official website](https://ersbeth-web.gitlab.io/picoflow/)
+| 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 |
 
-## Development
+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.
 
-```bash
-pnpm install
-pnpm playwright:install   # once — downloads Chromium for the browser tests
-pnpm test                 # watch Node tests
-pnpm test:browser         # watch browser tests
+```typescript
+import { formatGraph } from "@ersbeth/picoflow/inspect";
+
+console.log(formatGraph()); // every live node, its status and its edges
 ```
 
-See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the full setup, the conventions and the release procedure. Known issues and their status are tracked in [`audits/FINDINGS.md`](../../audits/FINDINGS.md); planned breaking changes in [`ROADMAP.md`](../../ROADMAP.md); vulnerability reporting in [`SECURITY.md`](../../SECURITY.md).
+## Documentation
+
+For comprehensive guides and API documentation, visit the [official website](https://ersbeth-web.gitlab.io/picoflow/)
+
+## Project
+
+Picoflow is developed at [gitlab.com/ersbeth-web/picoflow](https://gitlab.com/ersbeth-web/picoflow).
+Known issues and their status are tracked as
+[GitLab issues](https://gitlab.com/ersbeth-web/picoflow/-/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
 
@@ -70,4 +95,4 @@ npx skills add ./node_modules/@ersbeth/picoflow
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](LICENSE).

package/SKILL.md

@@ -14,10 +14,18 @@ imports from `@ersbeth/picoflow`.
 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.
+  or a `subscribe()` data function. Registers the caller as a dependent. The type is opaque: a tracker
+  is received, never constructed, so hand-rolling one to read synchronously is a compile error — use
+  `.value` or `.latest` below for that.
 - **`.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.
 
+Two synchronous getters exist for *looking* without taking part: **`.value`** returns a snapshot
+`{ status, data? }` — `data` is present only when `status === "resolved"`, so narrow on it — and
+**`.latest`** returns the last resolved value (`T | undefined`) even while pending or dirty. Neither
+computes a lazy derivation, throws, or tracks; they are for debuggers, dev panels and quick checks,
+not a replacement for `.pick()` when you need the value to be fresh.
+
 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.
@@ -27,8 +35,11 @@ new code in a PicoFlow codebase, and use it to tell reactive values apart from p
 Every factory also takes an optional trailing `{ name?: string }`, e.g. `state(0, { name: "$count" })` —
 pass the same `$`-prefixed name so it shows up in error messages (`[PicoFlow] Primitive "$count" is
 disposed`) instead of the unnamed generic message. Errors are also typed (`PicoFlowDisposedError`,
-`PicoFlowCycleError`, `PicoFlowInternalError`, all extending `PicoFlowError`), so `catch` blocks can
-discriminate with `instanceof` instead of matching on message text.
+`PicoFlowCycleError`, `PicoFlowInternalError`, `PicoFlowPreconditionError` — the collection
+preconditions and `from()`'s input check — all extending `PicoFlowError`, which is never thrown
+itself), so `catch` blocks can discriminate with `instanceof` instead of matching on message text. A computation that throws a
+non-`Error` value has it wrapped once (`new Error(String(thrown), { cause: thrown })`), so `pick()`,
+`get(t)`, `.value.error` and `onError` all hand you the same `Error` instance.
 
 ## Choosing a primitive
 
@@ -39,14 +50,19 @@ discriminate with `instanceof` instead of matching on message text.
 | 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) => ...)` | — |
+| A derivation that must recompute without waiting for a reader (pay for an expensive compute during the flush, keep a cache warm, observe `status` with no value reader) | `derivation((t) => ..., { eager: true })` — derivations are lazy by default; the option also exists on the writable/async variants | an `effect`/`subscribe` reading it just to force the computation |
 | 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 |
+| An external resource re-created whenever a value changes (socket, timer, listener) | `derivation<R>((t, previous) => ...)` — read the dependencies, release `previous`, return the next one; after `dispose()`, release `$r.latest` by hand | `subscribe()` holding the resource in a closure — there is no per-run `onCleanup()`, by design |
 
 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.
+callback) rather than needing manual `await`/try-catch inside a derivation. Handing a promise to a sync
+primitive is a compile error whose message names the async variant to use (`NotPromise<T>` resolves to
+the `PromiseNotAllowed` literal); the check is one level deep — a promise nested inside an object is not
+detected, so reach for the async variant deliberately.
 
 ## Mistakes to catch when reviewing PicoFlow code
 
@@ -54,8 +70,15 @@ callback) rather than needing manual `await`/try-catch inside a derivation.
   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)`).
+  observable. `array()`/`map()` reads are the live store typed `readonly T[]`/`ReadonlyMap<K, V>`, so
+  the compiler catches the first case. Always produce a new array/object (`items.map(...)`,
+  `{ ...user, name: 'x' }`), or use the primitive's own mutation methods (`$array.push(x)`,
+  `$map.setAt(k, v)`). An `equals` comparator does **not** fix this: both sides are the same reference, so it still reports "unchanged".
+- **A state that legitimately holds `NaN`, left on the default comparator** — change detection is `===`,
+  and `NaN !== NaN`, so every write re-runs the whole downstream subtree. Pass
+  `state(value, { equals: Object.is })`. The same option takes a structural comparator
+  (`{ equals: (a, b) => a.id === b.id }`) when writes routinely produce a *fresh* object with equal
+  fields. Value primitives only — `array()`, `map()` and `signal()` ignore `equals`.
 - **`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
@@ -70,23 +93,53 @@ callback) rather than needing manual `await`/try-catch inside a derivation.
 - **`subscribe(fn)` with no `onError`, and no global `onFlushError()` handler installed** — any exception
   thrown inside `fn` is only logged via `console.error` by default; install `onFlushError((error) => ...)`
   once at startup if the application needs to observe or report these instead of the default logging.
-- **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.
+- **`$x.set(fn)` expecting an updater, or `$x.update(fn)` on an errored state** — `set()` only replaces
+  (a function passed to it is stored as the value); `update(fn)` derives from the stabilised current
+  value and is skipped, leaving the error in place, when the state holds an error. Recover with `set()`
+  first. Collections have no `update(fn)` at all: use their mutation methods, or `set(items)`.
+- **Using `add()`/`setAt()`/`splice()` on `array`/`map` without checking preconditions** —
+  `array.setAt(index, x)` throws if the index is out of bounds; `map.add(key, x)` throws if the key
+  exists; `map.setAt(key, x)` throws if it doesn't; `array.splice(start, deleteCount, …)` throws unless
+  both bounds are integers addressing the array as it stands — it does not clamp them the way
+  `Array.prototype.splice` does, so `splice(-1, 1)` and `splice(i, Infinity)` are errors, not the
+  from-the-end and to-the-end forms. Check first (`.pick()`) or branch on it, don't assume. Writes
+  (`set`, `setAt`, `push`, `unshift`, `add`) return nothing; removals (`pop`, `shift`, `splice`,
+  `clear`, `delete`) return what they removed. The item a `setAt()` replaced is in `$lastAction`
+  (`clearedItem` / `clearedValue`), not in its return value.
 - **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):
+## Recognizing outdated API usage
+
+### Predates v3 (full guide: https://ersbeth-web.gitlab.io/picoflow/guide/advanced/migration-v3.html)
+
+- `$x.set((prev) => ...)` — the updater form is now `$x.update((prev) => ...)`. **Flag this first.** On a
+  typed primitive the compiler catches it, but on a `state<unknown>`, a state that legitimately holds a
+  function, or in plain JavaScript, `set()` stores the function *as the value* and nothing complains.
+- `$array.update(index, item)` / `$map.update(key, value)` — renamed `setAt(...)`, and the matching
+  `$lastAction` type `"update"` is now `"setAt"`, so a `case "update":` branch is dead code.
+- Binding the result of `setAt()` — writes return nothing now; only removals return what they removed.
+  The displaced entry is on `$lastAction` as `clearedItem` / `clearedValue`.
+- `$x.disposed` — removed. Read `$x.status === "disposed"`, and drop the guard entirely where it only
+  protected a `dispose()` call, which is idempotent.
+- `$array.length` — removed. `$items.get(t).length` to depend on it, `$items.latest?.length` to read it
+  passively.
+- `import { from } from '@ersbeth/picoflow'` — `from()` lives at `@ersbeth/picoflow/solid`.
+- `set`, `update` or `refresh` reached on a `constant()` or `derivation()` through a cast — they no
+  longer exist at runtime, so the call yields `undefined` rather than working.
+- Mutating the array or map handed back by a read — reads now return the live backing store, typed
+  read-only, so this changes the collection with no notification. Copy it (`[...$items.latest ?? []]`).
+
+### Predates v2 (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
+- `$map.$lastAdded` / `$lastUpdated` / `$lastDeleted` — replaced by a single `$map.$lastAction` stream
   with a `type` discriminant.
-- `$array.setItem(index, value)` — renamed to `$array.update(index, value)`.
+- `$array.setItem(index, value)` — renamed `$array.update(index, value)` in v2, and again to
+  `$array.setAt(index, value)` in v3.
 - `constant(value)` with a direct (non-function) value.
+- `TrackingContext` — the exported type is `FlowTracker`.
 
 ## Minimal example (the shape most PicoFlow code follows)
 
@@ -101,13 +154,74 @@ const effect = subscribe(
   (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
+$count.update((n) => n + 1) // derive from the current value; set(v) replaces without looking at it
 
 // when done:
 effect.dispose()
 $count.dispose()
 ```
 
+## Testing code that uses PicoFlow
+
+Reactivity is flushed asynchronously, so a synchronous assertion right after `.set()` always fails.
+Await the value (`await $count.pick()`) or poll (`await vi.waitFor(() => ...)`) before asserting.
+
+Scheduling is process-global: work queued by one test can still be waiting when the next one starts,
+and an `onFlushError()` handler stays installed until replaced. Call `reset()` from an `afterEach` to
+put the scheduler back to its just-started state — both queues emptied, any scheduled flush cancelled,
+the error handler back to `console.error`.
+
+`dispose()` is idempotent, so cleanup never needs a guard — and to ask whether something was released,
+read `$x.status` and compare against `"disposed"` (values report `resolved`/`pending`/`error`/`dirty`
+otherwise; effects report `idle`/`queued`). For a primitive whose
+lifetime is one test, `using $count = state(0)` disposes it on block exit even if an assertion throws
+first — which a trailing `dispose()` would skip. (The `using` syntax needs Node 24 or a transpiler;
+most test runners transpile already.)
+
+```typescript
+import { reset } from '@ersbeth/picoflow'
+
+afterEach(() => {
+  reset()
+})
+```
+
+`reset()` **discards** queued work rather than running it: primitives created earlier stay usable, but
+any recomputation that was waiting is lost, and those nodes only recompute if something notifies them
+again. It cancels pending reactivity — it is not a way to force it to complete. Use `pick()` for that.
+
+## Debugging: inspecting the graph
+
+When something "doesn't update", read the graph rather than guessing. The inspector lives behind its
+own subpath, `@ersbeth/picoflow/inspect`, and is passive by construction — it reads `status` and the
+same snapshot `.value` exposes and walks the dependency registries, never `get()`/`pick()`/`subscribe()`,
+so looking at a graph cannot change what it then does. It works on disposed primitives too.
+
+```typescript
+import { formatGraph, graphSnapshot, inspect } from '@ersbeth/picoflow/inspect'
+
+console.log(formatGraph())        // the whole graph as text — for a browser console
+inspect($count)                   // one node: kind, name, status, value, dependencies, dependents
+graphSnapshot()                   // every node as JSON: same data, for a tool or an agent
+```
+
+- **"My effect never ran."** `inspect(effect).dependencies` empty where you expected a source is the
+  `pick()`-instead-of-`get(t)` mistake, seen directly: the edge was never created.
+- **"Something is leaking."** `graphSnapshot().summary` counts `orphans` — nodes with no edge in
+  either direction. A count that climbs as the application runs is undisposed nodes piling up.
+- **"In what order did this happen?"** `enableTrace()` records the engine's own steps (notify, queue,
+  execute, resolve, effect run) into a bounded buffer; `trace.events` reads them back, and a feedback
+  loop ends in a `cycle-error` preceded by the effects that caused it. Call `trace.dispose()` when done.
+
+Two things to expect rather than report as bugs: a **lazy derivation never read has computed nothing**,
+so it shows `dirty`, no value and no dependencies (create it with `{ eager: true }`, or exercise the
+app first); and a node's `value` in a dump is a short **rendered string**, present only when the status
+is `resolved` — introspection describes the graph, it does not hand out its data.
+
+Name the nodes you expect to debug. Every factory takes `{ name }`, and as of v3 so does
+`subscribe(data, onData, onError?, onPending?, { name })` — an unnamed node is only ever labelled
+`derivation#12`.
+
 ## Further reference
 
 This file covers the rules needed to write and review correct PicoFlow code. For the full generated API