@zeix/cause-effect 0.9.7

package/test/cause-effect.test.ts

@@ -0,0 +1,467 @@
+import { describe, test, expect } from 'bun:test'
+import { state, computed, isComputed, effect, batch } from '../index'
+
+/* === Utility Functions === */
+
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+const increment = (n: number | void) => (n ?? 0) + 1;
+const decrement = (n: number | void) => (n ?? 0) - 1;
+
+/* === Tests === */
+
+describe('State', function () {
+
+	describe('Empty cause', function () {
+
+		test('should be undefined', function () {
+			const cause = state(undefined);
+			expect(cause.get()).toBeUndefined();
+		});
+
+	});
+
+	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.set((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.set(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.set(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('Computed', function () {
+
+	test('should compute a function', function() {
+		const derived = computed(() => 1 + 2);
+		expect(derived.get()).toBe(3);
+	});
+
+	test('should compute function dependent on a signal', function() {
+		const derived = state(42).map(v => ++v);
+		expect(derived.get()).toBe(43);
+	});
+
+	test('should compute function dependent on an updated signal', function() {
+		const cause = state(42);
+		const derived = cause.map(v => ++v);
+		cause.set(24);
+		expect(derived.get()).toBe(25);
+	});
+
+	test('should compute function dependent on an async signal', async function() {
+		const status = state('pending');
+		const promised = computed<number>(async () => {
+			await wait(100);
+			status.set('success');
+			return 42;
+		});
+		const derived = promised.map(increment);
+		expect(derived.get()).toBe(1);
+		expect(status.get()).toBe('pending');
+		await wait(100);
+		expect(derived.get()).toBe(43);
+		expect(status.get()).toBe('success');
+	});
+
+	test('should handle errors from an async signal gracefully', async function() {
+		const status = state('pending');
+		const error = state('');
+		const promised = computed(async () => {
+			await wait(100);
+			status.set('error');
+			error.set('error occurred');
+			return 0
+		});
+		const derived = promised.map(increment);
+		expect(derived.get()).toBe(1);
+		expect(status.get()).toBe('pending');
+		await wait(100);
+		expect(error.get()).toBe('error occurred');
+		expect(status.get()).toBe('error');
+	});
+
+	test('should compute function dependent on a chain of computed states dependent on a signal', function() {
+		const derived = state(42)
+			.map(v => ++v)
+			.map(v => v * 2)
+			.map(v => ++v);
+		expect(derived.get()).toBe(87);
+	});
+
+	test('should compute function dependent on a chain of computed states dependent on an updated signal', function() {
+		const cause = state(42);
+		const derived = cause.map(v => ++v)
+			.map(v => v * 2)
+			.map(v => ++v);
+		cause.set(24);
+		expect(derived.get()).toBe(51);
+	});
+
+	test('should drop X->B->X updates', function () {
+		let count = 0;
+		const x = state(2);
+		const a = x.map(decrement);
+		const b = computed(() => x.get() + (a.get() ?? 0));
+		const c = computed(() => {
+			count++;
+			return 'c: ' + b.get();
+		});
+		expect(c.get()).toBe('c: 3');
+		expect(count).toBe(1);
+		x.set(4);
+		expect(c.get()).toBe('c: 7');
+		expect(count).toBe(2);
+	});
+
+	test('should only update every signal once (diamond graph)', function() {
+		let count = 0;
+		const x = state('a');
+		const a = x.map(v => v);
+		const b = x.map(v => v);
+		const c = computed(() => {
+			count++;
+			return a.get() + ' ' + b.get();
+		});
+		expect(c.get()).toBe('a a');
+		expect(count).toBe(1);
+		x.set('aa');
+		expect(c.get()).toBe('aa aa');
+		expect(count).toBe(2);
+	});
+
+	test('should only update every signal once (diamond graph + tail)', function() {
+		let count = 0;
+		const x = state('a');
+		const a = x.map(v => v);
+		const b = x.map(v => v);
+		const c = computed(() => a.get() + ' ' + b.get());
+		const d = computed(() => {
+			count++;
+			return c.get();
+		});
+		expect(d.get()).toBe('a a');
+		expect(count).toBe(1);
+		x.set('aa');
+		expect(d.get()).toBe('aa aa');
+		expect(count).toBe(2);
+	});
+
+	test('should bail out if result is the same', function() {
+		let count = 0;
+		const x = state('a');
+		const a = computed(() => {
+			x.get();
+			return 'foo';
+		});
+		const b = computed(() => {
+			count++;
+			return a.get();
+		}, true); // turn memoization on
+		expect(b.get()).toBe('foo');
+		expect(count).toBe(1);
+		x.set('aa');
+		expect(b.get()).toBe('foo');
+		expect(count).toBe(1);
+	});
+
+	test('should block if result remains unchanged', function() {
+		let count = 0;
+		const x = state(42);
+		const a = x.map(v => v % 2);
+		const b = computed(() => a.get() ? 'odd' : 'even', true);
+		const c = computed(() => {
+			count++;
+			return `c: ${b.get()}`;
+		}, true);
+		expect(c.get()).toBe('c: even');
+		expect(count).toBe(1);
+		x.set(44);
+		expect(c.get()).toBe('c: even');
+		expect(count).toBe(1);
+	});
+
+	test('should block if an error occurred', function() {
+		let count = 0;
+		const x = state(0);
+		const a = computed(() => {
+			if (x.get() === 1) throw new Error('Calculation error');
+			return 1;
+		}, true);
+		const b = a.map(v => v ? 'success' : 'pending');
+		const c = computed(() => {
+			count++;
+			return `c: ${b.get()}`;
+		}, true);
+		expect(a.get()).toBe(1);
+		expect(c.get()).toBe('c: success');
+		expect(count).toBe(1);
+		x.set(1);
+		try {
+			expect(a.get()).toBe(1);
+		} catch (error) {
+			expect(error.message).toBe('Calculation error');
+		} finally {
+			expect(c.get()).toBe('c: success');
+			expect(count).toBe(1);
+		}
+	});
+
+});
+
+describe('Effect', function () {
+
+	/* test('should be added to state.effects', function () {
+	  const cause = state();
+	  effect(() => state());
+	  expect(state.effects.size).toBe(1);
+	  effect(() => state());
+	  expect(state.effects.size).toBe(2);
+	});
+
+	test('should be added to computed.effects', function () {
+	  const cause = state();
+	  const derived = computed(() => 1 + state());
+	  effect(() => computed());
+	  expect(computed.effects.size).toBe(1);
+	  const derived2 = computed(() => 2 + state());
+	  effect(() => computed() + computed2());
+	  expect(computed.effects.size).toBe(2);
+	  expect(computed2.effects.size).toBe(1);
+	}); */
+
+	test('should be triggered after a state change', function() {
+		const cause = state('foo');
+		let effectDidRun = false;
+		effect(() => {
+			cause.get();
+			effectDidRun = true;
+		});
+		cause.set('bar');
+		expect(effectDidRun).toBe(true);
+	});
+
+	test('should be triggered repeatedly after repeated state change', async function() {
+		const cause = state(0);
+		let count = 0;
+		effect(() => {
+			cause.get();
+			count++;
+		});
+		for (let i = 0; i < 10; i++) {
+			cause.set(i);
+			expect(count).toBe(i + 1); // + 1 for the initial state change
+		}
+	});
+
+	test('should update multiple times after multiple state changes', function() {
+		const a = state(3);
+		const b = state(4);
+		let count = 0;
+		const sum = computed(() => {
+			count++;
+			return a.get() + b.get()
+		});
+		expect(sum.get()).toBe(7);
+		a.set(6);
+		expect(sum.get()).toBe(10);
+		b.set(8);
+		expect(sum.get()).toBe(14);
+		expect(count).toBe(3);
+	});
+
+});
+
+describe('Batch', function () {
+
+	test('should be triggered only once after repeated state change', function() {
+		const cause = state(0);
+		let result = 0;
+		let count = 0;
+		batch(() => {
+			for (let i = 1; i <= 10; i++) {
+				cause.set(i);
+			}
+		});
+		effect(() => {
+			result = cause.get();
+			count++;
+		});
+		expect(result).toBe(10);
+		expect(count).toBe(1);
+	});
+
+	test('should be triggered only once when multiple signals are set', function() {
+		const a = state(3);
+		const b = state(4);
+		const sum = computed(() => a.get() + b.get());
+		let result = 0;
+		let count = 0;
+		batch(() => {
+			a.set(6);
+            b.set(8);
+		});
+		effect(() => {
+            result = sum.get();
+			count++;
+        });
+		expect(sum.get()).toBe(14);
+		expect(count).toBe(1);
+	});
+
+});

package/test/util/dependency-graph.ts

@@ -0,0 +1,131 @@
+import { pseudoRandom } from './pseudo-random'
+/**
+ * Make a rectangular dependency graph, with an equal number of source elements
+ * and computation elements at every layer.
+ *
+ * @param width number of source elements and number of computed elements per layer
+ * @param totalLayers total number of source and computed layers
+ * @param staticFraction every nth computed node is static (1 = all static, 3 = 2/3rd are dynamic)
+ * @returns the graph
+ */
+export function makeGraph(framework, config) {
+  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,
+      counter,
+      staticFraction,
+      nSources,
+      framework
+    );
+    const graph = { sources, layers: rows };
+    return { graph, counter };
+  });
+}
+/**
+ * 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();
+  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++) {
+    framework.withBatch(() => {
+      const sourceDex = i % sources.length;
+      sources[sourceDex].write(i + sourceDex);
+    });
+    for (const leaf of readLeaves) {
+      leaf.read();
+    }
+  }
+  const sum = readLeaves.reduce((total, leaf) => leaf.read() + total, 0);
+  return sum;
+}
+function removeElems(src, rmCount, rand) {
+  const copy = src.slice();
+  for (let i = 0; i < rmCount; i++) {
+    const rmDex = Math.floor(rand() * copy.length);
+    copy.splice(rmDex, 1);
+  }
+  return copy;
+}
+export class Counter {
+	count = 0;
+}
+function makeDependentRows(
+  sources,
+  numRows,
+  counter,
+  staticFraction,
+  nSources,
+  framework
+): { read: number }[][] {
+  let prevRow = sources;
+  const random = pseudoRandom();
+  const rows: {read: number}[][] = [];
+  for (let l = 0; l < numRows; l++) {
+    const row = makeRow(
+      prevRow,
+      counter,
+      staticFraction,
+      nSources,
+      framework,
+      l,
+      random
+    );
+    rows.push(row);
+    prevRow = row;
+  }
+  return rows;
+}
+function makeRow(
+  sources,
+  counter,
+  staticFraction,
+  nSources,
+  framework,
+  layer,
+  random
+) {
+  return sources.map((_, myDex) => {
+    const mySources: { read(): number }[] = [];
+    for (let sourceDex = 0; sourceDex < nSources; sourceDex++) {
+      mySources.push(sources[(myDex + sourceDex) % sources.length]);
+    }
+    const staticNode = random() < staticFraction;
+    if (staticNode) {
+      // static node, always reference sources
+      return framework.computed(() => {
+        counter.count++;
+        let sum = 0;
+        for (const src of mySources) {
+          sum += src.read();
+        }
+        return sum;
+      });
+    } else {
+      // dynamic node, drops one of the sources depending on the value of the first element
+      const first = mySources[0];
+      const tail = mySources.slice(1);
+      const node = framework.computed(() => {
+        counter.count++;
+        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/pseudo-random.ts

@@ -0,0 +1,45 @@
+export function pseudoRandom(seed = "seed") {
+	const hash = xmur3a(seed);
+	const rng = sfc32(hash(), hash(), hash(), hash());
+	return rng;
+  }
+  /* these are adapted from https://github.com/bryc/code/blob/master/jshash/PRNGs.md
+   * (License: Public domain) */
+  /** random number generator originally in PractRand */
+  function sfc32(a, b, c, d) {
+	return function () {
+	  a >>>= 0;
+	  b >>>= 0;
+	  c >>>= 0;
+	  d >>>= 0;
+	  let t = (a + b) | 0;
+	  a = b ^ (b >>> 9);
+	  b = (c + (c << 3)) | 0;
+	  c = (c << 21) | (c >>> 11);
+	  d = (d + 1) | 0;
+	  t = (t + d) | 0;
+	  c = (c + t) | 0;
+	  return (t >>> 0) / 4294967296;
+	};
+  }
+  /** MurmurHash3 */
+  export function xmur3a(str) {
+	let h = 2166136261 >>> 0;
+	for (let k, i = 0; i < str.length; i++) {
+	  k = Math.imul(str.charCodeAt(i), 3432918353);
+	  k = (k << 15) | (k >>> 17);
+	  h ^= Math.imul(k, 461845907);
+	  h = (h << 13) | (h >>> 19);
+	  h = (Math.imul(h, 5) + 3864292196) | 0;
+	}
+	h ^= str.length;
+	return function () {
+	  h ^= h >>> 16;
+	  h = Math.imul(h, 2246822507);
+	  h ^= h >>> 13;
+	  h = Math.imul(h, 3266489909);
+	  h ^= h >>> 16;
+	  return h >>> 0;
+	};
+  }
+  

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+	"compilerOptions": {
+		// Enable latest features
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+	
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+	
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false,
+	
+		// Declarations
+		"declaration": true,
+		"declarationDir": "./",
+		"emitDeclarationOnly": true,
+	},
+	"include": ["./*.ts", "./lib/*.ts"],
+	"exclude": ["node_modules", "test"],
+  }
+