Ecopages Signals

@ecopages/signals is a renderer-agnostic signals package that can be used standalone or underneath Radiant.

Its core model is based on the TC39 Signals proposal, with a smaller surface area and a few convenience helpers for application code today.

The public entrypoint remains index.ts, while the implementation now lives in focused modules under src/ so the core runtime, effects, watcher support, and store logic can evolve independently.

Current Scope

This package currently provides:

• State<T> for writable values
• Computed<T> for lazily derived values
• currentComputed() for advanced derived helpers that need the active computed context
• effect(...) for reactive side effects with scheduled re-execution
• watch(...) for observing derived values with previous-value access
• untrack(...) and peek(...) for non-tracking reads
• subtle.Watcher plus watched and unwatched hooks for low-level invalidation workflows
• createStore(...) for deep reactive object and array state
• mapItems(...) for derived lists that map each item once and reuse its result while it stays in the list
• isStore(...) for detecting signal-backed store proxies
• snapshot(...) for materializing plain nested data
• automatic dependency discovery during Computed evaluation
• subscription support for renderer or framework adapters

Source Layout

The package is organized around a stable public barrel and smaller implementation files:

• index.ts re-exports the public API and exposes subtle
• src/types.ts defines the public contracts, options, and low-level symbols
• src/state.ts implements writable State signals
• src/computed.ts implements lazy derived Computed signals and active-computation helpers
• src/effect.ts and src/watch.ts implement effect scheduling and derived-value observation
• src/watcher.ts implements proposal-shaped low-level watchers
• src/tracking.ts contains non-tracking read helpers
• src/store.ts contains deep store proxying and snapshot materialization

Design Position

This package is renderer-agnostic.

• It does not know about JSX.
• It does not know about Radiant components.
• It is meant to work both as a standalone package and underneath adapters in those packages.

flowchart LR
    Set["state.set(value)"] --> Stale["dependent computeds<br/>marked stale"]
    Stale --> Pull["computed.get()<br/>recomputes lazily and caches"]
    Stale --> Notify["subscribers, effects<br/>and watchers notified"]
    Notify --> Adapter["an adapter re-reads and patches,<br/>such as an @ecopages/jsx binding"]

A computed tracks the signals it reads while it evaluates, so dependencies need no declaration. Nothing recomputes until something reads it, and an adapter that subscribes gets pushed the new value to patch its own output.

TC39 Relationship

This package is based on the current TC39 Signals proposal and tracks the same broad model around:

• State and Computed signal classes
• lazy pull-based recomputation with cached values
• automatic dependency discovery during computed evaluation
• custom equality functions for writable and computed signals
• untracked reads as an escape hatch

It is not a drop-in implementation of the current proposal draft.

It is best understood as proposal-aligned in its core semantics, but not yet fully API-compatible with the draft surface.

• It exposes convenience helpers such as effect(...), watch(...), createStore(...), and snapshot(...) directly.
• It currently exposes manual subscribe(...) hooks for adapter and library integration.
• It exposes a proposal-shaped subtle.Watcher API, while still keeping the existing convenience helpers.
• Its subtle.Watcher follows the proposal-style re-arm behavior, where calling watch(...) resets the pending set and notification latch for the next invalidation cycle.
• It does not yet expose the full TC39 subtle introspection surface.

API Notes

• subscribe(...) is intended for adapter-style push integration. Application-level derived work is usually better expressed with Computed, effect(...), or watch(...).
• watch(...) is built on top of a computed signal plus an effect, so it inherits computed equality behavior and effect scheduling. It notifies on change, not per flush: a set followed by a set-back before the scheduler runs does not notify, and previousValue is the last value delivered.
• subtle.Watcher reports staleness rather than recalculated values. Calling watch(...) is both registration and reset.
• createStore(...) wraps nested plain objects and arrays, while snapshot(...) detaches the current plain value graph for logging, serialization, or comparison.
• mapItems(source, project, options?) keeps each item's result by item identity, so only new items are projected and the others keep the same result object. project runs untracked, so a result that reads its item's signals does not re-map the list. A renderer such as @ecopages/jsx skips rows whose value is unchanged; JSX users can use <MapItems each={list}> instead.

Example

import { Computed, State, createStore, effect, watch } from '@ecopages/signals';

const count = new State(0);
const parity = new Computed(() => ((count.get() & 1) === 0 ? 'even' : 'odd'));
const store = createStore({ profile: { name: 'Ada' } });

const dispose = effect(() => {
    console.log(parity.get(), store.profile.name);
});

const stopWatching = watch(
    () => store.profile.name,
    (nextName, previousName) => {
        console.log(previousName, '->', nextName);
    },
);

count.set(1);
store.profile.name = 'Grace';
dispose();
stopWatching();

Limits

This implementation is still smaller than the current TC39 proposal draft.

• no full TC39 Watcher and subtle semantics surface yet
• no full proposal-style subtle introspection helpers yet
• no batching or transaction model
• no framework-owned disposal tree or component ownership integration yet

Those omissions are deliberate. The goal is to keep a small, useful standalone package while leaving room to align further as the proposal evolves.