@esportsplus/reactivity 0.32.0 → 0.34.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
@@ -313,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/build/compiler/array.d.ts

@@ -1,5 +1,5 @@
 import { ts } from '@esportsplus/typescript';
 import type { ReplacementIntent } from '@esportsplus/typescript/compiler';
 import type { Bindings } from './types.js';
-declare const _default: (sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.TypeChecker) => ReplacementIntent[];
 export default _default;
+declare function _default(sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.Checker): ReplacementIntent[];

package/build/compiler/array.js

@@ -160,7 +160,7 @@ function visit(ctx, node) {
         node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
         ts.isIdentifier(node.left)) {
         let name = node.left.text, right = node.right;
-        while (ts.isAsExpression(right) || ts.isTypeAssertionExpression(right)) {
+        while (ts.isAsExpression(right) || ts.isTypeAssertion(right)) {
             right = right.expression;
         }
         if (ctx.bindings.get(name) === TYPES.Array && ts.isArrayLiteralExpression(right)) {
@@ -172,7 +172,7 @@ function visit(ctx, node) {
             });
         }
     }
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }
 export default (sourceFile, bindings, checker) => {
     let ctx = {

package/build/compiler/index.js

@@ -27,7 +27,7 @@ function hasReactiveCalls(checker, node) {
         return true;
     }
     let found = false;
-    ts.forEachChild(node, child => {
+    node.forEachChild(child => {
         if (!found && hasReactiveCalls(checker, child)) {
             found = true;
         }
@@ -41,7 +41,7 @@ function visit(ctx, node) {
             node
         });
     }
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }
 export default {
     patterns: ['reactive(', 'reactive<'],

package/build/compiler/object.d.ts

@@ -5,5 +5,5 @@ type ObjectTransformResult = {
     prepend: string[];
     replacements: ReplacementIntent[];
 };
-declare const _default: (sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.TypeChecker) => ObjectTransformResult;
 export default _default;
+declare function _default(sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.Checker): ObjectTransformResult;

package/build/compiler/object.js

@@ -13,10 +13,10 @@ function analyzeProperty(prop, sourceFile) {
         return null;
     }
     let unwrapped = prop.initializer, value = unwrapped, valueText = value.getText(sourceFile);
-    while (ts.isAsExpression(unwrapped) || ts.isTypeAssertionExpression(unwrapped) || ts.isParenthesizedExpression(unwrapped)) {
+    while (ts.isAsExpression(unwrapped) || ts.isTypeAssertion(unwrapped) || ts.isParenthesizedExpression(unwrapped)) {
         unwrapped = unwrapped.expression;
     }
-    if (ts.isAsExpression(value) || ts.isTypeAssertionExpression(value)) {
+    if (ts.isAsExpression(value) || ts.isTypeAssertion(value)) {
         let type = value.type;
         if (ts.isArrayTypeNode(type) ||
             (ts.isTypeReferenceNode(type) &&
@@ -161,12 +161,12 @@ function visit(ctx, node) {
             for (let i = 0, n = props.length; i < n; i++) {
                 let prop = props[i];
                 if (ts.isSpreadAssignment(prop)) {
-                    ts.forEachChild(node, n => visit(ctx, n));
+                    node.forEachChild(n => visit(ctx, n));
                     return;
                 }
                 let analyzed = analyzeProperty(prop, ctx.sourceFile);
                 if (!analyzed) {
-                    ts.forEachChild(node, n => visit(ctx, n));
+                    node.forEachChild(n => visit(ctx, n));
                     return;
                 }
                 properties.push(analyzed);
@@ -183,7 +183,7 @@ function visit(ctx, node) {
             });
         }
     }
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }
 export default (sourceFile, bindings, checker) => {
     let ctx = {

package/build/compiler/plugins/vite.d.ts

@@ -1,12 +1,14 @@
 declare const _default: ({ root }?: {
     root?: string;
 }) => {
+    closeBundle: () => void;
+    closeWatcher: () => void;
     configResolved: (config: unknown) => void;
-    enforce: "pre";
+    enforce: 'pre';
     name: string;
     transform: (code: string, id: string) => {
         code: string;
-        map: null;
+        map: import("@esportsplus/typescript/compiler").SourceMapV3;
     } | null;
     watchChange: (id: string) => void;
 };

package/build/compiler/primitives.d.ts

@@ -1,5 +1,5 @@
 import { ts } from '@esportsplus/typescript';
 import type { ReplacementIntent } from '@esportsplus/typescript/compiler';
 import type { Bindings } from './types.js';
-declare const _default: (sourceFile: ts.SourceFile, bindings: Bindings, isReactiveCall: (node: ts.Node) => boolean) => ReplacementIntent[];
 export default _default;
+declare function _default(sourceFile: ts.SourceFile, bindings: Bindings, isReactiveCall: (node: ts.Node) => boolean): ReplacementIntent[];

package/build/compiler/primitives.js

@@ -37,7 +37,7 @@ function visit(ctx, node) {
             }
             else {
                 let unwrapped = arg;
-                while (ts.isAsExpression(unwrapped) || ts.isParenthesizedExpression(unwrapped) || ts.isTypeAssertionExpression(unwrapped)) {
+                while (ts.isAsExpression(unwrapped) || ts.isParenthesizedExpression(unwrapped) || ts.isTypeAssertion(unwrapped)) {
                     unwrapped = unwrapped.expression;
                 }
                 if (ts.isArrayLiteralExpression(unwrapped) || ts.isObjectLiteralExpression(unwrapped)) {
@@ -48,7 +48,7 @@ function visit(ctx, node) {
                         generate: () => `${NAMESPACE}.reactive`,
                         node: call.expression
                     });
-                    ts.forEachChild(node, n => visit(ctx, n));
+                    node.forEachChild(n => visit(ctx, n));
                     return;
                 }
             }
@@ -97,7 +97,7 @@ function visit(ctx, node) {
         node.parent &&
         !(ts.isVariableDeclaration(node.parent) && node.parent.name === node)) {
         if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) {
-            ts.forEachChild(node, n => visit(ctx, n));
+            node.forEachChild(n => visit(ctx, n));
             return;
         }
         let bindings = ctx.scopedBindings, binding, name = node.text;
@@ -178,7 +178,7 @@ function visit(ctx, node) {
             }
         }
     }
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }
 export default (sourceFile, bindings, isReactiveCall) => {
     let ctx = {

package/build/reactive/array.d.ts

@@ -41,6 +41,9 @@ declare class ReactiveArray<T> extends Array<T> {
     private _length;
     listeners: Listeners<T>;
     constructor(...items: T[]);
+    static get [Symbol.species](): ArrayConstructor;
+    get $length(): number;
+    set $length(value: number);
     $set(i: number, value: T): void;
     clear(): void;
     concat(...items: ConcatArray<T>[]): ReactiveArray<T>;
@@ -56,7 +59,5 @@ declare class ReactiveArray<T> extends Array<T> {
     sort(fn?: (a: T, b: T) => number): this;
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
     unshift(...items: T[]): number;
-    get $length(): number;
-    set $length(value: number);
 }
 export { ReactiveArray };

package/build/reactive/array.js

@@ -14,6 +14,18 @@ class ReactiveArray extends Array {
         super(...items);
         this._length = signal(items.length);
     }
+    static get [Symbol.species]() {
+        return Array;
+    }
+    get $length() {
+        return read(this._length);
+    }
+    set $length(value) {
+        if (value > this.length) {
+            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
+        }
+        this.splice(value, this.length);
+    }
     $set(i, value) {
         let prev = this[i];
         if (prev === value) {
@@ -146,29 +158,34 @@ class ReactiveArray extends Array {
         return item;
     }
     sort(fn) {
-        let n = this.length, before = new Array(n);
-        for (let i = 0; i < n; i++) {
-            before[i] = this[i];
-        }
-        super.sort(fn);
-        let buckets = new Map(), order = new Array(n);
-        for (let i = 0; i < n; i++) {
-            let value = before[i], list = buckets.get(value);
-            if (!list) {
-                buckets.set(value, [i]);
+        if (this.listeners.sort === undefined) {
+            super.sort(fn);
+        }
+        else {
+            let n = this.length, before = new Array(n);
+            for (let i = 0; i < n; i++) {
+                before[i] = this[i];
             }
-            else {
-                list.push(i);
+            super.sort(fn);
+            let buckets = new Map(), order = new Array(n);
+            for (let i = 0; i < n; i++) {
+                let value = before[i], list = buckets.get(value);
+                if (!list) {
+                    buckets.set(value, [i]);
+                }
+                else {
+                    list.push(i);
+                }
             }
-        }
-        for (let i = 0; i < n; i++) {
-            let list = buckets.get(this[i]);
-            order[i] = list.length === 1 ? list[0] : list[list.length - 1];
-            if (list.length > 1) {
-                list.pop();
+            for (let i = 0; i < n; i++) {
+                let list = buckets.get(this[i]);
+                order[i] = list.length === 1 ? list[0] : list[list.length - 1];
+                if (list.length > 1) {
+                    list.pop();
+                }
             }
+            this.dispatch('sort', { order });
         }
-        this.dispatch('sort', { order });
         return this;
     }
     splice(start, deleteCount = this.length, ...items) {
@@ -191,15 +208,6 @@ class ReactiveArray extends Array {
         this.dispatch('unshift', { items });
         return length;
     }
-    get $length() {
-        return read(this._length);
-    }
-    set $length(value) {
-        if (value > this.length) {
-            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
-        }
-        this.splice(value, this.length);
-    }
 }
 Object.defineProperty(ReactiveArray.prototype, REACTIVE_ARRAY, { value: true });
 export { ReactiveArray };

package/build/reactive/object.d.ts

@@ -4,7 +4,7 @@ import { ReactiveArray } from './array.js';
 declare class ReactiveObject<T extends Record<PropertyKey, unknown>> {
     protected disposers: VoidFunction[] | null;
     constructor(data: T | null);
-    protected [COMPUTED]<T extends Computed<ReturnType<T>>['fn']>(value: T): Computed<import("../types.js").Settled<ReturnType<T>>>;
+    protected [COMPUTED]<T extends Computed<ReturnType<T>>['fn']>(value: T): import("../types.js").ComputedResult<ReturnType<T>>;
     protected [REACTIVE_ARRAY]<U>(value: U[]): ReactiveArray<U>;
     protected [SIGNAL]<T>(value: T): import("../types.js").Signal<T>;
     dispose(): void;

package/build/system.d.ts

@@ -1,25 +1,25 @@
-import { Computed, Settled, Signal } from './types.js';
+import { Computed, ComputedResult, Settled, Signal } from './types.js';
 declare const batch: <T>(fn: () => T) => T;
-declare const computed: {
-    <T>(fn: Computed<T>["fn"], equals?: ((a: Settled<T>, b: Settled<T>) => boolean) | null): Computed<Settled<T>>;
-    invalidate<T>(c: Computed<T>): void;
-};
+declare function computed<T>(fn: Computed<T>['fn'], equals?: ((a: Settled<T>, b: Settled<T>) => boolean) | null): ComputedResult<T>;
+declare namespace computed {
+    var invalidate: <T>(c: Computed<T>) => void;
+}
 declare const dispose: <T>(computed: Computed<T>) => void;
-declare const effect: <T>(fn: Computed<T>["fn"], onError?: (e: unknown) => void) => () => void;
+declare const effect: <T>(fn: Computed<T>['fn'], apply?: (value: T, prev: T | undefined) => void) => () => void;
 declare const flush: () => void;
 declare const isComputed: (value: unknown) => value is Computed<unknown>;
 declare const isSignal: (value: unknown) => value is Signal<unknown>;
 declare const onCleanup: (fn: VoidFunction) => typeof fn;
 declare const peek: <T>(node: Signal<T> | Computed<T>) => T;
 declare const read: <T>(node: Signal<T> | Computed<T>) => T;
-declare const root: {
-    <T>(fn: ((dispose: VoidFunction) => T) | (() => T)): T;
-    disposables: number;
-};
-declare const signal: {
-    <T>(value: T, equals?: ((a: T, b: T) => boolean) | null): Signal<T>;
-    selector<T>(node: Signal<T>, key: T): boolean;
-};
+declare function root<T>(fn: ((dispose: VoidFunction) => T) | (() => T)): T;
+declare namespace root {
+    var disposables: number;
+}
+declare function signal<T>(value: T, equals?: ((a: T, b: T) => boolean) | null): Signal<T>;
+declare namespace signal {
+    var selector: <T>(node: Signal<T>, key: T) => boolean;
+}
 declare const untrack: <T>(fn: () => T) => T;
 declare const write: <T>(signal: Signal<T>, value: T) => void;
 export { batch, computed, dispose, effect, flush, isComputed, isSignal, onCleanup, peek, read, root, signal, untrack, write };

package/build/system.js

@@ -412,18 +412,23 @@ function update(root) {
     }
 }
 function makeAsyncComputed(factory) {
-    let error = signal(undefined), node = signal(undefined), v = 0;
+    let error = signal(undefined), node = signal(undefined), pending = signal(false), v = 0;
     let stop = effect(() => {
         let fail = (e) => {
             if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                 write(error, e === undefined ? new Error('reactivity: async computed rejected with undefined') : e);
+                write(pending, false);
             }
         }, id = ++v, result = read(factory);
         if (isPromise(result)) {
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
             result.then((value) => {
                 if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                     write(error, undefined);
                     write(node, value);
+                    write(pending, false);
                 }
             }, fail);
         }
@@ -439,14 +444,22 @@ function makeAsyncComputed(factory) {
                 if (!r.done) {
                     write(error, undefined);
                     write(node, r.value);
+                    write(pending, false);
                     it.next().then(step, fail);
                 }
+                else {
+                    write(pending, false);
+                }
             };
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
             untrack(() => it.next()).then(step, fail);
         }
         else {
             write(error, undefined);
             write(node, result);
+            write(pending, false);
         }
     });
     let wrapper = makeComputed(() => {
@@ -456,6 +469,7 @@ function makeAsyncComputed(factory) {
         }
         return read(node);
     });
+    wrapper.pending = pending;
     asyncMeta.set(wrapper, { factory: factory });
     wrapper.disposal = stop;
     return wrapper;
@@ -574,15 +588,14 @@ const dispose = (computed) => {
         draining = false;
     }
 };
-const effect = (fn, onError) => {
-    let c = makeComputed(onError
+const effect = (fn, apply) => {
+    let prev;
+    let c = makeComputed(apply
         ? (o) => {
-            try {
-                return fn(o);
-            }
-            catch (e) {
-                onError(e);
-            }
+            let v = fn(o);
+            untrack(() => apply(v, prev));
+            prev = v;
+            return v;
         }
         : fn);
     c.state |= STATE_EFFECT;
@@ -681,9 +694,12 @@ root.disposables = 0;
 const signal = (value, equals = null) => {
     return {
         equals: equals,
+        key: undefined,
         keys: null,
         nextPending: null,
+        parent: undefined,
         rv: 0,
+        state: 0,
         subs: null,
         subsTail: null,
         type: SIGNAL,
@@ -703,6 +719,7 @@ signal.selector = (node, key) => {
             nextPending: null,
             parent: node,
             rv: 0,
+            state: 0,
             subs: null,
             subsTail: null,
             type: SIGNAL,

package/build/types.d.ts

@@ -19,6 +19,9 @@ interface Computed<T> {
     subsTail: Link | null;
     value: T;
 }
+type ComputedResult<T> = T extends Promise<any> | AsyncIterable<any> ? Computed<Settled<T>> & {
+    pending: Signal<boolean>;
+} : Computed<Settled<T>>;
 interface Link {
     dep: Signal<unknown> | Computed<unknown>;
     nextDep: Link | null;
@@ -42,9 +45,12 @@ type SelectorSignal<T> = Signal<boolean> & {
 type Settled<T> = T extends Promise<infer U> ? Awaited<U> | undefined : T extends AsyncIterable<infer U> ? U | undefined : T;
 type Signal<T> = {
     equals: ((a: unknown, b: unknown) => boolean) | null;
+    key: unknown;
     keys: Map<T, SelectorSignal<T>> | null;
     nextPending: Signal<unknown> | null;
+    parent: Signal<unknown> | undefined;
     rv: number;
+    state: number;
     subs: Link | null;
     subsTail: Link | null;
     type: typeof SIGNAL;
@@ -55,4 +61,4 @@ interface TransformResult {
     code: string;
     sourceFile: ts.SourceFile;
 }
-export type { Computed, Link, Reactive, SelectorSignal, Settled, Signal, TransformResult };
+export type { Computed, ComputedResult, Link, Reactive, SelectorSignal, Settled, Signal, TransformResult };

package/package.json

@@ -1,13 +1,13 @@
 {
   "author": "ICJR",
   "dependencies": {
-    "@esportsplus/utilities": "^0.27.3"
+    "@esportsplus/utilities": "^0.28.0"
   },
   "devDependencies": {
-    "@esportsplus/typescript": "^0.29.1",
-    "@types/node": "^25.6.0",
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4"
+    "@esportsplus/typescript": "^0.31.0",
+    "@types/node": "^26.1.1",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
   },
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "scripts": {
     "agent:bench": "vitest bench --run",
     "agent:test": "tsc --noEmit && vitest run",

package/pnpm-workspace.yaml

@@ -1,2 +1,4 @@
 allowBuilds:
   esbuild: true
+minimumReleaseAgeExclude:
+  - '@esportsplus/typescript@0.31.0'

package/src/compiler/array.ts

@@ -7,13 +7,13 @@ import type { Bindings } from './types';
 
 type VisitContext = {
     bindings: Bindings;
-    checker: ts.TypeChecker | undefined;
+    checker: ts.Checker | undefined;
     replacements: ReplacementIntent[];
     sourceFile: ts.SourceFile;
 };
 
 
-function isReactiveCall(checker: ts.TypeChecker | undefined, node: ts.Node): node is ts.CallExpression {
+function isReactiveCall(checker: ts.Checker | undefined, node: ts.Node): node is ts.CallExpression {
     if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) {
         return false;
     }
@@ -220,7 +220,7 @@ function visit(ctx: VisitContext, node: ts.Node): void {
             right = node.right;
 
         // Unwrap "as" expressions: arr = [] as Type[]
-        while (ts.isAsExpression(right) || ts.isTypeAssertionExpression(right)) {
+        while (ts.isAsExpression(right) || ts.isTypeAssertion(right)) {
             right = right.expression;
         }
 
@@ -234,11 +234,11 @@ function visit(ctx: VisitContext, node: ts.Node): void {
         }
     }
 
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }
 
 
-export default (sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.TypeChecker): ReplacementIntent[] => {
+export default (sourceFile: ts.SourceFile, bindings: Bindings, checker?: ts.Checker): ReplacementIntent[] => {
     let ctx: VisitContext = {
             bindings,
             checker,

package/src/compiler/index.ts

@@ -10,7 +10,7 @@ import primitives from './primitives';
 
 
 type FindRemainingContext = {
-    checker: ts.TypeChecker;
+    checker: ts.Checker;
     replacements: ReplacementIntent[];
     sourceFile: ts.SourceFile;
     transformedNodes: Set<ts.Node>;
@@ -18,7 +18,7 @@ type FindRemainingContext = {
 
 
 function findRemainingCalls(
-    checker: ts.TypeChecker,
+    checker: ts.Checker,
     sourceFile: ts.SourceFile,
     transformedNodes: Set<ts.Node>
 ): ReplacementIntent[] {
@@ -29,7 +29,7 @@ function findRemainingCalls(
     return ctx.replacements;
 }
 
-function isReactiveCallExpression(checker: ts.TypeChecker, node: ts.Node): node is ts.CallExpression {
+function isReactiveCallExpression(checker: ts.Checker, node: ts.Node): node is ts.CallExpression {
     if (!ts.isCallExpression(node)) {
         return false;
     }
@@ -49,14 +49,14 @@ function isReactiveCallExpression(checker: ts.TypeChecker, node: ts.Node): node
     return false;
 }
 
-function hasReactiveCalls(checker: ts.TypeChecker, node: ts.Node): boolean {
+function hasReactiveCalls(checker: ts.Checker, node: ts.Node): boolean {
     if (isReactiveCallExpression(checker, node)) {
         return true;
     }
 
     let found = false;
 
-    ts.forEachChild(node, child => {
+    node.forEachChild(child => {
         if (!found && hasReactiveCalls(checker, child)) {
             found = true;
         }
@@ -73,7 +73,7 @@ function visit(ctx: FindRemainingContext, node: ts.Node): void {
         });
     }
 
-    ts.forEachChild(node, n => visit(ctx, n));
+    node.forEachChild(n => visit(ctx, n));
 }