Reflex

Fine-grained reactivity for TypeScript with explicit effect scheduling.

@volynets/reflex is the application-facing Reflex package: signals, lazy derived state, effects, events, and disposable models in a small, framework-independent API.

State writes are synchronous. Computed values update lazily on read. You choose when invalidated effects run: explicitly with flush(), after a batch, or immediately.

Install

npm install @volynets/reflex

Quick start

import { computed, createRuntime, effect, signal } from "@volynets/reflex";

const runtime = createRuntime();
const [count, setCount] = signal(0);
const doubled = computed(() => count() * 2);

const stop = effect(() => {
  console.log(doubled());
});

setCount(1);
runtime.flush(); // logs 2

stop();

effect() runs once when created. With the default "flush" strategy, later runs wait for runtime.flush(). Signals and computed values always return their latest value without flushing.

Scheduling

const runtime = createRuntime({ effectStrategy: "flush" });

| Strategy | Invalidated effects run | | --------- | -------------------------------------------------- | | "flush" | when runtime.flush() is called | | "sab" | after the outermost batch settles | | "eager" | synchronously at the next runtime-settled boundary |

Use runtime.batch(fn) or the exported batch(fn) to group related writes. Writes and invalidations remain synchronous, and reads inside the batch observe the latest values. A reactive batch only coalesces host-visible settled notifications. Effect timing remains a scheduler policy selected by effectStrategy.

The eager strategy does not run an effect from the invalidation callback itself. It queues the effect during propagation and drains that queue once the runtime is settled; an effect that writes state produces another settled checkpoint.

API

• State: signal, computed, memo, effect, reaction, watch
• Control: createRuntime, batch, flush, untracked
• Events: event, map, filter, merge, switchMap, flatten, scan, hold
• Models: createModel, own, isModel

Most application code should depend on @volynets/reflex. The lower-level @volynets/reflex-runtime package is intended for renderer, scheduler, and tooling integrations.

License

MIT