/reactive-engine

name: reactive-engine
description: >-
  Manage application state with the @virtuoso.dev/reactive-engine-* package family. Use this skill when (1) defining reactive state
  with Cell, Stream, Trigger, or Resource nodes, (2) wiring React components through EngineProvider, useCellValue, useCellValues, or
  usePublisher, (3) fetching data with Query and Mutation from reactive-engine-query, (4) routing with Route, Layout, and Guard from
  reactive-engine-router, (5) persisting cells with linkCellToStorage, (6) architecting a component or library on top of the engine,
  (7) observing or troubleshooting propagation with describeNode, observeDiagnostics, useEngineDiagnostics, or
  useRemoteEngineDiagnostics, or (8) any task involving Engine, pub, sub, getValue, combine, pipe, link, changeWith, the e namespace,
  missing or duplicate emissions, unexpected distinct suppression, or the error "No active engine found".

Reactive Engine

A reactive state system built on a graph of typed nodes. Five packages compose:

| Package | Provides | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `@virtuoso.dev/reactive-engine-core` | Nodes (`Cell`, `Stream`, `Trigger`, `Resource`, `DerivedCell`), `Engine`, operators, combinators, the `e` namespace | | `@virtuoso.dev/reactive-engine-react` | `EngineProvider`, state hooks, local and remote diagnostic hooks | | `@virtuoso.dev/reactive-engine-query` | `Query` and `Mutation` data fetching on top of nodes | | `@virtuoso.dev/reactive-engine-router` | `Route`, `Layout`, `Guard`, `Router` — routes are nodes | | `@virtuoso.dev/reactive-engine-storage` | `linkCellToStorage` (localStorage / sessionStorage / cookie) |

It also powers `@virtuoso.dev/data-table` internally — the same concepts apply when remote-controlling the table, and data-table's architecture is the reference for building on the engine ([building-on-the-engine](references/core/05.building-on-the-engine.md)).

Mental model: nodes are definitions, engines hold state

Node constructors return inert references (symbols at runtime), defined at module scope with a `$` suffix. They hold no state. An `Engine` instance activates nodes lazily on first use and owns their values — two engines using the same node have independent state. This is what makes engine-based libraries reusable: one module-scope graph, one engine per component instance.

import { Cell, Stream, Engine, e } from '@virtuoso.dev/reactive-engine-core'

const count$ = Cell(0)
const engine = new Engine()
engine.sub(count$, (value) => console.log('count:', value))
engine.pub(count$, 1) // logs 'count: 1'

Node types — pick by statefulness:

| Node | State | Use for | | ------------------------------- | ------------------------------ | --------------------------------------------- | | `Cell(initial, distinct?)` | Stateful, has a current value | App state, settings | | `DerivedCell(initial, source$)` | Stateful, tracks a source | Read-only computed state | | `Stream<T>(distinct?)` | Stateless, emits values | Events, commands | | `Trigger()` | Stateless, valueless | "Something happened" signals (refetch, reset) | | `Resource(factory)` | Factory-initialized per engine | Objects needing setup/disposal |

Nodes are distinct by default using **reference equality** (`===`): publishing the same reference (or an equal primitive) does not re-emit. Always publish new references from updates (`new Map(old)`, spread). Pass `false` to always emit, or a comparator `(prev, next) => boolean` (true = equal = suppress); `prev` is `undefined` on first emission.

The three API flavors (most important distinction)

The same verbs exist in three forms — using the wrong one is the main source of errors:

| Flavor | Examples | Where | Effect | | ------------------------ | ------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------- | | Module-scope combinators | `link`, `pipe`, `sub`, `changeWith`, `combine` / `e.*` | Anywhere, incl. module top level | Deferred wiring, applied once per engine when the nodes activate | | Engine instance methods | `engine.pub`, `engine.sub`, `engine.getValue` | Wherever you hold an engine | Immediate, on that engine | | Context-bound utilities | standalone `pub`, `getValue`, `pubIn` / `e.pub`, ... | Only inside subscription callbacks and node inits | Acts on the currently executing engine |

Calling a context-bound utility elsewhere throws `No active engine found. You can use getValue only in the context of node subscription callbacks.` — fix by using `engine.*` methods, React hooks, or moving the code into a subscription. Note the asymmetry: standalone `sub`/`link`/`changeWith` are safe at module scope (they defer); standalone `pub`/`getValue` are not.

The `e` export bundles all combinators, operators, and context utilities into one namespace — idiomatic for wiring blocks:

e.link(
  e.pipe(