@zeix/cause-effect 0.10.1 → 0.12.0

package/test/effect.test.ts

@@ -0,0 +1,157 @@
+import { describe, test, expect, mock } from 'bun:test'
+import { state, computed, effect, UNSET } from '../'
+
+/* === Utility Functions === */
+
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+/* === Tests === */
+
+describe('Effect', function () {
+
+	test('should be triggered after a state change', function() {
+		const cause = state('foo');
+		let count = 0;
+		effect((_value) => {
+			count++;
+		}, cause);
+		expect(count).toBe(1);
+		cause.set('bar');
+		expect(count).toBe(2);
+	});
+
+	test('should be triggered after computed async signals resolve without waterfalls', async function() {
+		const a = computed(async () => {
+			await wait(100);
+			return 10;
+		});
+		const b = computed(async () => {
+			await wait(100);
+			return 20;
+		});
+		let result = 0;
+		let count = 0;
+		effect((aValue, bValue) => {
+			result = aValue + bValue;
+			count++;
+		}, a, b);
+		expect(result).toBe(0);
+		expect(count).toBe(0);
+		await wait(110);
+		expect(result).toBe(30);
+		expect(count).toBe(1);
+	});
+
+	test('should be triggered repeatedly after repeated state change', async function() {
+		const cause = state(0);
+		let result = 0;
+		let count = 0;
+		effect((res) => {
+			result = res;
+			count++;
+		}, cause);
+		for (let i = 0; i < 10; i++) {
+			cause.set(i);
+			expect(result).toBe(i);
+			expect(count).toBe(i + 1); // + 1 for effect initialization
+		}
+	});
+
+	test('should handle errors in effects', function() {
+		const a = state(1);
+		const b = computed(() => {
+			if (a.get() > 5) throw new Error('Value too high');
+			return a.get() * 2;
+		});
+		let normalCallCount = 0;
+		let errorCallCount = 0;
+		effect({
+			ok: (_bValue) => {
+				// console.log('Normal effect:', _bValue);
+				normalCallCount++;
+			},
+			err: (error) => {
+				// console.log('Error effect:', error);
+				errorCallCount++;
+				expect(error.message).toBe('Value too high');
+			}
+		}, b);
+	
+		// Normal case
+		a.set(2);
+		expect(normalCallCount).toBe(2);
+		expect(errorCallCount).toBe(0);
+	
+		// Error case
+		a.set(6);
+		expect(normalCallCount).toBe(2);
+		expect(errorCallCount).toBe(1);
+	
+		// Back to normal
+		a.set(3);
+		expect(normalCallCount).toBe(3);
+		expect(errorCallCount).toBe(1);
+	});
+
+	test('should handle UNSET values in effects', async function() {
+		const a = computed(async () => {
+			await wait(100);
+			return 42;
+		});
+		let normalCallCount = 0;
+		let nilCount = 0;
+		effect({
+			ok: (aValue) => {
+				normalCallCount++;
+				expect(aValue).toBe(42);
+			},
+			nil: () => {
+				nilCount++
+			}
+		}, a);
+
+		expect(normalCallCount).toBe(0);
+		expect(nilCount).toBe(1);
+		expect(a.get()).toBe(UNSET);
+		await wait(110);
+		expect(normalCallCount).toBe(2); // + 1 for effect initialization
+		expect(a.get()).toBe(42);
+	});
+
+	test('should log error to console when error is not handled', () => {
+        // Mock console.error
+        const originalConsoleError = console.error;
+        const mockConsoleError = mock((message: string, error: Error) => {});
+        console.error = mockConsoleError;
+
+        try {
+            const a = state(1);
+            const b = computed(() => {
+                if (a.get() > 5) throw new Error('Value too high');
+                return a.get() * 2;
+            });
+
+            // Create an effect without explicit error handling
+            effect(() => {
+                b.get();
+            });
+
+            // This should trigger the error
+            a.set(6);
+
+            // Check if console.error was called with the expected message
+            expect(mockConsoleError).toHaveBeenCalledWith(
+                'Unhandled error in effect:',
+                expect.any(Error)
+            );
+
+            // Check the error message
+            const [, error] = mockConsoleError.mock.calls[0];
+            expect(error.message).toBe('Value too high');
+
+        } finally {
+            // Restore the original console.error
+            console.error = originalConsoleError;
+        }
+    });
+});

