@esportsplus/reactivity 0.31.3 → 0.32.0

package/test/errors.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest';
+import { computed, effect, read, signal, write } from '~/system';
+import { tick } from './lib/wait-for';
+
+
+async function captureUncaught(run: () => void | Promise<void>): Promise<unknown[]> {
+    let captured: unknown[] = [],
+        listeners = process.listeners('uncaughtException');
+
+    process.removeAllListeners('uncaughtException');
+    process.on('uncaughtException', capture);
+
+    function capture(e: unknown) {
+        captured.push(e);
+    }
+
+    try {
+        await run();
+        await tick();
+    }
+    finally {
+        process.removeListener('uncaughtException', capture);
+
+        for (let i = 0, n = listeners.length; i < n; i++) {
+            process.on('uncaughtException', listeners[i]);
+        }
+    }
+
+    return captured;
+}
+
+
+describe('computed error caching', () => {
+    it('caches the error and rethrows at read without re-running fn', async () => {
+        let calls = 0,
+            s = signal(1),
+            c = computed(() => {
+                calls++;
+
+                if (read(s) % 2 !== 0) {
+                    throw new Error('odd');
+                }
+
+                return read(s);
+            });
+
+        expect(() => read(c)).toThrow('odd');
+        expect(calls).toBe(1);
+
+        expect(() => read(c)).toThrow('odd');
+        expect(() => read(c)).toThrow('odd');
+        expect(calls).toBe(1);
+
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(read(c)).toBe(2);
+        expect(calls).toBe(2);
+    });
+
+    it('rethrows the exact error instance', () => {
+        let error = new Error('boom'),
+            c = computed(() => {
+                throw error;
+            });
+
+        try {
+            read(c);
+            expect.unreachable();
+        }
+        catch (e) {
+            expect(e).toBe(error);
+        }
+    });
+
+    it('propagates through a computed chain', async () => {
+        let s = signal(1),
+            c1 = computed(() => {
+                if (read(s) % 2 !== 0) {
+                    throw new Error('odd');
+                }
+
+                return read(s);
+            }),
+            c2 = computed(() => read(c1)),
+            c3 = computed(() => read(c2));
+
+        expect(() => read(c3)).toThrow('odd');
+
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(read(c3)).toBe(2);
+    });
+
+    it('error to success with unchanged value still wakes dependents', async () => {
+        let s = signal(0),
+            c1 = computed(() => {
+                if (read(s) % 2 !== 0) {
+                    throw new Error('odd');
+                }
+
+                return 10;
+            }),
+            c2 = computed(() => read(c1));
+
+        expect(read(c2)).toBe(10);
+
+        write(s, 1);
+        await Promise.resolve();
+
+        expect(() => read(c2)).toThrow('odd');
+
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(read(c2)).toBe(10);
+    });
+});
+
+
+describe('effect error contract', () => {
+    it('effect without onError rethrows via microtask on first-run failure', async () => {
+        let captured = await captureUncaught(() => {
+            effect(() => {
+                throw new Error('first run boom');
+            });
+        });
+
+        expect(captured.length).toBe(1);
+        expect((captured[0] as Error).message).toBe('first run boom');
+    });
+
+    it('effect without onError rethrows via microtask on dependency-triggered failure', async () => {
+        let s = signal(0),
+            stop = effect(() => {
+                if (read(s) === 1) {
+                    throw new Error('effect boom');
+                }
+            });
+
+        let captured = await captureUncaught(() => {
+            write(s, 1);
+        });
+
+        expect(captured.length).toBe(1);
+        expect((captured[0] as Error).message).toBe('effect boom');
+
+        stop();
+    });
+
+    it('effect rethrows on every failure, not just the first', async () => {
+        let s = signal(0),
+            stop = effect(() => {
+                let val = read(s);
+
+                if (val % 2 !== 0) {
+                    throw new Error(`boom ${val}`);
+                }
+            });
+
+        let captured = await captureUncaught(async () => {
+            write(s, 1);
+            await tick();
+            write(s, 2);
+            await tick();
+            write(s, 3);
+        });
+
+        expect(captured.length).toBe(2);
+        expect((captured[0] as Error).message).toBe('boom 1');
+        expect((captured[1] as Error).message).toBe('boom 3');
+
+        stop();
+    });
+
+    it('effect onError receives the error and nothing rethrows', async () => {
+        let errors: unknown[] = [],
+            s = signal(0),
+            stop = effect(
+                () => {
+                    if (read(s) === 1) {
+                        throw new Error('handled');
+                    }
+                },
+                (e) => {
+                    errors.push(e);
+                }
+            );
+
+        let captured = await captureUncaught(() => {
+            write(s, 1);
+        });
+
+        expect(captured.length).toBe(0);
+        expect(errors.length).toBe(1);
+        expect((errors[0] as Error).message).toBe('handled');
+
+        stop();
+    });
+});

