@zeix/cause-effect 0.17.3 → 0.18.0

package/test/memo.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	createMemo,
+	createState,
+	isMemo,
+	isState,
+	UnsetSignalValueError,
+} from '../index.ts'
+
+/* === Tests === */
+
+describe('Memo', () => {
+	describe('createMemo', () => {
+		test('should compute a derived value', () => {
+			const derived = createMemo(() => 1 + 2)
+			expect(derived.get()).toBe(3)
+		})
+
+		test('should have Symbol.toStringTag of "Memo"', () => {
+			const memo = createMemo(() => 0)
+			expect(memo[Symbol.toStringTag]).toBe('Memo')
+		})
+
+		test('should evaluate lazily on first get()', () => {
+			let computed = false
+			const memo = createMemo(() => {
+				computed = true
+				return 42
+			})
+			expect(computed).toBe(false)
+			memo.get()
+			expect(computed).toBe(true)
+		})
+
+		test('should throw UnsetSignalValueError if callback returns undefined', () => {
+			const memo = createMemo(() => undefined as unknown as number)
+			expect(() => memo.get()).toThrow(UnsetSignalValueError)
+		})
+	})
+
+	describe('isMemo', () => {
+		test('should identify memo signals', () => {
+			expect(isMemo(createMemo(() => 0))).toBe(true)
+		})
+
+		test('should return false for non-memo values', () => {
+			expect(isMemo(42)).toBe(false)
+			expect(isMemo(null)).toBe(false)
+			expect(isMemo({})).toBe(false)
+			expect(isState(createMemo(() => 0))).toBe(false)
+		})
+	})
+
+	describe('Dependency Tracking', () => {
+		test('should recompute when a dependency changes', () => {
+			const source = createState(42)
+			const derived = createMemo(() => source.get() + 1)
+			expect(derived.get()).toBe(43)
+			source.set(24)
+			expect(derived.get()).toBe(25)
+		})
+
+		test('should track through a chain of memos', () => {
+			const x = createState(42)
+			const a = createMemo(() => x.get() + 1)
+			const b = createMemo(() => a.get() * 2)
+			const c = createMemo(() => b.get() + 1)
+			expect(c.get()).toBe(87)
+			x.set(24)
+			expect(c.get()).toBe(51)
+		})
+
+		test('should recompute after multiple state changes', () => {
+			const a = createState(3)
+			const b = createState(4)
+			let count = 0
+			const sum = createMemo(() => {
+				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('Memoization', () => {
+		test('should skip downstream recomputation when result is unchanged', () => {
+			let count = 0
+			const x = createState('a')
+			const a = createMemo(() => {
+				x.get()
+				return 'foo'
+			})
+			const b = createMemo(() => {
+				count++
+				return a.get()
+			})
+			expect(b.get()).toBe('foo')
+			expect(count).toBe(1)
+			x.set('aa')
+			x.set('aaa')
+			expect(b.get()).toBe('foo')
+			expect(count).toBe(1)
+		})
+
+		test('should not propagate when intermediate result is unchanged', () => {
+			let count = 0
+			const x = createState(42)
+			const a = createMemo(() => x.get() % 2)
+			const b = createMemo(() => (a.get() ? 'odd' : 'even'))
+			const c = createMemo(() => {
+				count++
+				return `c: ${b.get()}`
+			})
+			expect(c.get()).toBe('c: even')
+			expect(count).toBe(1)
+			x.set(44)
+			x.set(46)
+			expect(c.get()).toBe('c: even')
+			expect(count).toBe(1)
+		})
+	})
+
+	describe('Diamond Graph', () => {
+		test('should compute each memo only once', () => {
+			let count = 0
+			const x = createState('a')
+			const a = createMemo(() => x.get())
+			const b = createMemo(() => x.get())
+			const c = createMemo(() => {
+				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 compute each memo only once with tail', () => {
+			let count = 0
+			const x = createState('a')
+			const a = createMemo(() => x.get())
+			const b = createMemo(() => x.get())
+			const c = createMemo(() => `${a.get()} ${b.get()}`)
+			const d = createMemo(() => {
+				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 drop X->B->X updates', () => {
+			let count = 0
+			const x = createState(2)
+			const a = createMemo(() => x.get() - 1)
+			const b = createMemo(() => x.get() + a.get())
+			const c = createMemo(() => {
+				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)
+		})
+	})
+
+	describe('Error Handling', () => {
+		test('should detect and throw for circular dependencies', () => {
+			const a = createState(1)
+			const b = createMemo(() => c.get() + 1)
+			const c = createMemo((): number => b.get() + a.get())
+			expect(() => b.get()).toThrow('[Memo] Circular dependency detected')
+		})
+
+		test('should propagate errors from computation', () => {
+			const x = createState(0)
+			const a = createMemo(() => {
+				if (x.get() === 1) throw new Error('Computation failed')
+				return 1
+			})
+			expect(a.get()).toBe(1)
+			x.set(1)
+			expect(() => a.get()).toThrow('Computation failed')
+		})
+
+		test('should allow downstream memos to recover from errors', () => {
+			const x = createState(0)
+			let errCount = 0
+			const a = createMemo(() => {
+				if (x.get() === 1) throw new Error('Computation failed')
+				return 1
+			})
+			const b = createMemo(() => {
+				try {
+					return `ok: ${a.get()}`
+				} catch (_e) {
+					errCount++
+					return 'recovered'
+				}
+			})
+
+			expect(b.get()).toBe('ok: 1')
+			x.set(1)
+			expect(b.get()).toBe('recovered')
+			expect(errCount).toBe(1)
+
+			x.set(0)
+			expect(b.get()).toBe('ok: 1')
+		})
+	})
+
+	describe('options.value (prev)', () => {
+		test('should pass initial value as prev to first computation', () => {
+			let receivedPrev: number | undefined
+			const memo = createMemo(
+				prev => {
+					receivedPrev = prev
+					return prev + 1
+				},
+				{ value: 10 },
+			)
+			expect(memo.get()).toBe(11)
+			expect(receivedPrev).toBe(10)
+		})
+
+		test('should pass undefined as prev when no initial value', () => {
+			let receivedPrev: unknown = 999
+			const memo = createMemo((prev: number | undefined) => {
+				receivedPrev = prev
+				return 42
+			})
+			memo.get()
+			expect(receivedPrev).toBeUndefined()
+		})
+
+		test('should pass previous computed value on recomputation', () => {
+			const source = createState(5)
+			let receivedPrev: number | undefined
+			const memo = createMemo(
+				prev => {
+					receivedPrev = prev
+					return source.get() * 2
+				},
+				{ value: 0 },
+			)
+
+			expect(memo.get()).toBe(10)
+			expect(receivedPrev).toBe(0)
+
+			source.set(3)
+			expect(memo.get()).toBe(6)
+			expect(receivedPrev).toBe(10)
+		})
+
+		test('should work as a reducer', () => {
+			const increment = createState(0)
+			const sum = createMemo(
+				prev => {
+					const inc = increment.get()
+					return inc === 0 ? prev : prev + inc
+				},
+				{ value: 0 },
+			)
+
+			expect(sum.get()).toBe(0)
+			increment.set(5)
+			expect(sum.get()).toBe(5)
+			increment.set(3)
+			expect(sum.get()).toBe(8)
+		})
+
+		test('should preserve prev value across errors', () => {
+			const shouldError = createState(false)
+			const counter = createState(1)
+			const memo = createMemo(
+				prev => {
+					if (shouldError.get()) throw new Error('fail')
+					return prev + counter.get()
+				},
+				{ value: 10 },
+			)
+
+			expect(memo.get()).toBe(11) // 10 + 1
+			counter.set(5)
+			expect(memo.get()).toBe(16) // 11 + 5
+
+			shouldError.set(true)
+			expect(() => memo.get()).toThrow('fail')
+
+			shouldError.set(false)
+			counter.set(2)
+			expect(memo.get()).toBe(18) // 16 + 2
+		})
+	})
+
+	describe('options.equals', () => {
+		test('should use custom equality to skip propagation', () => {
+			const source = createState(1)
+			let downstream = 0
+			const memo = createMemo(() => ({ x: source.get() % 2 }), {
+				value: { x: -1 },
+				equals: (a, b) => a.x === b.x,
+			})
+			const tail = createMemo(() => {
+				downstream++
+				return memo.get()
+			})
+
+			tail.get()
+			expect(downstream).toBe(1)
+
+			source.set(3) // still odd, structurally equal
+			tail.get()
+			expect(downstream).toBe(1)
+
+			source.set(2) // now even, different
+			tail.get()
+			expect(downstream).toBe(2)
+		})
+	})
+
+	describe('options.guard', () => {
+		test('should validate initial value against guard', () => {
+			expect(() => {
+				createMemo(() => 42, {
+					value: -1,
+					guard: (v): v is number => typeof v === 'number' && v >= 0,
+				})
+			}).toThrow('[Memo] Signal value -1 is invalid')
+		})
+
+		test('should accept initial value that passes guard', () => {
+			const memo = createMemo(prev => prev + 1, {
+				value: 0,
+				guard: (v): v is number => typeof v === 'number' && v >= 0,
+			})
+			expect(memo.get()).toBe(1)
+		})
+	})
+
+	describe('Input Validation', () => {
+		test('should throw InvalidCallbackError for non-function callback', () => {
+			// @ts-expect-error - Testing invalid input
+			expect(() => createMemo(null)).toThrow(
+				'[Memo] Callback null is invalid',
+			)
+			// @ts-expect-error - Testing invalid input
+			expect(() => createMemo(42)).toThrow(
+				'[Memo] Callback 42 is invalid',
+			)
+			// @ts-expect-error - Testing invalid input
+			expect(() => createMemo('str')).toThrow(
+				'[Memo] Callback "str" is invalid',
+			)
+		})
+
+		test('should throw InvalidCallbackError for async callback', () => {
+			expect(() => createMemo(async () => 42)).toThrow()
+		})
+
+		test('should throw NullishSignalValueError for null initial value', () => {
+			expect(() => {
+				// @ts-expect-error - Testing invalid input
+				createMemo(() => 42, { value: null })
+			}).toThrow('[Memo] Signal value cannot be null or undefined')
+		})
+	})
+})

package/test/regression.test.ts

@@ -0,0 +1,156 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { gzipSync } from 'node:zlib'
+import { batch, createEffect, createMemo, createState } from '../index.ts'
+
+/* === Baseline Management === */
+
+type Baseline = {
+	bundleMinified: number
+	bundleGzipped: number
+	deepPropagation: number
+	broadPropagation: number
+	diamondPropagation: number
+	signalCreation: number
+}
+
+const BASELINE_PATH = `${import.meta.dir}/regression-baseline.json`
+const BUNDLE_MARGIN = 0.1 // 10%
+const PERF_MARGIN = 0.2 // 20%
+const PERF_FLOOR = 2 // minimum absolute tolerance in ms
+
+const baseline: Baseline | null = existsSync(BASELINE_PATH)
+	? JSON.parse(readFileSync(BASELINE_PATH, 'utf-8'))
+	: null
+
+const current = {} as Baseline
+
+function check(
+	key: keyof Baseline,
+	value: number,
+	margin: number,
+	unit: string,
+): void {
+	current[key] = value
+	if (baseline) {
+		const relative = baseline[key] * (1 + margin)
+		const limit =
+			unit === 'ms'
+				? Math.max(relative, baseline[key] + PERF_FLOOR)
+				: relative
+		console.log(
+			`  ${key}: ${value.toFixed(unit === 'ms' ? 1 : 0)}${unit}` +
+				` (baseline: ${baseline[key].toFixed(unit === 'ms' ? 1 : 0)}${unit},` +
+				` limit: ${limit.toFixed(unit === 'ms' ? 1 : 0)}${unit})`,
+		)
+		expect(value).toBeLessThanOrEqual(limit)
+	} else {
+		console.log(
+			`  ${key}: ${value.toFixed(unit === 'ms' ? 1 : 0)}${unit} (no baseline, recording)`,
+		)
+	}
+}
+
+afterAll(() => {
+	if (!baseline) {
+		writeFileSync(BASELINE_PATH, `${JSON.stringify(current, null, '\t')}\n`)
+		console.log(`\n  Baseline written to ${BASELINE_PATH}`)
+	}
+})
+
+/* === Bundle Size Regression Tests === */
+
+describe('Bundle size', () => {
+	test('minified bundle should not regress', async () => {
+		const result = await Bun.build({
+			entrypoints: ['./index.ts'],
+			minify: true,
+		})
+		const bytes = await result.outputs[0].arrayBuffer()
+		check('bundleMinified', bytes.byteLength, BUNDLE_MARGIN, 'B')
+	})
+
+	test('gzipped bundle should not regress', async () => {
+		const result = await Bun.build({
+			entrypoints: ['./index.ts'],
+			minify: true,
+		})
+		const bytes = await result.outputs[0].arrayBuffer()
+		const gzipped = gzipSync(new Uint8Array(bytes)).byteLength
+		check('bundleGzipped', gzipped, BUNDLE_MARGIN, 'B')
+	})
+})
+
+/* === Performance Regression Tests === */
+
+function measure(setup: () => () => void, iterations: number): number {
+	const fn = setup()
+	for (let i = 0; i < 100; i++) fn() // warmup
+	const start = performance.now()
+	for (let i = 0; i < iterations; i++) fn()
+	return performance.now() - start
+}
+
+describe('Performance', () => {
+	test('deep propagation (50 layers, 1000 iterations)', () => {
+		const elapsed = measure(() => {
+			const head = createState(0)
+			let current: { get(): number } = head
+			for (let i = 0; i < 50; i++) {
+				const c = current
+				current = createMemo(() => c.get() + 1)
+			}
+			createEffect(() => {
+				current.get()
+			})
+			let i = 0
+			return () => batch(() => head.set(++i))
+		}, 1000)
+		check('deepPropagation', elapsed, PERF_MARGIN, 'ms')
+	})
+
+	test('broad propagation (50 effects, 1000 iterations)', () => {
+		const elapsed = measure(() => {
+			const head = createState(0)
+			for (let i = 0; i < 50; i++) {
+				const c = createMemo(() => head.get() + i)
+				const c2 = createMemo(() => c.get() + 1)
+				createEffect(() => {
+					c2.get()
+				})
+			}
+			let i = 0
+			return () => batch(() => head.set(++i))
+		}, 1000)
+		check('broadPropagation', elapsed, PERF_MARGIN, 'ms')
+	})
+
+	test('diamond propagation (width 5, 5000 iterations)', () => {
+		const elapsed = measure(() => {
+			const head = createState(0)
+			const branches: { get(): number }[] = []
+			for (let i = 0; i < 5; i++)
+				branches.push(createMemo(() => head.get() + 1))
+			const sum = createMemo(() =>
+				branches.reduce((a, b) => a + b.get(), 0),
+			)
+			createEffect(() => {
+				sum.get()
+			})
+			let i = 0
+			return () => batch(() => head.set(++i))
+		}, 5000)
+		check('diamondPropagation', elapsed, PERF_MARGIN, 'ms')
+	})
+
+	test('create 1k signals (500 rounds)', () => {
+		const fn = () => {
+			for (let i = 0; i < 1000; i++) createState(i)
+		}
+		for (let i = 0; i < 50; i++) fn() // warmup
+		const start = performance.now()
+		for (let i = 0; i < 500; i++) fn()
+		const elapsed = performance.now() - start
+		check('signalCreation', elapsed, PERF_MARGIN, 'ms')
+	})
+})

package/test/scope.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from 'bun:test'
+import { createEffect, createScope, createState } from '../index.ts'
+
+/* === Tests === */
+
+describe('createScope', () => {
+	test('should return a dispose function', () => {
+		const dispose = createScope(() => {})
+		expect(typeof dispose).toBe('function')
+	})
+
+	test('should run the callback immediately', () => {
+		let ran = false
+		createScope(() => {
+			ran = true
+		})
+		expect(ran).toBe(true)
+	})
+
+	test('should call returned cleanup on dispose', () => {
+		let cleaned = false
+		const dispose = createScope(() => {
+			return () => {
+				cleaned = true
+			}
+		})
+		expect(cleaned).toBe(false)
+		dispose()
+		expect(cleaned).toBe(true)
+	})
+
+	test('should dispose child effects', () => {
+		const source = createState(0)
+		let count = 0
+		const dispose = createScope(() => {
+			createEffect((): undefined => {
+				source.get()
+				count++
+			})
+		})
+		expect(count).toBe(1)
+		source.set(1)
+		expect(count).toBe(2)
+		dispose()
+		source.set(2)
+		expect(count).toBe(2) // effect should no longer run
+	})
+
+	test('should dispose multiple child effects', () => {
+		const a = createState(0)
+		const b = createState(0)
+		let countA = 0
+		let countB = 0
+		const dispose = createScope(() => {
+			createEffect((): undefined => {
+				a.get()
+				countA++
+			})
+			createEffect((): undefined => {
+				b.get()
+				countB++
+			})
+		})
+		expect(countA).toBe(1)
+		expect(countB).toBe(1)
+		dispose()
+		a.set(1)
+		b.set(1)
+		expect(countA).toBe(1)
+		expect(countB).toBe(1)
+	})
+
+	test('should call returned cleanup and dispose child effects', () => {
+		const source = createState(0)
+		let effectCount = 0
+		let cleaned = false
+		const dispose = createScope(() => {
+			createEffect((): undefined => {
+				source.get()
+				effectCount++
+			})
+			return () => {
+				cleaned = true
+			}
+		})
+		expect(effectCount).toBe(1)
+		expect(cleaned).toBe(false)
+		dispose()
+		expect(cleaned).toBe(true)
+		source.set(1)
+		expect(effectCount).toBe(1)
+	})
+
+	test('should handle nested scopes independently', () => {
+		const source = createState(0)
+		let outerCount = 0
+		let innerCount = 0
+		let innerDispose!: () => void
+		const outerDispose = createScope(() => {
+			createEffect((): undefined => {
+				source.get()
+				outerCount++
+			})
+			innerDispose = createScope(() => {
+				createEffect((): undefined => {
+					source.get()
+					innerCount++
+				})
+			})
+		})
+		expect(outerCount).toBe(1)
+		expect(innerCount).toBe(1)
+		source.set(1)
+		expect(outerCount).toBe(2)
+		expect(innerCount).toBe(2)
+
+		// disposing inner scope should not affect outer
+		innerDispose()
+		source.set(2)
+		expect(outerCount).toBe(3)
+		expect(innerCount).toBe(2)
+
+		// disposing outer scope should have no further effect
+		outerDispose()
+		source.set(3)
+		expect(outerCount).toBe(3)
+		expect(innerCount).toBe(2)
+	})
+
+	test('should dispose nested scopes when parent is disposed', () => {
+		const source = createState(0)
+		let innerCount = 0
+		const outerDispose = createScope(() => {
+			createScope(() => {
+				createEffect((): undefined => {
+					source.get()
+					innerCount++
+				})
+			})
+		})
+		expect(innerCount).toBe(1)
+		source.set(1)
+		expect(innerCount).toBe(2)
+
+		// disposing outer should also dispose inner
+		outerDispose()
+		source.set(2)
+		expect(innerCount).toBe(2)
+	})
+
+	test('should call nested cleanup functions on parent dispose', () => {
+		let outerCleaned = false
+		let innerCleaned = false
+		const dispose = createScope(() => {
+			createScope(() => {
+				return () => {
+					innerCleaned = true
+				}
+			})
+			return () => {
+				outerCleaned = true
+			}
+		})
+		expect(outerCleaned).toBe(false)
+		expect(innerCleaned).toBe(false)
+		dispose()
+		expect(outerCleaned).toBe(true)
+		expect(innerCleaned).toBe(true)
+	})
+
+	test('should be safe to call dispose multiple times', () => {
+		let cleanCount = 0
+		const dispose = createScope(() => {
+			return () => {
+				cleanCount++
+			}
+		})
+		dispose()
+		expect(cleanCount).toBe(1)
+		dispose()
+		// cleanup should only run once since it's nulled after first run
+		expect(cleanCount).toBe(1)
+	})
+
+	test('should handle scope with no cleanup return', () => {
+		const dispose = createScope(() => {
+			// no return
+		})
+		expect(() => dispose()).not.toThrow()
+	})
+})