package/test/state.test.ts

@@ -0,0 +1,199 @@
+import { describe, test, expect } from 'bun:test'
+import { state, isComputed, UNSET } from '../'
+
+/* === Tests === */
+
+describe('State', function () {
+
+	describe('Boolean cause', function () {
+
+		test('should be boolean', function () {
+			const cause = state(false);
+			expect(typeof cause.get()).toBe('boolean');
+		});
+
+		test('should set initial value to false', function () {
+			const cause = state(false);
+			expect(cause.get()).toBe(false);
+		});
+
+		test('should set initial value to true', function () {
+			const cause = state(true);
+			expect(cause.get()).toBe(true);
+		});
+
+		test('should set new value with .set(true)', function () {
+			const cause = state(false);
+			cause.set(true);
+			expect(cause.get()).toBe(true);
+		});
+
+		test('should toggle initial value with .set(v => !v)', function () {
+			const cause = state(false);
+			cause.update((v) => !v);
+			expect(cause.get()).toBe(true);
+		});
+
+	});
+
+	describe('Number cause', function () {
+
+		test('should be number', function () {
+			const cause = state(0);
+			expect(typeof cause.get()).toBe('number');
+		});
+
+		test('should set initial value to 0', function () {
+			const cause = state(0);
+			expect(cause.get()).toBe(0);
+		});
+
+		test('should set new value with .set(42)', function () {
+			const cause = state(0);
+			cause.set(42);
+			expect(cause.get()).toBe(42);
+		});
+
+		test('should increment value with .set(v => ++v)', function () {
+			const cause = state(0);
+			cause.update(v => ++v);
+			expect(cause.get()).toBe(1);
+		});
+
+	});
+
+	describe('String cause', function () {
+
+		test('should be string', function () {
+			const cause = state('foo');
+			expect(typeof cause.get()).toBe('string');
+		});
+
+		test('should set initial value to "foo"', function () {
+			const cause = state('foo');
+			expect(cause.get()).toBe('foo');
+		});
+
+		test('should set new value with .set("bar")', function () {
+			const cause = state('foo');
+			cause.set('bar');
+			expect(cause.get()).toBe('bar');
+		});
+
+		test('should upper case value with .set(v => v.toUpperCase())', function () {
+			const cause = state('foo');
+			cause.update(v => v ? v.toUpperCase() : '');
+			expect(cause.get()).toBe("FOO");
+		});
+
+	});
+
+	describe('Array cause', function () {
+
+		test('should be array', function () {
+			const cause = state([1, 2, 3]);
+			expect(Array.isArray(cause.get())).toBe(true);
+		});
+
+		test('should set initial value to [1, 2, 3]', function () {
+			const cause = state([1, 2, 3]);
+			expect(cause.get()).toEqual([1, 2, 3]);
+		});
+
+		test('should set new value with .set([4, 5, 6])', function () {
+			const cause = state([1, 2, 3]);
+			cause.set([4, 5, 6]);
+			expect(cause.get()).toEqual([4, 5, 6]);
+		});
+
+		test('should reflect current value of array after modification', function () {
+			const array = [1, 2, 3];
+			const cause = state(array);
+			array.push(4); // don't do this! the result will be correct, but we can't trigger effects
+			expect(cause.get()).toEqual([1, 2, 3, 4]);
+		});
+
+		test('should set new value with .set([...array, 4])', function () {
+			const array = [1, 2, 3];
+			const cause = state(array);
+			cause.set([...array, 4]); // use destructuring instead!
+			expect(cause.get()).toEqual([1, 2, 3, 4]);
+		});
+
+	});
+
+	describe('Object cause', function () {
+
+		test('should be object', function () {
+			const cause = state({ a: 'a', b: 1 });
+			expect(typeof cause.get()).toBe('object');
+		});
+
+		test('should set initial value to { a: "a", b: 1 }', function () {
+			const cause = state({ a: 'a', b: 1 });
+			expect(cause.get()).toEqual({ a: 'a', b: 1 });
+		});
+
+		test('should set new value with .set({ c: true })', function () {
+			const cause = state<Record<string, any>>({ a: 'a', b: 1 });
+			cause.set({ c: true });
+			expect(cause.get()).toEqual({ c: true });
+		});
+
+		test('should reflect current value of object after modification', function () {
+			const obj = { a: 'a', b: 1 };
+			const cause = state<Record<string, any>>(obj);
+			// @ts-expect-error
+			obj.c = true; // don't do this! the result will be correct, but we can't trigger effects
+			expect(cause.get()).toEqual({ a: 'a', b: 1, c: true });
+		});
+
+		test('should set new value with .set({...obj, c: true})', function () {
+			const obj = { a: 'a', b: 1 };
+			const cause = state<Record<string, any>>(obj);
+			cause.set({...obj, c: true}); // use destructuring instead!
+			expect(cause.get()).toEqual({ a: 'a', b: 1, c: true });
+		});
+
+	});
+
+	describe('Map method', function () {
+
+		test('should return a computed signal', function() {
+			const cause = state(42);
+			const double = cause.map(v => v * 2);
+			expect(isComputed(double)).toBe(true);
+			expect(double.get()).toBe(84);
+		});
+
+	});
+
+	describe('Match method', function () {
+
+		test('should create an effect that reacts on signal changes', function() {
+			const cause = state(42);
+			let okCount = 0;
+			let nilCount = 0;
+			let result: number = 0;
+			cause.match({
+				ok: v => {
+					result = v;
+					okCount++
+				},
+				nil: () => {
+					nilCount++
+				}
+			})
+			cause.set(43);
+			expect(okCount).toBe(2); // + 1 for effect initialization 
+			expect(nilCount).toBe(0);
+			expect(result).toBe(43);
+
+			cause.set(UNSET);
+			expect(okCount).toBe(2);
+			expect(nilCount).toBe(1);
+		});
+
+	});
+
+});