package/test/flush.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import { batch, computed, effect, flush, read, signal, write } from '~/system';
+
+
+describe('flush()', () => {
+    it('runs the dependent effect synchronously before returning', () => {
+        let runs = 0,
+            s = signal(0);
+
+        effect(() => {
+            runs++;
+            read(s);
+        });
+
+        expect(runs).toBe(1);
+
+        write(s, 1);
+
+        expect(runs).toBe(1);
+
+        flush();
+
+        expect(runs).toBe(2);
+    });
+
+    it('drains a write-during-effect reschedule tail before returning', () => {
+        let s = signal(0),
+            c = computed(() => read(s) + 1),
+            innerRuns = 0,
+            outerRuns = 0,
+            proof = signal(0);
+
+        effect(() => {
+            outerRuns++;
+
+            if (read(c) === 2) {
+                write(proof, 1);
+            }
+        });
+
+        effect(() => {
+            innerRuns++;
+            read(proof);
+        });
+
+        expect(outerRuns).toBe(1);
+        expect(innerRuns).toBe(1);
+
+        write(s, 1);
+        flush();
+
+        expect(outerRuns).toBe(2);
+        expect(innerRuns).toBe(2);
+        expect(read(proof)).toBe(1);
+    });
+
+    it('is a safe no-op when called re-entrantly during stabilization, and does not block subsequent propagation', () => {
+        let effectARuns = 0,
+            effectBRuns = 0,
+            s = signal(0),
+            t = signal(0);
+
+        effect(() => {
+            effectARuns++;
+
+            if (read(s) === 1) {
+                flush();
+                write(t, 99);
+            }
+        });
+
+        effect(() => {
+            effectBRuns++;
+            read(t);
+        });
+
+        write(s, 1);
+        flush();
+
+        expect(effectARuns).toBe(2);
+        expect(effectBRuns).toBe(2);
+        expect(read(t)).toBe(99);
+    });
+
+    it('is a no-op when nothing is pending', () => {
+        expect(() => flush()).not.toThrow();
+    });
+
+    it('leaves the previously-queued microtask as a no-op after a manual flush', async () => {
+        let runs = 0,
+            s = signal(0);
+
+        effect(() => {
+            runs++;
+            read(s);
+        });
+
+        write(s, 1);
+        flush();
+
+        expect(runs).toBe(2);
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(runs).toBe(2);
+    });
+});
+
+describe('batch()', () => {
+    it('defers scheduling until the batch completes, producing exactly one effect re-run', async () => {
+        let runs = 0,
+            s1 = signal(0),
+            s2 = signal(0);
+
+        effect(() => {
+            runs++;
+            read(s1);
+            read(s2);
+        });
+
+        expect(runs).toBe(1);
+
+        batch(() => {
+            write(s1, 1);
+            write(s2, 2);
+        });
+
+        await Promise.resolve();
+
+        expect(runs).toBe(2);
+    });
+
+    it('settles synchronously when paired with flush', () => {
+        let runs = 0,
+            s1 = signal(0),
+            s2 = signal(0);
+
+        effect(() => {
+            runs++;
+            read(s1);
+            read(s2);
+        });
+
+        batch(() => {
+            write(s1, 1);
+            write(s2, 2);
+        });
+        flush();
+
+        expect(runs).toBe(2);
+    });
+
+    it('returns the wrapped function value', () => {
+        let result = batch(() => 42);
+
+        expect(result).toBe(42);
+    });
+
+    it('restores depth when the wrapped function throws', () => {
+        let s = signal(0);
+
+        expect(() => {
+            batch(() => {
+                write(s, 1);
+                throw new Error('reactivity: test error');
+            });
+        }).toThrow('reactivity: test error');
+
+        // depth must have unwound to 0, so a fresh write schedules normally instead of deferring forever.
+        let runs = 0;
+
+        effect(() => {
+            runs++;
+            read(s);
+        });
+
+        expect(runs).toBe(1);
+
+        write(s, 2);
+        flush();
+
+        expect(runs).toBe(2);
+    });
+});

