@esportsplus/reactivity 0.31.3 → 0.33.0

package/README.md

@@ -1,5 +1,7 @@
 # @esportsplus/reactivity
 
+Project doc bundle: [docs/index.md](./docs/index.md) — rejected dead-ends, skip reasons, completed-work index.
+
 A fine-grained reactivity system with compile-time transformations. Write reactive code with natural JavaScript syntax while the compiler generates optimized signal-based code.
 
 ## Installation
@@ -221,22 +223,27 @@ let user = new ReactiveObject_1();
 | `reactive(() => expr)` | Creates a computed value (compile-time only) |
 | `reactive({...})` | Creates a reactive object with signals and computeds |
 | `reactive([...])` | Creates a reactive array |
-| `effect(fn)` | Runs a function that re-executes when dependencies change. Returns a dispose function |
+| `effect(fn, onError?)` | Runs a function that re-executes when dependencies change. Returns a dispose function. Optional `onError` receives thrown or rejected errors |
 | `root(fn)` | Creates an untracked scope. If `fn` accepts an argument, a dispose function is provided |
 | `onCleanup(fn)` | Registers a cleanup function for the current effect/computed |
 
 ### Low-Level Functions
 
-These are typically only used by the transformer output:
+These operate directly on signal/computed nodes — the transformer emits them, and they can be called by hand:
 
 | Function | Description |
 |----------|-------------|
-| `signal(value)` | Creates a raw signal |
-| `computed(fn)` | Creates a raw computed |
-| `read(node)` | Reads a signal or computed value |
+| `signal(value, equals?)` | Creates a raw signal. Optional `equals` comparator suppresses writes it deems equal (default `===`) |
+| `computed(fn, equals?)` | Creates a raw computed. A `fn` returning a `Promise` or `AsyncIterable` becomes an async computed automatically (initial value `undefined`, unwrapped to `Settled<T>`). Optional `equals` comparator |
+| `read(node)` | Reads a signal or computed value, subscribing the current scope |
 | `write(signal, value)` | Sets a signal value |
-| `asyncComputed(fn)` | Creates a signal that resolves an async computed. Initial value is `undefined` |
+| `peek(node)` | Reads a signal/computed's current value **without** subscribing (returns an up-to-date value even for a dirty computed) |
+| `untrack(fn)` | Runs `fn` without tracking dependencies; returns `fn`'s result |
+| `batch(fn)` | Groups writes so dependent effects defer until `fn` returns; pair with `flush()` for a synchronous transaction |
+| `flush()` | Synchronously settles all pending computed/effect updates |
 | `dispose(computed)` | Disposes a computed and its dependencies |
