@esportsplus/reactivity 0.31.0 → 0.31.2

package/{readme.md → README.md}

@@ -135,7 +135,7 @@ The library requires a build-time transformer to convert `reactive()` calls into
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite';
-import reactivity from '@esportsplus/reactivity/plugins/vite';
+import reactivity from '@esportsplus/reactivity/compiler/vite';
 
 export default defineConfig({
     plugins: [
@@ -153,7 +153,7 @@ For direct TypeScript compilation using `ttsc` or `ts-patch`:
 {
     "compilerOptions": {
         "plugins": [
-            { "transform": "@esportsplus/reactivity/plugins/tsc" }
+            { "transform": "@esportsplus/reactivity/compiler/tsc" }
         ]
     }
 }
@@ -221,9 +221,9 @@ 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 |
-| `root(fn)` | Creates an untracked scope for effects |
-| `onCleanup(fn)` | Registers a cleanup function for the current effect |
+| `effect(fn)` | Runs a function that re-executes when dependencies change. Returns a dispose function |
+| `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
 
@@ -235,6 +235,7 @@ These are typically only used by the transformer output:
 | `computed(fn)` | Creates a raw computed |
 | `read(node)` | Reads a signal or computed value |
 | `write(signal, value)` | Sets a signal value |
+| `asyncComputed(fn)` | Creates a signal that resolves an async computed. Initial value is `undefined` |
 | `dispose(computed)` | Disposes a computed and its dependencies |
 
 ### Type Guards
@@ -271,7 +272,9 @@ Symbol constants for type identification:
 |------|-------------|
 | `Signal<T>` | Signal node type |
 | `Computed<T>` | Computed node type |
+| `Link` | Dependency graph link between nodes |
 | `Reactive<T>` | Utility type for inferring reactive object/array types |
+| `TransformResult` | Compiler transform output metadata |
 
 ## ReactiveArray
 
@@ -279,14 +282,14 @@ Symbol constants for type identification:
 
 | Method | Description |
 |--------|-------------|
-| `$length()` | Returns the reactive length (tracks reads) |
-| `$set(index, value)` | Sets an item at index reactively |
-| `clear()` | Removes all items and disposes nested reactive objects |
-| `dispose()` | Disposes all nested reactive objects |
-| `on(event, listener)` | Subscribes to an array event |
+| `clear()` | Removes all items, disposes nested reactive objects, and dispatches `clear` event |
+| `concat(...items)` | Appends items **in place** (mutating, returns `this`). Unlike `Array.prototype.concat` |
+| `dispatch(event, value?)` | Manually dispatches an event to registered listeners |
+| `dispose()` | Disposes all nested reactive objects and empties the array |
+| `on(event, listener)` | Subscribes to an array event. Deduplicates by reference |
 | `once(event, listener)` | Subscribes to an event once |
 
-All standard array methods (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `concat`) are supported and trigger corresponding events.
+All standard array methods (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`) are overridden and trigger corresponding events. Empty calls to `push`, `unshift`, and `concat` are no-ops.
 
 ### Events
 

package/build/reactive/array.js

@@ -28,8 +28,9 @@ class ReactiveArray extends Array {
         if (prev === value) {
             return;
         }
+        let length = this.length;
         this[i] = value;
-        if (i >= this.length) {
+        if (i >= length) {
             write(this._length, i + 1);
         }
         this.dispatch('set', { index: i, item: value });
@@ -191,6 +192,9 @@ class ReactiveArray extends Array {
         return removed;
     }
     unshift(...items) {
+        if (!items.length) {
+            return this.length;
+        }
         let length = super.unshift(...items);
         write(this._length, length);
         this.dispatch('unshift', { items });

package/package.json

@@ -1,13 +1,13 @@
 {
   "author": "ICJR",
   "dependencies": {
-    "@esportsplus/utilities": "^0.27.2"
+    "@esportsplus/utilities": "^0.27.3"
   },
   "devDependencies": {
-    "@esportsplus/typescript": "^0.29.0",
-    "@types/node": "^25.0.9",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "@esportsplus/typescript": "^0.29.1",
+    "@types/node": "^25.6.0",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
   },
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "scripts": {
     "build": "tsc",
     "build:test": "pnpm build && vite build --config test/vite.config.ts",

package/src/reactive/array.ts

@@ -84,9 +84,11 @@ class ReactiveArray<T> extends Array<T> {
             return;
         }
 
+        let length = this.length;
+
         this[i] = value;
 
-        if (i >= this.length) {
+        if (i >= length) {
             write(this._length, i + 1);
         }
 
@@ -309,6 +311,10 @@ class ReactiveArray<T> extends Array<T> {
     }
 
     unshift(...items: T[]) {
+        if (!items.length) {
+            return this.length;
+        }
+
         let length = super.unshift(...items);
 
         write(this._length, length);

package/tests/array.ts

@@ -91,11 +91,64 @@ describe('ReactiveArray', () => {
             arr.$set(5, 99);
             await Promise.resolve();
 
-            // Native .length is 6, but reactive _length check runs after
-            // this[i] = value so i >= this.length is false — _length not updated
             expect(arr.length).toBe(6);
             expect(arr[5]).toBe(99);
+            expect(lengths).toEqual([3, 6]);
+        });
+
+        it('$set creates sparse array and updates reactive $length', async () => {
+            let arr = new ReactiveArray<number>(),
+                lengths: number[] = [];
+
+            effect(() => {
+                lengths.push(arr.$length);
+            });
+
+            expect(lengths).toEqual([0]);
+
+            arr.$set(100, 42);
+            await Promise.resolve();
+
+            // Value is set at index 100
+            expect(arr[100]).toBe(42);
+
+            // Native length becomes 101 via Array behavior
+            expect(arr.length).toBe(101);
+
+            // Reactive $length updated correctly
+            expect(lengths).toEqual([0, 101]);
+
+            // Intermediate indices are empty (sparse)
+            expect(arr[0]).toBe(undefined);
+            expect(arr[50]).toBe(undefined);
+            expect(arr[99]).toBe(undefined);
+        });
+
+        it('$set with negative index does not affect length', () => {
+            let arr = new ReactiveArray(1, 2, 3);
+
+            arr.$set(-1 as any, 42);
+
+            expect(arr.length).toBe(3);
+            expect(arr.$length).toBe(3);
+            expect((arr as any)[-1]).toBe(42);
+        });
+
+        it('$set at large index updates $length', async () => {
+            let arr = new ReactiveArray(1, 2, 3),
+                lengths: number[] = [];
+
+            effect(() => {
+                lengths.push(arr.$length);
+            });
+
             expect(lengths).toEqual([3]);
+
+            arr.$set(10000, 99);
+            await Promise.resolve();
+
+            expect(arr.length).toBe(10001);
+            expect(lengths).toEqual([3, 10001]);
         });
     });
 
@@ -321,6 +374,26 @@ describe('ReactiveArray', () => {
 
             expect(events).toEqual([[1, 2]]);
         });
+
+        it('no-op for empty unshift', async () => {
+            let arr = new ReactiveArray(1, 2),
+                dispatched = false,
+                lengths: number[] = [];
+
+            arr.on('unshift', () => { dispatched = true; });
+
+            effect(() => { lengths.push(arr.$length); });
+
+            expect(lengths).toEqual([2]);
+
+            let result = arr.unshift();
+
+            await Promise.resolve();
+
+            expect(result).toBe(2);
+            expect(dispatched).toBe(false);
+            expect(lengths).toEqual([2]);
+        });
     });
 
 
@@ -369,6 +442,32 @@ describe('ReactiveArray', () => {
 
             expect(dispatched).toBe(false);
         });
+
+        it('splice with start beyond array length removes nothing', () => {
+            let arr = new ReactiveArray(1, 2, 3),
+                dispatched = false;
+
+            arr.on('splice', () => { dispatched = true; });
+
+            let removed = arr.splice(100, 1);
+
+            expect([...removed]).toEqual([]);
+            expect([...arr]).toEqual([1, 2, 3]);
+            expect(dispatched).toBe(false);
+        });
+
+        it('splice with negative start removes from end', () => {
+            let arr = new ReactiveArray(1, 2, 3, 4, 5),
+                events: { start: number; deleteCount: number; items: number[] }[] = [];
+
+            arr.on('splice', (e) => { events.push(e); });
+
+            let removed = arr.splice(-2, 1);
+
+            expect([...removed]).toEqual([4]);
+            expect([...arr]).toEqual([1, 2, 3, 5]);
+            expect(events).toEqual([{ start: -2, deleteCount: 1, items: [] }]);
+        });
     });
 
 
@@ -493,6 +592,20 @@ describe('ReactiveArray', () => {
 
             expect([...arr]).toEqual([1, 2, 2]);
         });
+
+        it('sort preserves object references', () => {
+            let a = { id: 3 },
+                b = { id: 1 },
+                c = { id: 2 },
+                arr = new ReactiveArray(a, b, c);
+
+            arr.sort((x, y) => x.id - y.id);
+
+            // Sorted order: b(1), c(2), a(3) — same object references
+            expect(arr[0]).toBe(b);
+            expect(arr[1]).toBe(c);
+            expect(arr[2]).toBe(a);
+        });
     });
 
 
@@ -654,6 +767,37 @@ describe('ReactiveArray', () => {
             expect(arr.listeners['push']!.length).toBe(1);
             expect(fn1).toHaveBeenCalledTimes(1);
         });
+
+        it('on() inserts after trailing nulls cleaned from dispatch', () => {
+            let arr = new ReactiveArray<number>(),
+                fn1 = vi.fn(),
+                fn2 = () => { throw new Error('err2'); },
+                fn3 = () => { throw new Error('err3'); };
+
+            arr.on('push', fn1);
+            arr.on('push', fn2);
+            arr.on('push', fn3);
+
+            // Dispatch: fn2 and fn3 throw → nulled → trailing nulls cleaned
+            // listeners = [fn1, null, null] → cleanup → [fn1]
+            arr.push(1);
+
+            expect(fn1).toHaveBeenCalledTimes(1);
+            expect(arr.listeners['push']!.length).toBe(1);
+
+            // Register fn4 — should append at index 1 (no holes left)
+            let fn4 = vi.fn();
+
+            arr.on('push', fn4);
+
+            expect(arr.listeners['push']!.length).toBe(2);
+
+            // Both fn1 and fn4 called on next push
+            arr.push(2);
+
+            expect(fn1).toHaveBeenCalledTimes(2);
+            expect(fn4).toHaveBeenCalledTimes(1);
+        });
     });
 
 