package/test/glitch-freedom.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+import { computed, effect, read, signal, write } from '~/system';
+
+
+// Correctness guarantees the algorithm items (read-version-dedup,
+// global-version-fast-path, pending-only-writes) must preserve
+
+describe('glitch freedom', () => {
+    it('diamond: join computes exactly once per write and never observes mixed state', async () => {
+        let s = signal(1),
+            observed: [number, number][] = [],
+            b = computed(() => read(s) + 1),
+            c = computed(() => read(s) * 2),
+            d = computed(() => {
+                let bv = read(b),
+                    cv = read(c);
+
+                observed.push([bv, cv]);
+
+                return bv + cv;
+            });
+
+        effect(() => {
+            read(d);
+        });
+
+        expect(read(d)).toBe(4);
+
+        observed.length = 0;
+
+        write(s, 2);
+        await Promise.resolve();
+
+        // One run, and the pair is consistent for s=2 — never a mixed b/c state
+        expect(observed).toEqual([[3, 4]]);
+        expect(read(d)).toBe(7);
+
+        observed.length = 0;
+
+        write(s, 5);
+        await Promise.resolve();
+
+        expect(observed).toEqual([[6, 10]]);
+        expect(read(d)).toBe(16);
+    });
+
+    it('unstable: dynamic dep swap mid-propagation settles correctly with no double-run', async () => {
+        let runs = 0,
+            s = signal(1),
+            double = computed(() => read(s) * 2),
+            inverse = computed(() => -read(s)),
+            current = computed(() => {
+                runs++;
+
+                return read(s) % 2 ? read(double) : read(inverse);
+            });
+
+        // Keepers hold a subscription on both branches — last-sub unlink auto-disposes a computed
+        effect(() => {
+            read(double);
+        });
+
+        effect(() => {
+            read(inverse);
+        });
+
+        effect(() => {
+            read(current);
+        });
+
+        expect(read(current)).toBe(2);
+
+        runs = 0;
+
+        write(s, 2);
+        await Promise.resolve();
+
+        // Swapped from double to inverse in one settle pass
+        expect(read(current)).toBe(-2);
+        expect(runs).toBe(1);
+
+        runs = 0;
+
+        write(s, 3);
+        await Promise.resolve();
+
+        // Swapped back
+        expect(read(current)).toBe(6);
+        expect(runs).toBe(1);
+    });
+
+    it('repeated observers: one effect reading the same signal 3x re-runs exactly once per write', async () => {
+        let runs = 0,
+            s = signal(0);
+
+        effect(() => {
+            read(s);
+            read(s);
+            read(s);
+            runs++;
+        });
+
+        expect(runs).toBe(1);
+
+        write(s, 1);
+        await Promise.resolve();
+
+        expect(runs).toBe(2);
+
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(runs).toBe(3);
+    });
+});

