@zakkster/lite-signal

@zakkster/lite-signal

Zero-GC reactive graph for hot paths. Object-pooled nodes, versioned push-pull propagation, 32-bit modular epochs. Built for 16ms render budgets and 1MB extension bundles.

4th of 15 on the community reactivity benchmark -- and the only zero-GC engine in the field

On the independent js-reactivity-benchmark (Andrii Volynets' fork; 15 reactive libraries, 47 tests), lite-signal places 4th overall by geomean (81.6) -- within noise of 5th-place Preact Signals (83.0, a 1.7% gap), behind only three push-eager engines: alien-signals, reflex, and @reactively.

It is the only object-pooled, zero-GC engine in the entire field, and it gets that result without giving up glitch-freedom or lazy evaluation. Against the mainstream reactivity libraries it leads decisively:

lite-signal finishes top-3 on 18 of the 47 tests and is the outright fastest of all 15 on manyEffectsFromOneSource (1 source -> many effects, fan-out) and manySourcesIntoOneComputedEffectWithDirect (many sources -> one computed, fan-in) -- the aggregation shapes that dominate live dashboards, scoreboards, and HUDs. The three engines ahead of it are all push-eager designs that allocate on the hot path; lite-signal is the only top-4 finisher that allocates nothing in steady state. (Note: this suite measures reactivity libraries -- Vue's reactivity core, MobX, Solid, Preact Signals, etc. -- not full UI frameworks like React or Angular.)

npm install @zakkster/lite-signal

import { signal, computed, effect, batch } from "@zakkster/lite-signal";

const count = signal(0);
const double = computed(() => count() * 2);

effect(() => console.log("double is", double()));
// -> double is 0

count.set(21);
// -> double is 42

Synchronous, glitch-free, push-pull. No microtask queue, no allocations after warm-up, no surprises.

Table of contents

• Why this exists
• What you get
• The case for object pooling
• Architecture in one diagram
• How a write propagates
• API reference
• Watchers
• Capacity, growth, and the link ceiling
• Edge cases pinned down
• Benchmarks
• Testing strategy
• What this is not
• Ecosystem
• Browser and runtime support
• Integration recipes
• Conformance
• FAQ
• npm scripts

Why this exists

Reactive graph libraries are now table-stakes for UI work. They all do the same thing: track reads, mark dirty, re-run on change. The differences live in the hot path.

lite-signal was built under three constraints simultaneously:

1. No allocation after warm-up. A 60fps Twitch overlay can't tolerate GC pauses. set, peek, and re-runs touch no heap.
2. Zero microtasks. Effects flush synchronously in the same call stack as set(). There is no scheduler queue. Predictable cause-and-effect makes debugging tractable.
3. Survive forever. A multi-day extension session can issue billions of writes. Internal versions use 32-bit modular arithmetic -- the engine never overflows.

Other libraries hit two of three. None of the ones I measured hit all three.

flowchart LR
  A[set called] --> B[bump globalVersion<br/>via 32-bit add]
  B --> C[markDownstream<br/>iterative DFS, pre-allocated stack]
  C --> D[push observable effects<br/>to active queue buffer]
  D --> E{batch depth zero?}
  E -- yes --> F[flushEffects<br/>double-buffered swap]
  E -- no --> G[return,<br/>queue drains on batch close]
  F --> H[per-effect: pull deps,<br/>compare versions, re-run if dirty]
  H --> I[user code]

No microtask between B and I. No promise, no queueMicrotask. Just call stack.

What you get

• signal(value, { equals? }) -- root reactive cell. set, peek, update, subscribe.
• computed(fn, { equals? }) -- memoized derivation. Lazy. Pulls deps on read.
• effect(fn, { scheduler? }) -- side-effect runner. Returns a dispose function.
• dispose(api) -- universal disposal for signals, computeds, and effect handles. Cross-registry calls are silent no-ops.
• batch(fn) -- defer effect flush until the outermost batch closes.
• untrack(fn) -- read without subscribing.
• isTracking() -- true iff a read right now would subscribe (for lazy-allocation wrappers).
• onCleanup(fn) -- register teardown for the current computation. Works in effects and computeds.
• createRegistry(config) -- isolated pool for tests, plugins, sandboxing.
• stats() -- pool occupancy snapshot. Used by the demo and easy to wire into perf overlays.
• CapacityError -- thrown when a fixed-size pool is exhausted under the "throw" policy.

Full type definitions ship in Signal.d.ts and are referenced from package.json. Every public symbol has JSDoc.

The case for object pooling

Architecture in one diagram

flowchart TB
  subgraph Pools[Pre-allocated object pools]
    NP[ReactiveNode pool<br/>default 1024]
    LP[ReactiveLink pool<br/>default 4096]
  end

  subgraph Graph[Reactive graph]
    S1((signal))
    S2((signal))
    C1[[computed]]
    C2[[computed]]
    E1{effect}
    S1 -->|link| C1
    S2 -->|link| C1
    C1 -->|link| C2
    C2 -->|link| E1
  end

  subgraph Hot[Hot-path state]
    GV[globalVersion<br/>32-bit modular int]
    MS[markStack<br/>iterative DFS buffer]
    Q1[effectQueueA]
    Q2[effectQueueB<br/>double-buffered]
  end

  NP -.->|alloc / free| Graph
  LP -.->|alloc / free| Graph
  Graph --> GV
  Graph --> MS
  Graph --> Q1
  Graph --> Q2

How a write propagates

sequenceDiagram
  participant U as User code
  participant S as signal
  participant Mark as markDownstream
  participant Q as effectQueue
  participant Flush as flushEffects
  participant Eff as effect body

  U->>S: signal.set(value)
  S->>S: equals(prev, next) ? return
  S->>S: bump node.version + globalVersion
  S->>Mark: walk sub list (iterative DFS)
  Mark->>Q: push observable effects (FLAG_QUEUED)
  Note over Mark,Q: stale computeds left dirty<br/>(pulled lazily on next read)
  S->>Flush: batchDepth == 0 ? flush
  loop until queue empty
    Flush->>Eff: for each effect: re-pull deps,<br/>compare versions, run if dirty
    Eff-->>Flush: maybe re-queue (handled by buffer B)
    Flush->>Flush: swap buffers A<->B, repeat
  end
  Note over Flush: maxFlushPasses=100<br/>guards against runaway loops

API reference

Top-level

import {
  // Core
  signal, computed, effect,
  batch, untrack, onCleanup, isTracking,
  // Registry / lifecycle
  createRegistry, setDefaultRegistry, dispose, destroy,
  stats, CapacityError,
  // Introspection (1.1.4 / 1.1.5 / 1.2.1)
  hasObservers, observeObservers,
  forEachObserver, forEachSource,
  nodeId, describe,
  forEachOwned, ownerOf,        // 1.2.1
  // Debug hook (1.2.1)
  onGraphMutation,
  // Watchers
  watch, when, whenAsync,
} from "@zakkster/lite-signal";

The top-level functions route to a default registry created on import. For isolated sandboxes (tests, plugins, multi-tenant SDKs), use createRegistry directly.

Signal

const s = signal(initial, { equals?: (a, b) => boolean });

s();              // tracked read
s.peek();         // untracked read
s.set(value);     // notify downstream
s.update(fn);     // s.set(fn(s.peek()))
const off = s.subscribe(value => { ... });
off();            // unsubscribe

equals defaults to Object.is (so NaN notifies once, -0/+0 are distinct). Pass () => false to force every write to propagate, or your own deep-equal to skip redundant updates.

Computed

const c = computed(() => s() * 2, { equals?: (a, b) => boolean });

c();              // tracked read, lazy evaluation
c.peek();         // untracked read, may still compute
const off = c.subscribe(value => { ... });

Computeds cache by version, not by value. Reading a clean computed (one whose dependencies haven't changed since its evalVersion) is O(deps) -- it still walks the dep list to check versions, then returns the cached value. The equals option short-circuits downstream propagation when the new computed value matches the old.

Effect

const dispose = effect(() => {
  console.log(s());
  onCleanup(() => { /* fires on next run + final dispose */ });
}, {
  scheduler?: (runEffect) => void  // optional, see below
});

dispose();

Effects run once eagerly on creation, then again whenever any tracked dependency changes. Dispose returns the node to the pool. If a scheduler is provided, the runner is handed to the scheduler instead of executing inline -- useful for batching reactive updates into requestAnimationFrame, microtasks, or your own frame loop.

Batch

batch(() => {
  s1.set(1);
  s2.set(2);
  s3.set(3);
}); // effects flush exactly once at the end

Nestable. Effects only flush on the outermost close.

Untrack

const value = untrack(() => s());  // read without subscribing

Useful inside computeds/effects when you need a current value but don't want it as a dependency.

isTracking

function makeLazyField(initial) {
  let s = null, value = initial;
  return {
    get() {
      if (isTracking()) {
        if (s === null) s = signal(value);   // allocate only when subscribed
        return s();
      }
      return value;
    },
    set(v) { value = v; if (s !== null) s.set(v); }
  };
}

Returns true iff a read right now would record a dependency on the current registry -- an observer body is on the stack AND tracking is enabled. Mirrors the engine's own read-trap check (both flags), so it correctly returns false inside untrack, inside subscribe callbacks, inside onCleanup bodies, inside watch / when callbacks, and outside any observer.

For wrapper libraries (lite-store, lite-query, lite-form) gating lazy allocation on the read path. Per-registry -- call registry.isTracking() if your signals live in a non-default registry.

Observer-lifecycle introspection

// Start a ticker only while something is actually watching a derived value.
const now = signal(performance.now());
const unobserve = observeObservers(now, {
  onConnect:    () => startRAF(),   // 0 -> 1 observers
  onDisconnect: () => stopRAF(),    // 1 -> 0 observers
});

hasObservers(now);                  // O(1): is anyone subscribed right now? (a peek doesn't count)

// Walk the live graph in either direction (lite-devtools):
forEachObserver(sum, d => console.log(d.kind, d.value));  // subscribers of `sum`
forEachSource(sum,   d => console.log(d.kind, d.value));  // dependencies of `sum`

// 1.2.1: walk the owner tree (cascade-disposal domains)
forEachOwned(effectHandle, d => console.log(d.kind, d.id));  // observers this one will cascade-dispose
ownerOf(innerComputedDesc);                                  // descriptor of the enclosing effect/computed

Eight functions (top-level + per-registry) -- four in 1.1.4, two in 1.1.5, two more in 1.2.1 -- for auto-pausing wrappers and graph inspection:

• hasObservers(handle) -> boolean -- O(1) (node.headSub !== null). The auto-pause predicate.
• observeObservers(handle, { onConnect?, onDisconnect? }) -> unobserve -- fires on the 0->1 and 1->0 observer transitions after registration (transition-only -- no immediate fire if already observed). Re-tracking a persistently-read source does not churn. This is the hook lite-time / lite-raf use to run a clock only while a derived value is watched. Throws TypeError on a non-handle.
• forEachObserver(handle, fn) / forEachSource(handle, fn) -- walk subscribers / dependencies; fn gets a { id, kind, value } descriptor (kind in "signal" | "computed" | "effect"; id added in 1.1.5). No-op on a non-handle.
• nodeId(handle) -> number | undefined (1.1.5) -- the node's stable per-allocation id; the dedupe key for graph traversal. undefined on a non-handle.
• describe(handle) -> { id, kind, value } | undefined (1.1.5) -- the handle's own descriptor. Re-walkable: pass it back into any forEach* to recurse the graph. undefined on a non-handle.
• forEachOwned(handle, fn) (1.2.1) -- walk this node's owned children (lifetime-binding edges from the 1.2 owner tree). The dep/sub edges show DATA FLOW; the owner edges show LIFETIME BINDING -- when this handle re-runs or is disposed, every owned child is cascade-disposed. No-op on a non-handle, top-level handle with no children, or stale handle.
• ownerOf(handle) -> { id, kind, value } | undefined (1.2.1) -- descriptor of handle's owner, or undefined for top-level / stale handles. The inverse of forEachOwned: walks UP the owner tree.

The surface is gated by an internal lifecycle counter: when nothing is being observed, the hot path adds a single branch-predicted count !== 0 check in link alloc/free and nothing else -- zero steady-state cost when unused.

Stale-handle guard (1.2.1)

The 1.2.0 owner tree makes the engine recycle pool slots autonomously: when an effect or computed re-runs, every observer it created in its previous body is cascade-disposed. Holding a stale handle stopped being a user error and became routine. Pre-1.2.1, the introspection surface plus peek() resolved NODE_PTR ungated and would happily report the recycled slot's NEW resident -- wrong id, wrong value, wrong edges.

1.2.1 generation-checks every entry point that resolves a handle (the same ABA discipline dispose() always had):

• nodeId, describe, hasObservers, forEachObserver, forEachSource, forEachOwned, ownerOf, signal.peek(), computed.peek(), signal()/computed() read, signal.set() -> return undefined / are no-ops on stale handles.
• observeObservers throws TypeError (matching the existing non-handle contract).

Descriptors returned by describe() and the forEach* walkers are themselves gen-stamped, so the documented "descriptors are re-walkable handles" contract survives the guard: a fresh descriptor walks, one held across a recycle correctly goes stale.

onGraphMutation (1.2.1)

// Push-based devtools / studio integration. Single listener, allocation-free dispatch.
const unsub = onGraphMutation((opcode, intA, intB) => {
  switch (opcode) {
    case 1: devtools.onNodeCreate(intA, intB);  break;   // intA = node.id, intB = node.flags
    case 2: devtools.onNodeDispose(intA);       break;   //   ditto (cascade-disposed children included)
    case 3: devtools.onLinkAdd(intA, intB);     break;   // intA = source.id, intB = target.id
    case 4: devtools.onLinkRemove(intA, intB);  break;
    case 5: devtools.onRecompute(intA);         break;   // before each effect re-run / computed re-eval
  }
});

// Stop listening -- restores the previous registration (or null), engine returns to zero-cost state.
unsub();

A registry-level (and top-level) debug hook for push-based tooling -- the connection point lite-devtools 1.1 and lite-studio 1.1 use to walk away from polling. Single nullable listener; every fire point in the engine is one if (mutationHook !== null) mutationHook(opcode, intA, intB):

• Zero cost when unregistered -- branch-predicted null check per mutation point, same as the lifecycle counter pattern.
• Allocation-free when registered -- three integers, no objects, no closures. Worst-case measured cost on a dynamic-retracking torture loop (11.4M events over 400K writes) is +29% -- a debug-mode tax proportional to event volume, paid only while a consumer is attached.
• LIFO stacking -- onGraphMutation(a); onGraphMutation(b); unsubB() restores a. Used by lite-devtools 1.1 to multiplex multiple consumers behind one engine registration.

Listener contract: observe only -- never throw, never mutate the graph from inside. The hook fires synchronously inside mutation points; mutating from the callback corrupts the in-flight operation. Wrap any downstream work that could touch the registry in a microtask.

onCleanup

effect(() => {
  const id = setInterval(tick, 100);
  onCleanup(() => clearInterval(id));
});

Registers a teardown for the current computation. Fires before every re-run and once on dispose. Supports multiple cleanups per scope (they're stored as a flat list, run in registration order). Works inside computeds too -- useful for canceling async work when memos become stale.

dispose

const s = signal(0);
const c = computed(() => s() * 2);
const e = effect(() => { /* ... */ });

dispose(s);   // signal -> returns the node to the pool
dispose(c);   // computed -> same, also unlinks its upstreams
dispose(e);   // effect handle -> identical to calling e()

One function for all three primitives. Idempotent. Cross-registry calls are silent no-ops -- each registry holds a private Symbol("node_ptr") keyed on its own nodes, so passing a signal from registry A to registry B.dispose() won't corrupt either pool. Passing an unrelated value (null, 42, {}) is also a safe no-op. Passing an arbitrary function invokes it (the effect-handle contract).

The effect dispose handle (const dispose = effect(...)) is still a plain function -- you can call it directly. dispose() exists to unify the call site when you're managing a heterogeneous bag of reactive resources, which is the common case for component teardown and tests.

createRegistry

const r = createRegistry({
  maxNodes:          1024,       // default
  maxLinks:          4 * 1024,   // default = maxNodes * 4
  maxFlushPasses:    100,        // default
  onCapacityExceeded: "throw"    // default. Other: "grow"
});

const s = r.signal(0);
const e = r.effect(() => s());
r.destroy();                     // reset all pools, invalidate generations

createRegistry is the unit of isolation. Two registries share no state -- useful for multi-tenant code, plugin sandboxes, and tests that need a fresh world.

setDefaultRegistry(r) swaps the registry used by top-level helpers. Use sparingly; intended for test setup.

Capacity, growth, and the link ceiling

flowchart LR
  A[allocator hits empty pool] --> B{policy?}
  B -- "throw" --> C[CapacityError]
  B -- "grow" --> D[double pool size]
  D --> E{new size > 16× original?}
  E -- yes --> F[CapacityError<br/>link ceiling]
  E -- no --> G[allocate, continue]

Watchers

@zakkster/lite-signal ships three composable watcher primitives, all built from effect + untrack -- no engine extensions, no per-watcher flag in ReactiveNode. The core stays small; the surface stays useful.

watch(source, callback, options?)

Fires the callback whenever the source's projected value changes. The callback receives (newValue, oldValue, stop) -- calling stop() from inside the callback disposes the watcher.

import { signal, watch } from "@zakkster/lite-signal";

const count = signal(0);

// Basic -- observe forever
const stop = watch(count, (next, prev) => {
    console.log(`${prev} -> ${next}`);
});

count.set(1);  // logs: 0 -> 1
stop();        // manual dispose

Self-disposing watcher -- declarative termination from inside the callback:

watch(status, (next, prev, stop) => {
    if (next === "ready") {
        initialize();
        stop();  // detach after first "ready"
    }
});

Immediate option -- fires once on registration with oldValue = undefined:

watch(theme, (v) => applyTheme(v), { immediate: true });

Raw getter equality -- watch uses Object.is internally to avoid spurious fires when a dep mutation produces the same projected value:

const health = signal(10);
let deathLog = 0;
watch(() => health() <= 0, (isDead) => { deathLog++; });

health.set(9);  // isDead is still false -- no fire
health.set(8);  // same -- no fire
health.set(0);  // crossed -- fires once with (true, false)

Without this guard, the callback would fire on every health mutation regardless of whether isDead changed. Wrapping the source in computed() would achieve the same via the computed's own equality check -- the guard makes that wrapping optional.

when(predicate, callback)

Fires callback exactly once when predicate first returns a truthy value, then auto-disposes. If the predicate is already truthy at registration, fires synchronously.

import { when } from "@zakkster/lite-signal";

when(() => user.isAuthenticated, () => {
    navigate("/dashboard");
});

The returned dispose function can cancel before the predicate fires:

const cancel = when(() => slowApi.ready, () => start());
if (userBacked) cancel();

whenAsync(predicate)

! Hot-path warning

whenAsync calls new Promise(...) internally -- this is a heap allocation. Every call allocates a Promise object, an executor closure, and Promise infrastructure (resolve function, microtask state). Promises require heap allocation by the language spec; this cost is unavoidable.

Use for: high-level scene/UI orchestration, boot sequences, awaiting user input, level transitions. Anything that runs once or rarely.

NEVER use for: per-frame entity updates, render-loop logic, animation tick handlers, anywhere that runs at 60/120 fps. The Promise allocations will be visible in GC traces and will cause frame-time spikes under sustained load.

For zero-GC hot-path logic, use when with a callback.

Promise-returning variant of when. Composes with async/await for declarative async control flow against reactive state:

import { whenAsync } from "@zakkster/lite-signal";

async function bootSequence() {
    await whenAsync(() => config.loaded);
    await whenAsync(() => auth.ready);
    await whenAsync(() => db.connected);
    render();
}

The promise never rejects on its own -- if the predicate never becomes truthy, the promise never settles. For timeout semantics use Promise.race:

await Promise.race([
    whenAsync(() => api.ready),
    new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), 5000))
]);

Allocation profile

Honest accounting of where memory is spent in each primitive:

The "0 per fire" property for watch is deliberate engineering -- the inner untrack callback is hoisted to a single closure allocated once at registration, with currentNewValue as shared mutable state. If you read the source and wonder why we don't use a clean inline arrow function inside the effect body, this is the answer: doing it inline would allocate a fresh closure on every dep change, at 7,200 allocs per minute per watcher at 120 fps.

Tree-shaking

All three primitives live in a separate module (Watch.js) and are re-exported from the main entry (which binds them to its own effect/untrack, so there is exactly one engine instance). If your bundle doesn't import them, they won't appear in the output -- modern ESM tree-shaking (Vite, Rollup, esbuild) handles this reliably.

Edge cases pinned down

Benchmarks

Honest numbers, against the same workload, with anti-DCE sinks and verified effect execution. All measurements: Node 22, 2016-era Intel MacBook Pro (4 cores, ~10 yr old hardware), 20K iterations, one engine per cold process, median of 10 isolated runs. Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters. Numbers below are lite-signal @1.2.2 vs alien-signals on the same loop; the full five-framework comparison (incl. preact, vue-reactivity, solid across 34 reactive-suite tests) is in resultsReactive.txt. (These numbers use the corrected one-engine-per-process protocol -- the prior 1.2.0 table ran several engines in one process, which let nursery-allocating engines borrow a warm heap and polluted shared inline caches. 1.2.2 is drop-in over 1.2.0; the hot paths are byte-identical, so the table moves here are the measurement correction, not engine changes. The 1.2.0 single-process table is in git history.)

Reading the table: lite-signal's wins cluster exactly where its zero-GC design pays off -- the allocation-heavy dynamic shapes (DYNAMIC DAG +44%, SELECTIVE DAG +48%, SMALL SELECTIVE +31%), where alien-signals churns the nursery and lite's object pool allocates nothing, plus MUX +35% (fan-in aggregation). These are the patterns that dominate live UI workloads under input churn: dashboards, scoreboards, HUDs, leaderboards. On the cheap, low-allocation stable shapes (KAIROS, BROADCAST, wide app/dense) lite runs at parity with alien -- within a 4-7% band that is inside this old host's run-to-run noise. The one structural loss is DEEP CHAIN (-19%): on a 256-deep computed pipeline alien's flatter representation wins because the propagation path is long rather than wide.

On allocation pressure, lite-signal is alone in the zero-alloc band: ~0.3 KB of transient garbage on stable shapes across 20,000 iterations. The contrast is starkest on the dynamic DAGs -- lite allocates 9-13 MB (genuine retracking re-links) where alien-signals allocates 39-42 MB on the same shapes, and that allocation gap is the mechanism behind lite's +44-48% wins there once each engine is measured in isolation. preact ranges from ~220 KB to low-single-digit MB per stable loop, solid runs into single-digit megabytes. Negative "retained" numbers mean V8 reclaimed memory below the pre-bench baseline during the post-run forced GC -- no leaks anywhere.

Note on the +70.8 KB retained that lite-signal shows on KAIROS specifically: that's the pre-allocated pool sitting in memory holding the live graph (1002 nodes + ~2000 links). The pool is the working memory -- see the Case for object pooling section. On the other benches the graph is small enough that the same pool floats below baseline after GC.

The benchmark harness is in bench/benchmark.mjs; a full methodology write-up -- including the anti-DCE design, workload diagrams, variance discipline, reproducibility recipe, and a self-validation procedure for the harness itself -- lives in bench/README.md. It:

1. Writes every effect's output to a shared Float64Array(4096) exposed on globalThis -- V8 cannot prove these writes are dead.
2. Uses the client Solid runtime (solid-js/dist/solid.js), not the SSR stub Node resolves to by default. The default Node resolution silently no-ops effects, which is how earlier benchmarks across the ecosystem have reported Solid at ~50 GHz throughput.
3. Validates each lib's sink slot is non-zero after the timed loop and prints sink=[x] for each line. If you ever see sink=[ ], the run is invalid.

Run it yourself:

npm install --no-save alien-signals @preact/signals-core solid-js
npm run bench

Testing strategy

Three tiers, all reproducible.

Tier 1 -- Behavior (unit tests, fast)

npm test runs the suite in test/, covering:

• 01-core_test.mjs -- signal/computed/effect basics, equality semantics, NaN/+/-0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
• 02-topology_test.mjs -- diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (CycleError).
• 03-pool_test.mjs -- CapacityError under both "throw" and "grow" policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
• 05-scheduler_test.mjs -- scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), setDefaultRegistry, onCleanup inside computeds.
• 06-nested-objects_test.mjs -- array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
• 07-dispose_test.mjs -- unified dispose(api) across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
• 08-watch_test.mjs -- Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
• 09-conformance_test.mjs -- Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
• 10-is-tracking_test.mjs -- The isTracking() observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside untrack, subscribe callbacks, onCleanup bodies, and watch callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
• 11-adopted-reactive_test.mjs -- 24 engine-agnostic edge cases adopted from across the ecosystem: alien-signals' parent-child link-integrity regression (#226-228), equality-predicate corners (preact/solid/vue), signal.update(fn) functional setter (vue/solid), peek() non-subscription depth (preact/vue), and the subscribe behavioral contract (preact/mobx).
• 12-coverage_test.mjs -- 18 targeted exercises for public surface and hot-path branches the behavioral suites don't incidentally hit: top-level routing to the default registry, the computed clean-read short-circuit (markEpoch O(1) skip), dependency-set shrink severing the stale tail, error/structural edge paths, scheduler ABA across a recycled pool slot, and the v1.2 owner-tree paths (direct-child detach, cascade tolerates an already-freed child). Capability-gated via a runtime probe, so the same file runs unchanged across engines.
• 13-introspection_test.mjs -- The observer-lifecycle surface (1.1.4). 10 tests across 3 describe blocks: hasObservers (live observation reflects; a peek doesn't count), observeObservers auto-pause lifecycle (start-on-first / stop-on-last, no extra connect for a 2nd observer, re-observe fires again, no churn on re-track, conditional reads toggle honestly, transition-only registration, works for computeds), and forEachObserver/forEachSource enumeration (both directions; descriptor carries kind + value).
• 14-lifecycle-teardown_test.mjs -- Effect-teardown guards against the alien-signals@3.2.1 regressions (4 tests). A stopped effect must not re-subscribe to a signal read later in the same run; self-dispose must leave no orphaned link (clean activeLinks); a throwing setup must leave no live subscription; normal and dynamic re-tracking stay unaffected by the allocateLink eligibility gate.
• 15-owner-lazy-alloc_test.mjs -- Owner-adoption contract for the 1.2.0 owner tree (5 tests). A signal allocated lazily inside a computed/effect must not be owner-adopted (it survives the owner's re-run -- the lite-store/lite-form lazy-field shape) and sibling lazy signals must not cross-wire, while observers (nested effect/computed) are still auto-disposed on the owner's re-run.
• 16-alien-parity_test.mjs -- Differential regression guards (3 tests) reproducing the properties behind alien-signals@3.2.0 fixed bugs: reads inside a cleanup create no spurious dependencies (the dispose-cleanup fix); an inner-effect write does not block later propagation through a computed chain (#112); a dynamic dependency-set change stays correct under dirty-check (#109/#110).
• 17-reactivity_test.mjs -- Behavioral suite (~30 tests across 11 groups) mirroring universal signal-system bug classes: subscription lifecycle, cleanup ordering, stale-dependency tracking, batching/timing (incl. set-then-revert), equality cutoff (NaN/+/-0/custom), nested invalidation + glitch-free diamond, memory/retained nodes, the synchronous async-boundary, scheduler & loops (self-write termination, self-reading computed), and differential-review additions (cached computed errors, mid-batch pull, self-disposing getter, pooled-slot return). SSR hydration is a documented N/A -- lite has no DOM layer.
• 18-identity_test.mjs -- Node identity (1.1.5; 5 tests). Unique/stable ids; nodeId/describe return undefined for a non-handle; the descriptor's visible shape is { id, kind, value }; forEach* descriptors carry id and are re-walkable (nodeId/forEachSource accept a descriptor); identity walks are non-perturbing (add no observers).
• 19-v12-additions_test.mjs -- v1.2.0 release-prep regressions (24 tests across 8 suites). Shared peek (one closure per registry, identical reference across primitives, no tracking, two registries hold independent peeks). Owner-adoption rule (signals not adopted, computeds/effects adopted, cascade drains correctly). Pre-batch revert (signal-level, propagates through computeds, respects custom equals, nested batches, final-different-value still fires). Multi-throw aggregation (AggregateError with both errors carried, single-throw unwrapped, engine survives). CycleError via maxFlushPasses (default + custom). maxLinks config branch under throw and grow. Documented disposed-signal semantics (read undefined, set silent no-op, dispose idempotent). Scheduler-thunk ABA guard across a recycled pool slot.
• 20-axis-stress_test.mjs -- engine-invariant regression guards along eight orthogonal "axes" (16 tests across 9 suites). Pins lite-signal's actual contract on: batch semantics under exception (writes commit; pre-batch revert holds; effects see the post-throw value), connect/disconnect lifecycle re-entrancy (observeObservers from inside an onConnect, transition-only registration), untrack does NOT suppress owner adoption (a nested effect created via untrack is still owner-cascaded), untrack inside a computed body (no hidden dep leaks; tracked source re-evaluates), queue safety under self-dispose mid-flush (no UAF), value-dependent cycle detection (computed graph closes a cycle, CycleError thrown), nested-effect creation order (effects run synchronously on creation; immediately-stopped one still ran), synchronous flush (no scheduler in the default path; batch coalesces). Plus a bonus suite: 1,000 effect-create-then-dispose cycles return pool to baseline; dispose() idempotent; dispose() on foreign values safe.
• 21-perf-pins_test.mjs -- v1.2.1 construction-shape pins (6 tests). Locks the canonical handle shapes (signal 6 own props: peek/set/update/subscribe + NODE_PTR/NODE_GEN; computed 4: peek/subscribe + NODE_PTR/NODE_GEN) so a future "let's unify them" change has to be explicit. Locks the 1.2.1 ABA guards: detached const {set} = signal() keeps working on a LIVE signal; read() returns undefined and skips dep-tracking on a stale handle (no phantom subscription to the recycled slot); set() on a stale handle is a no-op across three corruption tiers (disposed slot, recycled slot, downstream propagation); peek() returns undefined for stale signal and computed handles.
• 22-mutation-hook_test.mjs -- 1.2.1 onGraphMutation semantics (12 tests across 2 suites). Registration: unsubscribe returns a function; null argument clears and the unsub restores the prior listener; non-function/non-null throws TypeError; multiple registrations stack LIFO; registries are isolated (no cross-talk). Opcode emission: 1 node-create fires with (id, flags) for signal (32) / computed (1) / effect (2); 2 node-dispose fires for cascade-disposed owned children; 3 link-add fires with (source.id, target.id) on dependency record; 4 link-remove fires when a dep-set flip severs the tail; 5 recompute fires on initial eval AND re-eval; the hook fires synchronously inside the mutation (listener sees its own event before the caller returns); payload is always three plain numbers -- no objects, no closures.
• 23-owner-introspection_test.mjs -- 1.2.1 owner-tree introspection + effect-disposer regression (22 tests across 4 suites). ownerOf: undefined for top-level / garbage input / stale handle; returns the enclosing effect's descriptor for a child created inside an effect body. forEachOwned: no-op for handles with no owned children / garbage input / stale handle; iterates owned children as {id, kind, value} descriptors. Gen-guarded introspection (ABA fix): nodeId / describe / hasObservers return undefined / false for stale handles; observeObservers throws TypeError; forEachObserver / forEachSource are no-ops; descriptors returned by describeNode are themselves gen-stamped so a descriptor obtained pre-recycle correctly walks as a no-op post-recycle (the "descriptors are re-walkable handles" contract survives the guard). Plus the 1.2.1 effect-dispose-handle fix: passing the effect's disposer directly to describe / nodeId / forEachSource / forEachOwned / ownerOf / hasObservers works as a first-class introspection handle (pre-fix it was a bare closure and returned undefined for a live effect); after fx() dispose the same handle correctly goes stale on every entry point; the disposer's NODE_GEN mirrors the effect node's birthGen exactly.
• 24-signalbox_test.mjs -- staged for v1.5.0; all 9 tests {skip: true} on 1.2.x. The signalBox / computedBox allocation-light handle API lands in 1.5.0; the suite is committed early so the surface is pinned and the skips are visible in the test count (the 10 skips on 1.2.2 are these 9 plus 1 architecturally-N/A SSR case in 17-reactivity).
• 25-devtools-real-boot_test.mjs -- Devtools/Studio contract (10 tests). Boots the actual Devtools.js against the 1.2.2 engine and exercises all 19 Devtools exports plus the 10 symbols Studio imports from Devtools. Pins the ghost contract: heavy introspection (graph walk, owner-tree, observer descriptors) adds zero nodes to the live graph. Catches the real-rig failure mode where importing the package by its own name from a repo whose package.json declares name: "@zakkster/lite-signal" resolves to the published build instead of the local engine.
• 26-free-list-invariant_test.mjs -- the 1.2.2 audit's cleanliness pins (3 invariant tests + 1 targeted coverage test). Asserts directly -- by inspecting freshly-allocated nodes through the documented describe() -> NODE_PTR introspection protocol -- that the ReactiveNode constructor and the fresh-pool-growth path initialize the ten fields the audit removed from createNode to identical values, so the deleted writes were defending against a state the engine cannot produce on a clean free list. The 4th test covers the swallow-on-self-dispose-then-throw branch in pullComputed (the path that lifted branch coverage from 98.07% to 98.43%).

npm test

Tier 2 -- Memory (allocation-free verification)

npm run test:gc runs test/04-zero-gc_test.mjs with --expose-gc:

• 100,000 set() calls on a graph with effects retain < 200 KB of heap.
• 1,000 create/dispose cycles retain < 50 KB.
• Batched writes do not increase retained heap monotonically.
• Deep-chain propagation through 256 nodes stays under a tight steady-state budget.

If these fail, something allocates in the hot path and we want to find it before publish.

npm run test:gc

Tier 3 -- Performance (comparative benchmark)

npm run bench runs the comparative benchmark (9 scenarios -- stable fan-in/out + dynamic/layered DAGs) against alien-signals (results.txt). npm run bench-reactive runs the cross-framework reactivity suite vs alien-signals, preact, vue-reactivity, and solid (resultsReactive.txt). Output is plain text -- easy to copy into PRs and changelogs.

npm run bench

Tier 4 -- Torture soaks (crash detection under chaos)

bench/torture/ contains three soak harnesses that build large randomised graphs (1,500 / 7,500 / 3,300 nodes) and run mixed fuzz workloads -- leaf writes, batched writes, computed rewires, effect rewires, nested-batch + untrack reads, and microtask-scheduled async flushes -- for 5-10 seconds. These are not perf benchmarks. The numbers they print (ops/sec) reflect random workload composition, not engine throughput; the existing bench/benchmark.mjs is the canonical perf harness. What the soaks DO assert, with a non-zero exit code on failure:

• zero thrown exceptions during the run, and
• after teardown, activeNodes / activeLinks return to the leaf-only baseline (the dispose path is sound under sustained churn).

node --expose-gc bench/torture/graph-fuzzer.mjs     # 10s random-DAG fuzz, 1500 nodes
node --expose-gc bench/torture/torture-soak.mjs     #  5s high-volume churn, 7500 nodes
node --expose-gc bench/torture/scheduler-bench.mjs  # 10s microtask-scheduled, 3300 nodes

Run any of them with TORTURE_SECONDS=N for a longer soak. Indicative numbers from a development host (post-teardown pool returns to baseline in all three):

npm run verify   # test + test:gc + a sanity bench

Performance Trade-offs & Topology Scaling

What this is not

• A virtual DOM, JSX runtime, or rendering library. It's the substrate. Plug it under whatever rendering layer you like.
• A general-purpose state container. No time-travel, no devtools integration, no serialization. (Build those on top if you need them.)
• A perfect fit for every workload. On 256-deep computed pipelines (DEEP CHAIN) alien-signals is still a bit faster -- its flatter representation pays off when the propagation path is long rather than wide. (Through 1.1.2 this caveat also covered chaotic, high-fan-in read order; 1.1.4's retracking rewrite closed that -- those shapes are now parity-or-ahead.) lite-signal is at its best on the fan-in / fan-out / wide-memo and dynamic-churn patterns that dominate animation loops, HUDs, and dashboards.
• A library for the server. It works in Node, but there's no SSR story. Use it on the client.

Ecosystem

A growing family of zero-GC, ESM-only, sub-2KB packages built on lite-signal. All MIT, all by @zakkster.

State & data

• @zakkster/lite-store -- Fine-grained reactivity for objects & arrays via Proxy. Direct mutation; lazy per-key signals (allocated only on first tracked read); proxy identity preserved across reads; cycle-safe disposal walk.
• @zakkster/lite-resource -- Async state as a signal. resource(source, fetcher) exposes data/error/loading/state with race-safe commits (generation guard), AbortSignal, stale-while-revalidate, and optimistic mutate.
• @zakkster/lite-form -- Headless reactive forms. One validator per keystroke, hoisted Zod/Yup schema, ~1.5M keystrokes/sec on a 100-field form (8× the hand-written pattern). No DOM, no VDOM, no compiler.
• @zakkster/lite-router -- Zero-GC sub-2KB SPA router. URL pathname, query params, and route matches as fine-grained signals -- components re-render only when their slice of the URL changes.
• @zakkster/lite-persist -- Zero-GC reactive persistence. Debounced, coalesced localStorage/sessionStorage sync with cross-tab mirroring -- a burst of writes becomes one storage write.
• @zakkster/lite-channel -- Cross-tab synchronization over BroadcastChannel. Multiplexed per-key sync, last-writer-wins (Lamport clock + tab-id tiebreak), reactive presence (peers, status, leader election as signals).

Rendering (DOM / Canvas)

• @zakkster/lite-element -- Zero-GC reactive Custom Elements, no virtual DOM or templating. Component state survives synchronous reparents (sort, drag-and-drop, insertBefore) -- the moves that destroy React, Vue, and Lit components.
• @zakkster/lite-virtual -- Thrash-free list/grid windowing. Integer-gated reactive indices + Object.is cutoff means scrolling within a row writes zero bytes to the DOM. ~3.6M sub-row scrolls/sec, bounded pool regardless of count, fixed and variable heights, 2-D grid.
• @zakkster/lite-scene -- Reactive retained-mode Canvas2D scene graph. Nodes (group/rect/circle/line/text/image/path) take signals as props; the renderer redraws only what changed. Hit testing, clip groups, pointerEvents, nested transforms.

Time & scheduling

• @zakkster/lite-raf -- Zero-GC frame-rate scheduling. One requestAnimationFrame loop; frameTime/frameDelta/frameCount as signals; rafEffect() -- reactive effects that run at most once per frame. Built for canvas/WebGL render loops and games.
• @zakkster/lite-time -- Reactive, drift-corrected wall-clock cadence. One 1s heartbeat; zero-GC relativeTime/countdown/every; deterministic for tests and SSR. Not a date library -- Intl does formatting, you bring the dates.

Browser and runtime support

Integration recipes

import { signal, effect } from "@zakkster/lite-signal";

const score = signal(0);
const health = signal(100);

let frameRequested = false;
const rafScheduler = (run) => {
  if (frameRequested) return;
  frameRequested = true;
  requestAnimationFrame(() => { frameRequested = false; run(); });
};

effect(() => {
  hudCanvas.draw({ score: score(), health: health() });
}, { scheduler: rafScheduler });

import { signal, effect, batch } from "@zakkster/lite-signal";

const config = {
  theme:     signal("dark"),
  rgbHue:    signal(180),
  showStats: signal(true)
};

Twitch.ext.configuration.onChanged(() => {
  const cfg = JSON.parse(Twitch.ext.configuration.broadcaster?.content || "{}");
  batch(() => {
    if (cfg.theme)     config.theme.set(cfg.theme);
    if (cfg.rgbHue)    config.rgbHue.set(cfg.rgbHue);
    if (cfg.showStats !== undefined) config.showStats.set(cfg.showStats);
  });
});

effect(() => applyTheme(config.theme(), config.rgbHue()));
effect(() => statsPanel.toggle(config.showStats()));

import { createRegistry } from "@zakkster/lite-signal";

function spawnPlugin(pluginCode) {
  const r = createRegistry({ maxNodes: 256, maxLinks: 1024 });
  try {
    pluginCode(r);  // plugin uses r.signal, r.effect, etc.
  } catch (err) {
    console.error("Plugin failed:", err);
  }
  return () => r.destroy();  // unload kills the whole reactive world
}

Conformance

FAQ

npm scripts

npm test          # behavior suite, ~1.3s
npm run test:gc   # zero-gc suite, requires --expose-gc, ~3s
npm run bench     # comparative benchmark vs alien-signals (results.txt), ~5min
npm run bench-reactive  # 5-framework reactivity suite (resultsReactive.txt)
npm run verify    # test + test:gc + sanity bench; gate for publish

License

MIT (c) Zahary Shinikchiev

Part of the @zakkster zero-GC stack: lite-ecs * lite-ease * lite-pointer-tracker * lite-bmfont * lite-color