package/tests/async-computed.ts

@@ -160,6 +160,50 @@ describe('asyncComputed', () => {
         expect(read(node)).toBe(1);
     });
 
+    it('nested asyncComputed — B depends on A', async () => {
+        let s = signal(5),
+            nodeA!: ReturnType<typeof asyncComputed<number>>,
+            nodeB!: ReturnType<typeof asyncComputed<number>>;
+
+        root(() => {
+            nodeA = asyncComputed(() => Promise.resolve(read(s) * 2));
+
+            nodeB = asyncComputed(() => {
+                let a = read(nodeA);
+
+                if (a === undefined) {
+                    return Promise.resolve(0);
+                }
+
+                return Promise.resolve(a + 100);
+            });
+        });
+
+        // Initially both undefined
+        expect(read(nodeA)).toBeUndefined();
+        expect(read(nodeB)).toBeUndefined();
+
+        // Wait for A to resolve
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(read(nodeA)).toBe(10);
+
+        // Wait for B to react to A's resolved value
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(read(nodeB)).toBe(110);
+
+        // Update source signal — A and B should both update
+        write(s, 20);
+        await new Promise((r) => setTimeout(r, 20));
+
+        expect(read(nodeA)).toBe(40);
+
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(read(nodeB)).toBe(140);
+    });
+
     it('rejected promise does not crash and retains previous value', async () => {
         let node!: ReturnType<typeof asyncComputed<number>>,
             s = signal(1);

package/tests/bench/array.ts

@@ -102,6 +102,18 @@ describe('ReactiveArray sort', () => {
 
         arr.sort((a, b) => a - b);
     });
+
+    bench('sort 1000 items', () => {
+        let items = [];
+
+        for (let i = 1000; i > 0; i--) {
+            items.push(i);
+        }
+
+        let arr = new ReactiveArray(...items);
+
+        arr.sort((a, b) => a - b);
+    });
 });
 
 