package/test/invalidate.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest';
+import { computed, effect, flush, peek, read, signal, write } from '~/system';
+import { waitFor } from './lib/wait-for';
+
+
+describe('invalidate()', () => {
+    it('re-runs the computed fn with no dependency change', () => {
+        let runs = 0,
+            s = signal(1);
+
+        let c = computed(() => {
+            runs++;
+
+            return read(s);
+        });
+
+        effect(() => {
+            read(c);
+        });
+
+        expect(runs).toBe(1);
+
+        computed.invalidate(c);
+        flush();
+
+        expect(runs).toBe(2);
+    });
+
+    it('dependents re-run only when the forced re-run changes the value', () => {
+        let changingRuns = 0,
+            s = signal(1),
+            stableRuns = 0,
+            ticks = 0;
+
+        let changing = computed(() => {
+            read(s);
+
+            return ++ticks;
+        });
+
+        let stable = computed(() => read(s));
+
+        effect(() => {
+            stableRuns++;
+            read(stable);
+        });
+
+        effect(() => {
+            changingRuns++;
+            read(changing);
+        });
+
+        computed.invalidate(stable);
+        flush();
+
+        expect(stableRuns).toBe(1);
+
+        computed.invalidate(changing);
+        flush();
+
+        expect(changingRuns).toBe(2);
+    });
+
+    it('re-dispatches an asyncComputed factory (refetch via the asyncMeta redirect)', async () => {
+        let fetches = 0;
+
+        let node = computed(() => {
+            fetches++;
+
+            return Promise.resolve(fetches);
+        });
+
+        let stop = effect(() => {
+            read(node);
+        });
+
+        await waitFor(() => read(node) === 1, 'node resolves to 1');
+
+        expect(fetches).toBe(1);
+        expect(read(node)).toBe(1);
+
+        computed.invalidate(node);
+        await waitFor(() => read(node) === 2, 'node refetches to 2');
+
+        expect(fetches).toBe(2);
+        expect(read(node)).toBe(2);
+
+        stop();
+    });
+
+    it('forces a side-effecting computed (the public effect encoding) to re-run without propagating', () => {
+        let keeperRuns = 0,
+            s = signal(1),
+            sideRuns = 0;
+
+        let c = computed<void>(() => {
+            read(s);
+            sideRuns++;
+        });
+
+        effect(() => {
+            keeperRuns++;
+            read(c);
+        });
+
+        expect(sideRuns).toBe(1);
+        expect(keeperRuns).toBe(1);
+
+        computed.invalidate(c);
+        flush();
+
+        expect(sideRuns).toBe(2);
+        expect(keeperRuns).toBe(1);
+    });
+
+    it('the global-version fast path does not swallow a forced re-run', () => {
+        let runs = 0,
+            s = signal(1);
+
+        let c = computed(() => {
+            runs++;
+
+            return read(s);
+        });
+
+        effect(() => {
+            read(c);
+        });
+
+        write(s, 2);
+        flush();
+
+        expect(runs).toBe(2);
+
+        // Fully settled: c carries the current gv stamp. Without writes++ inside invalidate,
+        // this synchronous pull would exit through the fast path and skip the re-run. peek()
+        // forces the pull unconditionally (read() outside an observer returns the cached value).
+        computed.invalidate(c);
+
+        expect(peek(c)).toBe(2);
+        expect(runs).toBe(3);
+
+        flush();
+
+        expect(runs).toBe(3);
+    });
+});

package/test/lib/wait-for.ts

@@ -0,0 +1,28 @@
+const tick = (times = 1): Promise<void> => {
+    let p = Promise.resolve();
+
+    for (let i = 0; i < times; i++) {
+        p = p.then(() => new Promise<void>((resolve) => setTimeout(resolve, 0)));
+    }
+
+    return p;
+};
+
+const waitFor = (condition: () => boolean, description: string, timeoutMs = 1000): Promise<void> => {
+    return new Promise<void>((resolve, reject) => {
+        let deadline = Date.now() + timeoutMs,
+            timer = setInterval(() => {
+                if (condition()) {
+                    clearInterval(timer);
+                    resolve();
+                }
+                else if (Date.now() >= deadline) {
+                    clearInterval(timer);
+                    reject(new Error('wait-for: timed out waiting for ' + description));
+                }
+            }, 10);
+    });
+};
+
+
+export { tick, waitFor };