+| `computed.invalidate(computed)` | Forces re-derivation of a computed on next read (re-dispatches an async computed's promise for a refetch) |
+| `signal.selector(signal, key)` | Per-key selector: within a tracking scope, subscribes to whether `signal`'s value equals `key`, so only key-matching observers re-run on write (O(1) fan-out) |
 
 ### Type Guards
 
@@ -272,6 +279,8 @@ Symbol constants for type identification:
 |------|-------------|
 | `Signal<T>` | Signal node type |
 | `Computed<T>` | Computed node type |
+| `Settled<T>` | Resolved value type of a computed (unwraps `Promise<T>`/`AsyncIterable<T>` to `T`) |
+| `SelectorSignal<T>` | Signal variant backing `signal.selector` per-key subscriptions |
 | `Link` | Dependency graph link between nodes |
 | `Reactive<T>` | Utility type for inferring reactive object/array types |
 | `TransformResult` | Compiler transform output metadata |
@@ -306,6 +315,34 @@ All standard array methods (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`,
 | `splice` | `{ start, deleteCount, items }` | Array was spliced |
 | `unshift` | `{ items: T[] }` | Items were unshifted |
 
+## Architecture
+
+- `src/system.ts` — the core signal/computed/effect engine: height-bucketed heap scheduler,
+  generation-version dependency dedup (read-version dedup), and iterative (non-recursive)
+  notify/update/dispose walks. Also supports async (Promise/AsyncIterable) computeds and
+  per-key selector signals (`signal.selector`).
+- `src/constants.ts` — shared state bitmasks and symbol constants consumed by every other module.
+- `src/types.ts` — shared `Signal`/`Computed`/`Link`/`Reactive` types.
+- `src/reactive/index.ts`, `src/reactive/array.ts`, `src/reactive/object.ts` — the runtime
+  `reactive()` dispatch and the `ReactiveObject`/`ReactiveArray` classes it builds on.
+- `src/compiler/*` — the build-time transform pipeline (`constants.ts`, `primitives.ts`,
+  `object.ts`, `array.ts`, `index.ts`) plus the `plugins/tsc.ts` and `plugins/vite.ts`
+  entrypoints that wire it into a build (see Transformer Plugins above).
+
+## Development
+
+```bash
+pnpm install
+pnpm build   # tsc
+pnpm test    # vitest run
+pnpm bench   # vitest bench --run
+```
+
+`agent:test` (`tsc --noEmit && vitest run`) and `agent:bench` (`vitest bench --run`) are the
+CI-facing aliases of the same build/test/bench commands.
+
 ## License
 
 MIT
+
+<!-- claude-code:readme-source-hash: 189167a17e9be8c6 -->

package/bench/cellx.bench.ts

@@ -0,0 +1,61 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Ported from milomg/js-reactivity-benchmark packages/core/src/benches/cellxBench.ts (MIT)
+
+interface Layer {
+    prop1: ReactiveComputed<number>;
+    prop2: ReactiveComputed<number>;
+    prop3: ReactiveComputed<number>;
+    prop4: ReactiveComputed<number>;
+}
+
+
+function cellx(layers: number, before: readonly number[], after: readonly number[]) {
+    let start = {
+        prop1: framework.signal(1),
+        prop2: framework.signal(2),
+        prop3: framework.signal(3),
+        prop4: framework.signal(4)
+    };
+
+    let layer: Layer = start;
+
+    for (let i = layers; i > 0; i--) {
+        let m = layer;
+
+        layer = {
+            prop1: framework.computed(() => m.prop2.read()),
+            prop2: framework.computed(() => m.prop1.read() - m.prop3.read()),
+            prop3: framework.computed(() => m.prop2.read() + m.prop4.read()),
+            prop4: framework.computed(() => m.prop3.read())
+        };
+    }
+
+    let end = layer;
+
+    assert(end.prop1.read() === before[0], 'cellx: unexpected initial prop1');
+    assert(end.prop2.read() === before[1], 'cellx: unexpected initial prop2');
+    assert(end.prop3.read() === before[2], 'cellx: unexpected initial prop3');
+    assert(end.prop4.read() === before[3], 'cellx: unexpected initial prop4');
+
+    return framework.withBatch(() => {
+        start.prop1.write(4);
+        start.prop2.write(3);
+        start.prop3.write(2);
+        start.prop4.write(1);
+    }).then(() => {
+        assert(end.prop1.read() === after[0], 'cellx: unexpected final prop1');
+        assert(end.prop2.read() === after[1], 'cellx: unexpected final prop2');
+        assert(end.prop3.read() === after[2], 'cellx: unexpected final prop3');
+        assert(end.prop4.read() === after[3], 'cellx: unexpected final prop4');
+    });
+}
+
+
+describe('cellx', () => {
+    bench('cellx1000', async () => {
+        await framework.withBuild(() => cellx(1000, [-3, -6, -2, 2], [-2, -4, 2, 3]));
+    });
+});

package/bench/dynamic.bench.ts

@@ -0,0 +1,103 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Dynamic-graph workloads: dependency SETS change between runs (branch on a control
+// signal), exercising link/unlink churn and the link pool
+
+function dependencySwap() {
+    let a = [],
+        b = [],
+        computeds: ReactiveComputed<number>[] = [],
+        control = framework.signal(true);
+
+    for (let i = 0; i < 10; i++) {
+        a.push(framework.signal(i));
+        b.push(framework.signal(i * 2));
+    }
+
+    for (let i = 0; i < 20; i++) {
+        computeds.push(framework.computed(() => {
+            let source = control.read() ? a : b,
+                sum = 0;
+
+            for (let j = 0, n = source.length; j < n; j++) {
+                sum += source[j].read();
+            }
+
+            return sum;
+        }));
+    }
+
+    for (let i = 0, n = computeds.length; i < n; i++) {
+        let c = computeds[i];
+
+        framework.effect(() => c.read());
+    }
+
+    let flip = true;
+
+    return async () => {
+        flip = !flip;
+
+        await framework.withBatch(() => {
+            control.write(flip);
+        });
+
+        let expected = flip ? 45 : 90;
+
+        for (let i = 0, n = computeds.length; i < n; i++) {
+            assert(computeds[i].read() === expected, 'dynamic swap: unexpected sum');
+        }
+    };
+}
+
+function movingBranchPoint() {
+    let base = framework.signal(100),
+        chain: ReactiveComputed<number>[] = [],
+        cut = framework.signal(0),
+        depth = 30,
+        source = framework.signal(1);
+
+    // Each node conditionally links `base` (a signal — safe to drop, signals never
+    // auto-dispose) while ALWAYS reading its predecessor so the chain stays alive
+    chain.push(framework.computed(() => (cut.read() > 0 ? base.read() : 0) + source.read()));
+
+    for (let i = 1; i < depth; i++) {
+        let prev = chain[i - 1];
+
+        chain.push(framework.computed(() => (cut.read() > i ? base.read() : 0) + prev.read() + 1));
+    }
+
+    let tail = chain[depth - 1];
+
+    framework.effect(() => tail.read());
+
+    return async () => {
+        await framework.withBatch(() => {
+            cut.write(15);
+        });
+
+        assert(tail.read() === 15 * 100 + 1 + (depth - 1), 'dynamic branch: unexpected tail after cut');
+
+        await framework.withBatch(() => {
+            cut.write(0);
+        });
+
+        assert(tail.read() === 1 + (depth - 1), 'dynamic branch: unexpected tail after restore');
+    };
+}
+
+
+describe('dynamic graphs', () => {
+    let branchRun = framework.withBuild(movingBranchPoint),
+        swapRun = framework.withBuild(dependencySwap);
+
+    bench('dependency set swap (20 computeds x 10 deps)', async () => {
+        await swapRun();
+    });
+
+    bench('moving branch point (30-deep chain re-link)', async () => {
+        await branchRun();
+    });
+});

package/bench/kairo.bench.ts

@@ -0,0 +1,368 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Ported from milomg/js-reactivity-benchmark packages/core/src/benches/kairo/* (MIT)
+
+function avoidablePropagation() {
+    let head = framework.signal(0),
+        computed1 = framework.computed(() => head.read()),
+        computed2 = framework.computed(() => (computed1.read(), 0)),
+        computed3 = framework.computed(() => (busy(), computed2.read() + 1)),
+        computed4 = framework.computed(() => computed3.read() + 2),
+        computed5 = framework.computed(() => computed4.read() + 3);
+
+    framework.effect(() => {
+        computed5.read();
+        busy();
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(computed5.read() === 6, 'kairo avoidable: unexpected terminal value');
+
+        for (let i = 0; i < 1000; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(computed5.read() === 6, 'kairo avoidable: propagation was not avoided');
+        }
+    };
+}
+
+function broadPropagation() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        last: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < 50; i++) {
+        let current = framework.computed(() => head.read() + i),
+            current2 = framework.computed(() => current.read() + 1);
+
+        framework.effect(() => {
+            current2.read();
+            counter.count++;
+        });
+
+        last = current2;
+    }
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        counter.count = 0;
+
+        for (let i = 0; i < 50; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(last.read() === i + 50, 'kairo broad: unexpected tail value');
+        }
+
+        assert(counter.count === 50 * 50, 'kairo broad: unexpected effect run count');
+    };
+}
+
+function busy() {
+    let a = 0;
+
+    for (let i = 0; i < 100; i++) {
+        a++;
+    }
+
+    return a;
+}
+
+function deepPropagation() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        len = 50,
+        current: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < len; i++) {
+        let c = current;
+
+        current = framework.computed(() => c.read() + 1);
+    }
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        let iter = 50;
+
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        counter.count = 0;
+
+        for (let i = 0; i < iter; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(current.read() === len + i, 'kairo deep: unexpected tail value');
+        }
+
+        assert(counter.count === iter, 'kairo deep: unexpected effect run count');
+    };
+}
+
+function diamond() {
+    let counter = { count: 0 },
+        current: ReactiveComputed<number>[] = [],
+        head = framework.signal(0),
+        width = 5;
+
+    for (let i = 0; i < width; i++) {
+        current.push(framework.computed(() => head.read() + 1));
+    }
+
+    let sum = framework.computed(() => current.map((x) => x.read()).reduce((a, b) => a + b, 0));
+
+    framework.effect(() => {
+        sum.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(sum.read() === 2 * width, 'kairo diamond: unexpected initial sum');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 500; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(sum.read() === (i + 1) * width, 'kairo diamond: unexpected sum');
+        }
+
+        assert(counter.count === 500, 'kairo diamond: unexpected effect run count');
+    };
+}
+
+function mux() {
+    let heads = new Array(100).fill(null).map(() => framework.signal(0));
+
+    let muxed = framework.computed(() => Object.fromEntries(heads.map((h) => h.read()).entries()));
+
+    let splited = heads
+        .map((_, index) => framework.computed(() => muxed.read()[index]))
+        .map((x) => framework.computed(() => x.read() + 1));
+
+    for (let i = 0, n = splited.length; i < n; i++) {
+        let x = splited[i];
+
+        framework.effect(() => x.read());
+    }
+
+    return async () => {
+        for (let i = 0; i < 10; i++) {
+            await framework.withBatch(() => {
+                heads[i].write(i);
+            });
+
+            assert(splited[i].read() === i + 1, 'kairo mux: unexpected split value');
+        }
+
+        for (let i = 0; i < 10; i++) {
+            await framework.withBatch(() => {
+                heads[i].write(i * 2);
+            });
+
+            assert(splited[i].read() === i * 2 + 1, 'kairo mux: unexpected split value');
+        }
+    };
+}
+
+function repeatedObservers() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        size = 30;
+
+    let current = framework.computed(() => {
+        let result = 0;
+
+        for (let i = 0; i < size; i++) {
+            result += head.read();
+        }
+
+        return result;
+    });
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(current.read() === size, 'kairo repeated: unexpected initial value');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(current.read() === i * size, 'kairo repeated: unexpected value');
+        }
+
+        assert(counter.count === 100, 'kairo repeated: unexpected effect run count');
+    };
+}
+
+function triangle() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        list: ReactiveComputed<number>[] = [],
+        width = 10,
+        current: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < width; i++) {
+        let c = current;
+
+        list.push(current);
+        current = framework.computed(() => c.read() + 1);
+    }
+
+    let sum = framework.computed(() => list.map((x) => x.read()).reduce((a, b) => a + b, 0));
+
+    framework.effect(() => {
+        sum.read();
+        counter.count++;
+    });
+
+    return async () => {
+        let constant = (width * (width + 1)) / 2;
+
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(sum.read() === constant, 'kairo triangle: unexpected initial sum');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(sum.read() === constant - width + i * width, 'kairo triangle: unexpected sum');
+        }
+
+        assert(counter.count === 100, 'kairo triangle: unexpected effect run count');
+    };
+}
+
+function unstable() {
+    let counter = { count: 0 },
+        head = framework.signal(0);
+
+    let double = framework.computed(() => head.read() * 2);
+
+    let inverse = framework.computed(() => -head.read());
+
+    let current = framework.computed(() => {
+        let result = 0;
+
+        for (let i = 0; i < 20; i++) {
+            result += head.read() % 2 ? double.read() : inverse.read();
+        }
+
+        return result;
+    });
+
+    // Keepers: this system auto-disposes a computed on last-sub unlink, so the
+    // inactive branch would go permanently stale without a live subscriber
+    framework.effect(() => double.read());
+
+    framework.effect(() => inverse.read());
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(current.read() === 40, 'kairo unstable: unexpected initial value');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+        }
+
+        assert(counter.count === 100, 'kairo unstable: unexpected effect run count');
+    };
+}
+
+
+describe('kairo', () => {
+    let avoidableRun = framework.withBuild(avoidablePropagation),
+        broadRun = framework.withBuild(broadPropagation),
+        deepRun = framework.withBuild(deepPropagation),
+        diamondRun = framework.withBuild(diamond),
+        muxRun = framework.withBuild(mux),
+        repeatedRun = framework.withBuild(repeatedObservers),
+        triangleRun = framework.withBuild(triangle),
+        unstableRun = framework.withBuild(unstable);
+
+    bench('avoidablePropagation', async () => {
+        await avoidableRun();
+    });
+
+    bench('broad', async () => {
+        await broadRun();
+    });
+
+    bench('deep', async () => {
+        await deepRun();
+    });
+
+    bench('diamond', async () => {
+        await diamondRun();
+    });
+
+    bench('mux', async () => {
+        await muxRun();
+    });
+
+    bench('repeatedObservers', async () => {
+        await repeatedRun();
+    });
+
+    bench('triangle', async () => {
+        await triangleRun();
+    });
+
+    bench('unstable', async () => {
+        await unstableRun();
+    });
+});

package/bench/lib/reactive-adapter.ts

@@ -0,0 +1,51 @@
+import { computed, effect, read, root, signal, write } from '~/system';
+
+import type { Settled } from '~/types';
+
+
+interface ReactiveComputed<T> {
+    read: () => T;
+}
+
+interface ReactiveSignal<T> extends ReactiveComputed<T> {
+    write: (value: T) => void;
+}
+
+
+// Mirrors js-reactivity-benchmark's ReactiveFramework so a future external-package swap is mechanical
+const framework = {
+    computed: <T>(fn: () => T): ReactiveComputed<Settled<T>> => {
+        let node = computed(fn);
+
+        return {
+            read: () => read(node)
+        };
+    },
+    effect: (fn: () => void): VoidFunction => effect(fn),
+    signal: <T>(value: T): ReactiveSignal<T> => {
+        let node = signal(value);
+
+        return {
+            read: () => read(node),
+            write: (v: T) => write(node, v)
+        };
+    },
+    withBatch: async (fn: () => void): Promise<void> => {
+        fn();
+
+        // Propagation is microtask-scheduled (schedule/stabilize) — two ticks cover a reschedule
+        await Promise.resolve();
+        await Promise.resolve();
+    },
+    withBuild: <T>(fn: () => T): T => root(fn)
+};
+
+const assert = (condition: boolean, message: string): void => {
+    if (!condition) {
+        throw new Error(`bench: ${message}`);
+    }
+};
+
+
+export { assert, framework };
+export type { ReactiveComputed, ReactiveSignal };