package/tests/bench/reactive-object.ts

@@ -1,6 +1,4 @@
 import { bench, describe } from 'vitest';
-import { computed, dispose, effect, read, root, signal, write } from '~/system';
-import { ReactiveArray } from '~/reactive/array';
 import { ReactiveObject } from '~/reactive/object';
 
 
@@ -16,6 +14,13 @@ describe('ReactiveObject creation', () => {
             sum: () => 0
         });
     });
+
+    bench('create with async computed property', () => {
+        new ReactiveObject({
+            value: 1,
+            async: () => Promise.resolve(0)
+        });
+    });
 });
 
 

package/tests/bench/system.ts

@@ -1,5 +1,5 @@
 import { bench, describe } from 'vitest';
-import { computed, dispose, effect, onCleanup, read, root, signal, write } from '~/system';
+import { asyncComputed, computed, dispose, effect, onCleanup, read, root, signal, write } from '~/system';
 
 
 describe('signal', () => {
@@ -76,6 +76,19 @@ describe('computed', () => {
 });
 
 
+describe('asyncComputed', () => {
+    bench('create asyncComputed', () => {
+        asyncComputed(() => Promise.resolve(0));
+    });
+
+    bench('create asyncComputed from signal', () => {
+        let s = signal(0);
+
+        asyncComputed(() => Promise.resolve(read(s)));
+    });
+});
+
+
 describe('effect', () => {
     bench('create + dispose effect', () => {
         let stop = effect(() => {});
@@ -261,6 +274,26 @@ describe('deep propagation', () => {
 
         write(s, ++i);
     });
+
+    bench('deep chain (100 computeds)', () => {
+        let s = signal(0),
+            chain: ReturnType<typeof computed>[] = [],
+            i = 0;
+
+        chain[0] = computed(() => read(s) + 1);
+
+        for (let j = 1; j < 100; j++) {
+            let prev = chain[j - 1];
+
+            chain[j] = computed(() => read(prev) + 1);
+        }
+
+        effect(() => {
+            read(chain[99]);
+        });
+
+        write(s, ++i);
+    });
 });
 
 
@@ -284,6 +317,27 @@ describe('stabilization', () => {
 
         write(a, ++i);
     });
+
+    bench('read computed during stabilization', () => {
+        let a = signal(0),
+            b = signal(0),
+            c = computed(() => read(b) * 2),
+            i = 0;
+
+        effect(() => {
+            let val = read(a);
+
+            if (val > 0) {
+                write(b, val * 10);
+            }
+        });
+
+        effect(() => {
+            read(c);
+        });
+
+        write(a, ++i);
+    });
 });
 
 

package/tests/objects.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { computed, effect, read, signal, write } from '~/system';
+import { COMPUTED, REACTIVE_ARRAY } from '~/constants';
 import { ReactiveObject } from '~/reactive/object';
 import { ReactiveArray } from '~/reactive/array';
 import reactive from '~/reactive/index';
@@ -19,6 +20,15 @@ describe('reactive object patterns', () => {
             expect(obj.name).toBe('John');
         });
 
+        it('empty object constructor', () => {
+            let obj = new ReactiveObject({}) as any;
+
+            // No reactive properties created — only internal 'disposers' field
+            expect(Object.keys(obj).filter((k: string) => k !== 'disposers')).toEqual([]);
+
+            obj.dispose();
+        });
+
         it('updates multiple properties independently', async () => {
             let obj = new ReactiveObject({ age: 25, name: 'John' }) as any,
                 ages: number[] = [],
@@ -160,6 +170,65 @@ describe('reactive object patterns', () => {
     });
 
 
+    describe('subclass overrides', () => {
+        it('[COMPUTED] subclass creates computed field from external signal', async () => {
+            class Doubled extends ReactiveObject<Record<string, never>> {
+                private _doubled: ReturnType<typeof computed<number>>;
+
+                constructor(source: ReturnType<typeof signal<number>>) {
+                    super(null);
+                    this._doubled = this[COMPUTED](() => read(source) * 2);
+                }
+
+                get doubled() {
+                    return read(this._doubled);
+                }
+            }
+
+            let s = signal(5),
+                obj = new Doubled(s),
+                values: number[] = [];
+
+            expect(obj.doubled).toBe(10);
+
+            effect(() => {
+                values.push(obj.doubled);
+            });
+
+            expect(values).toEqual([10]);
+
+            write(s, 10);
+            await Promise.resolve();
+
+            expect(obj.doubled).toBe(20);
+            expect(values).toEqual([10, 20]);
+
+            obj.dispose();
+        });
+
+        it('[REACTIVE_ARRAY] subclass creates ReactiveArray field', () => {
+            class Collection extends ReactiveObject<Record<string, never>> {
+                items: ReactiveArray<number>;
+
+                constructor(values: number[]) {
+                    super(null);
+                    this.items = this[REACTIVE_ARRAY](values);
+                }
+            }
+
+            let obj = new Collection([10, 20, 30]);
+
+            expect(obj.items).toBeInstanceOf(ReactiveArray);
+            expect([...obj.items]).toEqual([10, 20, 30]);
+
+            obj.dispose();
+
+            // After dispose, array should be cleared
+            expect(obj.items.length).toBe(0);
+        });
+    });
+
+
     describe('dispose', () => {
         it('disposes object with computed properties', () => {
             let s = signal(42),
@@ -181,5 +250,20 @@ describe('reactive object patterns', () => {
 
             obj.dispose();
         });
+
+        it('calling dispose twice does not throw', () => {
+            let s = signal(1),
+                obj = new ReactiveObject({
+                    computed: () => read(s) * 2,
+                    items: [1, 2, 3]
+                }) as any;
+
+            expect(obj.computed).toBe(2);
+            expect([...obj.items]).toEqual([1, 2, 3]);
+
+            obj.dispose();
+
+            expect(() => obj.dispose()).not.toThrow();
+        });
     });
 });

package/tests/system.ts

@@ -423,6 +423,27 @@ describe('onCleanup', () => {
         expect(returned).toBe(fn);
         expect(fn).not.toHaveBeenCalled();
     });
+
+    it('throwing cleanup skips subsequent cleanups in same array', () => {
+        let called: number[] = [],
+            c = computed((onCleanup) => {
+            onCleanup(() => { called.push(1); });
+            onCleanup(() => { called.push(2); throw new Error('cleanup boom'); });
+            onCleanup(() => { called.push(3); });
+            return 42;
+        });
+
+        expect(called).toEqual([]);
+
+        // dispose() calls cleanup() synchronously — no try/catch wraps it
+        // cleanup iterates the array: index 0 (push 1), index 1 (push 2, throws)
+        // index 2 (push 3) is never reached because no try/catch in cleanup()
+        expect(() => dispose(c)).toThrow('cleanup boom');
+
+        expect(called).toContain(1);
+        expect(called).toContain(2);
+        expect(called).not.toContain(3);
+    });
 });
 
 
@@ -966,6 +987,135 @@ describe('edge cases', () => {
         expect(result).toBe(99);
     });
 
+    it('write during stabilization triggers reschedule and computed sees updated value', async () => {
+        let s1 = signal(1),
+            s2 = signal(0),
+            c = computed(() => read(s2) * 10),
+            cValues: number[] = [];
+
+        // Effect 1: writes to s2 when s1 changes — triggers during stabilization
+        effect(() => {
+            let val = read(s1);
+
+            if (val > 1) {
+                write(s2, val);
+            }
+        });
+
+        // Effect 2: reads computed c which depends on s2
+        effect(() => {
+            cValues.push(read(c));
+        });
+
+        expect(cValues).toEqual([0]);
+
+        // Write s1 → effect1 runs during stabilization → writes s2=5
+        // → reschedule → c recomputes with s2=5 → effect2 sees 50
+        write(s1, 5);
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(cValues).toEqual([0, 50]);
+    });
+
+    it('diamond with write during stabilization propagates through both branches', async () => {
+        let source = signal(1),
+            trigger = signal(0),
+            left = computed(() => read(source) + 1),
+            right = computed(() => read(source) * 2),
+            join = computed(() => read(left) + read(right)),
+            joinValues: number[] = [];
+
+        // Effect that writes source during stabilization
+        effect(() => {
+            let val = read(trigger);
+
+            if (val > 0) {
+                write(source, val);
+            }
+        });
+
+        // Effect that reads the diamond join
+        effect(() => {
+            joinValues.push(read(join));
+        });
+
+        // Initial: source=1, left=2, right=2, join=4
+        expect(joinValues).toEqual([4]);
+
+        // trigger=10 → effect writes source=10 → reschedule
+        // left=11, right=20, join=31
+        write(trigger, 10);
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(joinValues).toEqual([4, 31]);
+    });
+
+    it('disposed computed does not prevent new computed from reading same signal', async () => {
+        let s = signal(10),
+            c1 = computed(() => read(s) * 2),
+            c2Values: number[] = [];
+
+        expect(read(c1)).toBe(20);
+
+        dispose(c1);
+
+        // After dispose, c1 retains its last computed value
+        expect(c1.value).toBe(20);
+
+        // New computed can read the same signal
+        let c2 = computed(() => read(s) + 5);
+
+        expect(read(c2)).toBe(15);
+
+        // Subscribe with an effect so c2 reacts to changes
+        effect(() => {
+            c2Values.push(read(c2));
+        });
+
+        expect(c2Values).toEqual([15]);
+
+        // Signal still propagates to new computed
+        write(s, 20);
+        await Promise.resolve();
+
+        expect(c2Values).toEqual([15, 25]);
+
+        // Disposed computed value is stale — not updated
+        expect(c1.value).toBe(20);
+    });
+
+    it('disposed computed retains last value and does not recompute', async () => {
+        let s = signal(1),
+            calls = 0,
+            c = computed(() => {
+                calls++;
+                return read(s) * 3;
+            }),
+            result = -1;
+
+        // Subscribe so it's in the heap
+        effect(() => {
+            result = read(c);
+        });
+
+        expect(result).toBe(3);
+        expect(calls).toBe(1);
+
+        dispose(c);
+
+        // After disposal, value is retained
+        expect(c.value).toBe(3);
+
+        write(s, 10);
+        await Promise.resolve();
+
+        // Not recomputed after dispose
+        expect(calls).toBe(1);
+        expect(c.value).toBe(3);
+    });
+
     it('link pool handles >1000 dependencies with disposal and reuse', async () => {
         let signals: ReturnType<typeof signal>[] = [],
             stops: (() => void)[] = [];

package/tests/tsconfig.json

@@ -1,11 +1,10 @@
 {
     "extends": "../tsconfig.json",
     "compilerOptions": {
-        "baseUrl": "..",
         "noEmit": true,
         "paths": {
             "~/*": [
-                "src/*"
+                "../src/*"
             ]
         },
         "rootDir": ".."