package/test/util/dependency-graph.ts

@@ -1,4 +1,12 @@
-import { pseudoRandom } from './pseudo-random'
+import { TestConfig } from "./framework-types";
+import { Computed, ReactiveFramework, Signal } from "./reactive-framework";
+import { Random } from "random";
+
+export interface Graph {
+  sources: Signal<number>[];
+  layers: Computed<number>[][];
+}
+
 /**
  * Make a rectangular dependency graph, with an equal number of source elements
  * and computation elements at every layer.
@@ -8,11 +16,15 @@ import { pseudoRandom } from './pseudo-random'
  * @param staticFraction every nth computed node is static (1 = all static, 3 = 2/3rd are dynamic)
  * @returns the graph
  */
-export function makeGraph(framework, config) {
+export function makeGraph(
+  framework: ReactiveFramework,
+  config: TestConfig,
+  counter: Counter
+): Graph {
   const { width, totalLayers, staticFraction, nSources } = config;
+
   return framework.withBuild(() => {
     const sources = new Array(width).fill(0).map((_, i) => framework.signal(i));
-    const counter = new Counter();
     const rows = makeDependentRows(
       sources,
       totalLayers - 1,
@@ -22,54 +34,95 @@ export function makeGraph(framework, config) {
       framework
     );
     const graph = { sources, layers: rows };
-    return { graph, counter };
+    return graph;
   });
 }
+
 /**
  * Execute the graph by writing one of the sources and reading some or all of the leaves.
  *
  * @return the sum of all leaf values
  */
-export function runGraph(graph, iterations, readFraction, framework) {
-  const rand = pseudoRandom();
+export function runGraph(
+  graph: Graph,
+  iterations: number,
+  readFraction: number,
+  framework: ReactiveFramework
+): number {
+  const rand = new Random("seed");
   const { sources, layers } = graph;
   const leaves = layers[layers.length - 1];
   const skipCount = Math.round(leaves.length * (1 - readFraction));
   const readLeaves = removeElems(leaves, skipCount, rand);
-  for (let i = 0; i < iterations; i++) {
+  const frameworkName = framework.name.toLowerCase();
+  // const start = Date.now();
+  let sum = 0;
+
+  if (frameworkName === "s-js" || frameworkName === "solidjs") {
+    // [S.js freeze](https://github.com/adamhaile/S#sdatavalue) doesn't allow different values to be set during a single batch, so special case it.
+    for (let i = 0; i < iterations; i++) {
+      framework.withBatch(() => {
+        const sourceDex = i % sources.length;
+        sources[sourceDex].write(i + sourceDex);
+      });
+
+      for (const leaf of readLeaves) {
+        leaf.read();
+      }
+    }
+
+    sum = readLeaves.reduce((total, leaf) => leaf.read() + total, 0);
+  } else {
     framework.withBatch(() => {
-      const sourceDex = i % sources.length;
-      sources[sourceDex].write(i + sourceDex);
+      for (let i = 0; i < iterations; i++) {
+        // Useful for debugging edge cases for some frameworks that experience
+        // dramatic slow downs for certain test configurations. These are generally
+        // due to `computed` effects not being cached efficiently, and as the number
+        // of layers increases, the uncached `computed` effects are re-evaluated in
+        // an `O(n^2)` manner where `n` is the number of layers.
+        /* if (i % 100 === 0) {
+           console.log("iteration:", i, "delta:", Date.now() - start);
+        } */
+
+        const sourceDex = i % sources.length;
+        sources[sourceDex].write(i + sourceDex);
+
+        for (const leaf of readLeaves) {
+          leaf.read();
+        }
+      }
+	  
+      sum = readLeaves.reduce((total, leaf) => leaf.read() + total, 0);
     });
-    for (const leaf of readLeaves) {
-      leaf.read();
-    }
   }
-  const sum = readLeaves.reduce((total, leaf) => leaf.read() + total, 0);
+
   return sum;
 }
-function removeElems(src, rmCount, rand) {
+
+function removeElems<T>(src: T[], rmCount: number, rand: Random): T[] {
   const copy = src.slice();
   for (let i = 0; i < rmCount; i++) {
-    const rmDex = Math.floor(rand() * copy.length);
+    const rmDex = rand.int(0, copy.length - 1);
     copy.splice(rmDex, 1);
   }
   return copy;
 }
+
 export class Counter {
-	count = 0;
+  count = 0;
 }
+
 function makeDependentRows(
-  sources,
-  numRows,
-  counter,
-  staticFraction,
-  nSources,
-  framework
-): { read: number }[][] {
+  sources: Computed<number>[],
+  numRows: number,
+  counter: Counter,
+  staticFraction: number,
+  nSources: number,
+  framework: ReactiveFramework
+): Computed<number>[][] {
   let prevRow = sources;
-  const random = pseudoRandom();
-  const rows: {read: number}[][] = [];
+  const rand = new Random("seed");
+  const rows = [];
   for (let l = 0; l < numRows; l++) {
     const row = makeRow(
       prevRow,
@@ -78,32 +131,35 @@ function makeDependentRows(
       nSources,
       framework,
       l,
-      random
+      rand
     );
-    rows.push(row);
+    rows.push(row as never);
     prevRow = row;
   }
   return rows;
 }
+
 function makeRow(
-  sources,
-  counter,
-  staticFraction,
-  nSources,
-  framework,
-  layer,
-  random
-) {
+  sources: Computed<number>[],
+  counter: Counter,
+  staticFraction: number,
+  nSources: number,
+  framework: ReactiveFramework,
+  _layer: number,
+  random: Random
+): Computed<number>[] {
   return sources.map((_, myDex) => {
-    const mySources: { read(): number }[] = [];
+    const mySources: Computed<number>[] = [];
     for (let sourceDex = 0; sourceDex < nSources; sourceDex++) {
       mySources.push(sources[(myDex + sourceDex) % sources.length]);
     }
-    const staticNode = random() < staticFraction;
+
+    const staticNode = random.float() < staticFraction;
     if (staticNode) {
       // static node, always reference sources
       return framework.computed(() => {
         counter.count++;
+
         let sum = 0;
         for (const src of mySources) {
           sum += src.read();
@@ -119,10 +175,12 @@ function makeRow(
         let sum = first.read();
         const shouldDrop = sum & 0x1;
         const dropDex = sum % tail.length;
+
         for (let i = 0; i < tail.length; i++) {
           if (shouldDrop && i === dropDex) continue;
           sum += tail[i].read();
         }
+
         return sum;
       });
       return node;

package/test/util/framework-types.ts

@@ -0,0 +1,53 @@
+import { TestResult } from "./perf-tests";
+import { ReactiveFramework } from "./reactive-framework";
+
+/** Parameters for a running a performance benchmark test
+ *
+ * The benchmarks create a rectangular grid of reactive elements, with
+ * mutable signals in the first level, computed elements in the middle levels,
+ * and read effect elements in the last level.
+ *
+ * Each test iteration modifies one signal, and then reads specified
+ * fraction of the effect elements.
+ *
+ * Each non-signal node sums values from a specified number of elements
+ * in the preceding layer. Some nodes are dynamic, and read vary
+ * the number of sources the read for the sum.
+ *
+ * Tests may optionally provide result values to verify the sum
+ * of all read effect elements in all iterations, and the total
+ * number of non-signal updated.
+ */
+export interface TestConfig {
+  /** friendly name for the test, should be unique */
+  name?: string;
+
+  /** width of dependency graph to construct */
+  width: number;
+
+  /** depth of dependency graph to construct */
+  totalLayers: number;
+
+  /** fraction of nodes that are static */ // TODO change to dynamicFraction
+  staticFraction: number;
+
+  /** construct a graph with number of sources in each node */
+  nSources: number;
+
+  /** fraction of [0, 1] elements in the last layer from which to read values in each test iteration */
+  readFraction: number;
+
+  /** number of test iterations */
+  iterations: number;
+
+  /** sum and count of all iterations, for verification */
+  expected: Partial<TestResult>;
+}
+
+export interface FrameworkInfo {
+  /** wrapper/adapter for a benchmarking a reactive framework */
+  framework: ReactiveFramework;
+
+  /** verify the number of nodes executed matches the expected number */
+  testPullCounts?: boolean;
+}

package/test/util/perf-tests.ts

@@ -0,0 +1,42 @@
+import { FrameworkInfo, TestConfig } from "./framework-types";
+
+export interface TestResult {
+  sum: number;
+  count: number;
+}
+
+export interface TimingResult<T> {
+  result: T;
+  timing: TestTiming;
+}
+
+export interface TestTiming {
+  time: number;
+}
+
+export function verifyBenchResult(
+  perfFramework: FrameworkInfo,
+  config: TestConfig,
+  timedResult: TimingResult<TestResult>
+): void {
+  const { testPullCounts, framework } = perfFramework;
+  const { expected } = config;
+  const { result } = timedResult;
+
+  if (expected.sum) {
+    console.assert(
+      result.sum == expected.sum,
+      `sum ${framework.name} ${config.name} result:${result.sum} expected:${expected.sum}`
+    );
+  }
+  if (
+    expected.count &&
+    (config.readFraction === 1 || testPullCounts) &&
+    testPullCounts !== false
+  ) {
+    console.assert(
+      result.count === expected.count,
+      `count ${framework.name} ${config.name} result:${result.count} expected:${expected.count}`
+    );
+  }
+}

package/test/util/reactive-framework.ts

@@ -0,0 +1,22 @@
+/** interface for a reactive framework.
+ *
+ * Implement this interface to add a new reactive framework to the test and performance test suite.
+ */
+export interface ReactiveFramework {
+	name: string;
+	signal<T>(initialValue: T): Signal<T>;
+	computed<T>(fn: () => T): Computed<T>;
+	effect(fn: () => void): void;
+	withBatch<T>(fn: () => T): void;
+	withBuild<T>(fn: () => T): T;
+}
+  
+export interface Signal<T> {
+	read(): T;
+	write(v: T): void;
+}
+  
+export interface Computed<T> {
+	read(): T;
+}
+