@zeix/cause-effect 0.17.3 → 0.18.0

package/test/task.test.ts

@@ -0,0 +1,395 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	createEffect,
+	createMemo,
+	createState,
+	createTask,
+	isMemo,
+	isTask,
+	UnsetSignalValueError,
+} from '../index.ts'
+
+/* === Utility Functions === */
+
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+/* === Tests === */
+
+describe('Task', () => {
+	describe('createTask', () => {
+		test('should resolve async computation', async () => {
+			const task = createTask(
+				async () => {
+					await wait(50)
+					return 42
+				},
+				{ value: 0 },
+			)
+			expect(task.get()).toBe(0)
+			await wait(60)
+			expect(task.get()).toBe(42)
+		})
+
+		test('should have Symbol.toStringTag of "Task"', () => {
+			const task = createTask(async () => 1, { value: 0 })
+			expect(task[Symbol.toStringTag]).toBe('Task')
+		})
+
+		test('should throw UnsetSignalValueError before resolution with no initial value', () => {
+			const task = createTask(async () => {
+				await wait(50)
+				return 42
+			})
+			expect(() => task.get()).toThrow(UnsetSignalValueError)
+		})
+	})
+
+	describe('isTask', () => {
+		test('should identify task signals', () => {
+			expect(isTask(createTask(async () => 1, { value: 0 }))).toBe(true)
+		})
+
+		test('should return false for non-task values', () => {
+			expect(isTask(42)).toBe(false)
+			expect(isTask(null)).toBe(false)
+			expect(isTask({})).toBe(false)
+			expect(isMemo(createTask(async () => 1, { value: 0 }))).toBe(false)
+		})
+	})
+
+	describe('isPending', () => {
+		test('should return true while computation is in-flight', async () => {
+			const task = createTask(
+				async () => {
+					await wait(50)
+					return 42
+				},
+				{ value: 0 },
+			)
+			task.get() // trigger computation
+			expect(task.isPending()).toBe(true)
+			await wait(60)
+			task.get() // read resolved value
+			expect(task.isPending()).toBe(false)
+		})
+
+		test('should return false before first get()', () => {
+			const task = createTask(async () => 42, { value: 0 })
+			expect(task.isPending()).toBe(false)
+		})
+	})
+
+	describe('abort', () => {
+		test('should abort the current computation', async () => {
+			let completed = false
+			const task = createTask(
+				async (_prev, signal) => {
+					await wait(50)
+					if (!signal.aborted) completed = true
+					return 42
+				},
+				{ value: 0 },
+			)
+			task.get() // trigger computation
+			expect(task.isPending()).toBe(true)
+			task.abort()
+			expect(task.isPending()).toBe(false)
+			await wait(60)
+			expect(completed).toBe(false)
+		})
+	})
+
+	describe('Dependency Tracking', () => {
+		test('should re-execute when dependencies change', async () => {
+			const source = createState(1)
+			const task = createTask(
+				async () => {
+					const val = source.get() // dependency tracked before await
+					await wait(50)
+					return val * 2
+				},
+				{ value: 0 },
+			)
+
+			let result = 0
+			createEffect(() => {
+				result = task.get()
+			})
+			expect(result).toBe(0)
+			await wait(60)
+			expect(result).toBe(2)
+
+			source.set(5)
+			await wait(60)
+			expect(result).toBe(10)
+		})
+
+		test('should work with downstream memos', async () => {
+			const status = createState('pending')
+			const task = createTask(async () => {
+				await wait(50)
+				status.set('success')
+				return 42
+			})
+			const derived = createMemo(() => {
+				try {
+					return task.get() + 1
+				} catch {
+					return 0
+				}
+			})
+			expect(derived.get()).toBe(0)
+			expect(status.get()).toBe('pending')
+			await wait(60)
+			expect(derived.get()).toBe(43)
+			expect(status.get()).toBe('success')
+		})
+
+		test('should run tasks in parallel without waterfalls', async () => {
+			const a = createTask(
+				async () => {
+					await wait(80)
+					return 10
+				},
+				{ value: 0 },
+			)
+			const b = createTask(
+				async () => {
+					await wait(80)
+					return 20
+				},
+				{ value: 0 },
+			)
+			const sum = createMemo(() => a.get() + b.get(), { value: 0 })
+			expect(sum.get()).toBe(0)
+			await wait(90)
+			expect(sum.get()).toBe(30)
+		})
+	})
+
+	describe('AbortSignal', () => {
+		test('should signal abort when dependency changes during computation', async () => {
+			const source = createState(1)
+			let wasAborted = false
+			const task = createTask(
+				async (_prev, signal) => {
+					const val = source.get()
+					await wait(100)
+					if (signal.aborted) wasAborted = true
+					return val
+				},
+				{ value: 0 },
+			)
+
+			task.get() // start computation
+			await wait(10)
+			source.set(2) // change dependency mid-flight
+
+			await wait(110)
+			expect(wasAborted).toBe(true)
+		})
+
+		test('should coalesce multiple rapid changes into one recomputation', async () => {
+			const source = createState(1)
+			let computationCount = 0
+			const task = createTask(
+				async () => {
+					computationCount++
+					await wait(100)
+					return source.get()
+				},
+				{ value: 0 },
+			)
+
+			task.get()
+			expect(computationCount).toBe(1)
+
+			source.set(2)
+			source.set(3)
+			source.set(4)
+			await wait(210)
+
+			expect(task.get()).toBe(4)
+			expect(computationCount).toBe(1)
+		})
+	})
+
+	describe('Error Handling', () => {
+		test('should propagate async errors on get()', async () => {
+			const task = createTask(
+				async () => {
+					await wait(50)
+					throw new Error('async failure')
+				},
+				{ value: 0 },
+			)
+			task.get()
+			await wait(60)
+			expect(() => task.get()).toThrow('async failure')
+		})
+
+		test('should recover from errors when dependency changes', async () => {
+			const source = createState(1)
+			const task = createTask(
+				async () => {
+					const value = source.get()
+					await wait(50)
+					if (value === 2) throw new Error('bad value')
+					return value
+				},
+				{ value: 0 },
+			)
+
+			task.get()
+			await wait(60)
+			expect(task.get()).toBe(1)
+
+			source.set(2)
+			task.get()
+			await wait(60)
+			expect(() => task.get()).toThrow('bad value')
+
+			source.set(3)
+			task.get()
+			await wait(60)
+			expect(task.get()).toBe(3)
+		})
+	})
+
+	describe('options.value (prev)', () => {
+		test('should return initial value before resolution', () => {
+			const task = createTask(
+				async () => {
+					await wait(50)
+					return 42
+				},
+				{ value: 10 },
+			)
+			expect(task.get()).toBe(10)
+		})
+
+		test('should pass initial value as prev to first computation', async () => {
+			let receivedPrev: number | undefined
+			const task = createTask(
+				async prev => {
+					receivedPrev = prev
+					await wait(50)
+					return prev + 5
+				},
+				{ value: 10 },
+			)
+
+			expect(task.get()).toBe(10)
+			await wait(60)
+			expect(task.get()).toBe(15)
+			expect(receivedPrev).toBe(10)
+		})
+
+		test('should pass previous resolved value on recomputation', async () => {
+			const source = createState(1)
+			const receivedPrevs: number[] = []
+			const task = createTask(
+				async prev => {
+					const val = source.get() // dependency tracked before await
+					receivedPrevs.push(prev)
+					await wait(50)
+					return val + prev
+				},
+				{ value: 0 },
+			)
+
+			let result = 0
+			createEffect(() => {
+				result = task.get()
+			})
+			await wait(60)
+			expect(result).toBe(1) // 0 + 1
+
+			source.set(2)
+			await wait(60)
+			expect(result).toBe(3) // 1 + 2
+			expect(receivedPrevs).toEqual([0, 1])
+		})
+	})
+
+	describe('options.equals', () => {
+		test('should use custom equality to skip propagation after resolution', async () => {
+			const source = createState(1)
+			let effectCount = 0
+			const task = createTask(
+				async () => {
+					const val = source.get() // dependency tracked before await
+					await wait(50)
+					return { x: val % 2 }
+				},
+				{
+					value: { x: -1 },
+					equals: (a, b) => a.x === b.x,
+				},
+			)
+
+			createEffect(() => {
+				task.get()
+				effectCount++
+			})
+			await wait(60) // first resolution: { x: 1 }
+
+			source.set(3) // still odd — result will be { x: 1 }, structurally equal
+			await wait(60)
+			const countAfterEqual = effectCount
+
+			source.set(2) // now even — result will be { x: 0 }, different
+			await wait(60)
+
+			// After the structurally different result resolves, effect should run again
+			expect(effectCount).toBeGreaterThan(countAfterEqual)
+		})
+	})
+
+	describe('options.guard', () => {
+		test('should validate initial value against guard', () => {
+			expect(() => {
+				createTask(async () => 42, {
+					// @ts-expect-error - Testing invalid input
+					value: 'foo',
+					guard: (v): v is number => typeof v === 'number',
+				})
+			}).toThrow('[Task] Signal value "foo" is invalid')
+		})
+
+		test('should accept initial value that passes guard', () => {
+			const task = createTask(async () => 42, {
+				value: 10,
+				guard: (v): v is number => typeof v === 'number',
+			})
+			expect(task.get()).toBe(10)
+		})
+	})
+
+	describe('Input Validation', () => {
+		test('should throw InvalidCallbackError for sync callback', () => {
+			expect(() => {
+				// @ts-expect-error - Testing invalid input
+				createTask((_a: unknown) => 42)
+			}).toThrow('[Task] Callback (_a) => 42 is invalid')
+		})
+
+		test('should throw InvalidCallbackError for non-function callback', () => {
+			// @ts-expect-error - Testing invalid input
+			expect(() => createTask(null)).toThrow(
+				'[Task] Callback null is invalid',
+			)
+			// @ts-expect-error - Testing invalid input
+			expect(() => createTask(42)).toThrow(
+				'[Task] Callback 42 is invalid',
+			)
+		})
+
+		test('should throw NullishSignalValueError for null initial value', () => {
+			expect(() => {
+				// @ts-expect-error - Testing invalid input
+				createTask(async () => 42, { value: null })
+			}).toThrow('[Task] Signal value cannot be null or undefined')
+		})
+	})
+})

package/test/untrack.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	createEffect,
+	createMemo,
+	createScope,
+	createState,
+	untrack,
+} from '../index.ts'
+
+/* === Tests === */
+
+describe('untrack', () => {
+	test('should return the value of the callback', () => {
+		const result = untrack(() => 42)
+		expect(result).toBe(42)
+	})
+
+	test('should read a signal without tracking it', () => {
+		const tracked = createState('tracked')
+		const untracked = createState('untracked')
+		let count = 0
+		createEffect((): undefined => {
+			tracked.get()
+			untrack(() => untracked.get())
+			count++
+		})
+		expect(count).toBe(1)
+
+		// changing tracked signal should re-run the effect
+		tracked.set('changed')
+		expect(count).toBe(2)
+
+		// changing untracked signal should not re-run the effect
+		untracked.set('changed')
+		expect(count).toBe(2)
+	})
+
+	test('should not track dependencies in memos', () => {
+		const a = createState(1)
+		const b = createState(2)
+		const sum = createMemo(() => a.get() + untrack(() => b.get()))
+		expect(sum.get()).toBe(3)
+
+		// changing a should recompute
+		a.set(10)
+		expect(sum.get()).toBe(12)
+
+		// changing b should not recompute (stale value of b used)
+		b.set(20)
+		expect(sum.get()).toBe(12)
+	})
+
+	test('should prevent dependency pollution from subcomponent creation', () => {
+		const parentSignal = createState('parent')
+		let parentRuns = 0
+		let childRuns = 0
+
+		const dispose = createScope(() => {
+			createEffect((): undefined => {
+				parentSignal.get()
+				parentRuns++
+
+				// Simulate subcomponent: create local state + effect
+				// Without untrack, childSignal.get() in the child effect
+				// would link to the parent effect during initial run
+				untrack(() => {
+					const childSignal = createState('child')
+					createEffect((): undefined => {
+						childSignal.get()
+						childRuns++
+					})
+					childSignal.set('updated')
+				})
+			})
+		})
+
+		expect(parentRuns).toBe(1)
+		expect(childRuns).toBe(2) // initial + update
+
+		// parent should re-run when its own signal changes
+		parentSignal.set('changed')
+		expect(parentRuns).toBe(2)
+
+		dispose()
+	})
+
+	test('should prevent parent effect from re-running on child signal changes', () => {
+		const show = createState(true)
+		let parentRuns = 0
+		let childValue = ''
+
+		const dispose = createScope(() => {
+			createEffect((): undefined => {
+				parentRuns++
+				if (show.get()) {
+					// Subcomponent with its own reactive state
+					untrack(() => {
+						const label = createState('hello')
+						createEffect((): undefined => {
+							childValue = label.get()
+						})
+						label.set('world')
+					})
+				}
+			})
+		})
+
+		expect(parentRuns).toBe(1)
+		expect(childValue).toBe('world')
+
+		// toggling show re-runs parent (it's tracked)
+		show.set(false)
+		expect(parentRuns).toBe(2)
+
+		dispose()
+	})
+
+	test('should nest correctly', () => {
+		const a = createState(1)
+		const b = createState(2)
+		const c = createState(3)
+		let count = 0
+		createEffect((): undefined => {
+			a.get()
+			untrack(() => {
+				b.get()
+				untrack(() => {
+					c.get()
+				})
+			})
+			count++
+		})
+		expect(count).toBe(1)
+
+		a.set(10)
+		expect(count).toBe(2)
+
+		b.set(20)
+		expect(count).toBe(2)
+
+		c.set(30)
+		expect(count).toBe(2)
+	})
+
+	test('should restore tracking after untrack completes', () => {
+		const before = createState('before')
+		const during = createState('during')
+		const after = createState('after')
+		let count = 0
+		createEffect((): undefined => {
+			before.get()
+			untrack(() => during.get())
+			after.get()
+			count++
+		})
+		expect(count).toBe(1)
+
+		before.set('x')
+		expect(count).toBe(2)
+
+		during.set('x')
+		expect(count).toBe(2)
+
+		after.set('x')
+		expect(count).toBe(3)
+	})
+})

package/types/index.d.ts

@@ -1,19 +1,17 @@
 /**
  * @name Cause & Effect
- * @version 0.17.3
+ * @version 0.18.0
  * @author Esther Brunner
  */
-export { type Collection, type CollectionCallback, type CollectionSource, DerivedCollection, isCollection, TYPE_COLLECTION, } from './src/classes/collection';
-export { type Computed, createComputed, isComputed, isMemoCallback, isTaskCallback, Memo, type MemoCallback, Task, type TaskCallback, TYPE_COMPUTED, } from './src/classes/computed';
-export { type ArrayToRecord, isList, type KeyConfig, List, TYPE_LIST, } from './src/classes/list';
-export { isRef, Ref, TYPE_REF } from './src/classes/ref';
-export { isState, State, TYPE_STATE } from './src/classes/state';
-export { BaseStore, createStore, isStore, type Store, TYPE_STORE, } from './src/classes/store';
-export { type DiffResult, diff, isEqual, type UnknownArray, type UnknownRecord, } from './src/diff';
-export { createEffect, type EffectCallback, type MaybeCleanup, } from './src/effect';
-export { CircularDependencyError, createError, DuplicateKeyError, type Guard, guardMutableSignal, InvalidCallbackError, InvalidCollectionSourceError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, validateCallback, validateSignalValue, } from './src/errors';
-export { type MatchHandlers, match } from './src/match';
-export { type ResolveResult, resolve } from './src/resolve';
-export { createSignal, isMutableSignal, isSignal, type Signal, type SignalValues, type UnknownSignalRecord, } from './src/signal';
-export { batch, type Cleanup, createWatcher, flush, notifyOf, type SignalOptions, subscribeTo, track, UNSET, untrack, type Watcher, } from './src/system';
-export { isAbortError, isAsyncFunction, isFunction, isNumber, isObjectOfType, isRecord, isRecordOrArray, isString, isSymbol, valueString, } from './src/util';
+export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
+export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
+export { type Collection, type CollectionCallback, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
+export { createEffect, type MatchHandlers, type MaybePromise, match, } from './src/nodes/effect';
+export { createList, type DiffResult, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
+export { createMemo, isMemo, type Memo } from './src/nodes/memo';
+export { createSensor, isSensor, type Sensor, type SensorCallback, } from './src/nodes/sensor';
+export { createState, isState, type State, type UpdateCallback, } from './src/nodes/state';
+export { createStore, isStore, type Store, type StoreOptions, } from './src/nodes/store';
+export { createTask, isTask, type Task } from './src/nodes/task';
+export { createComputed, createMutableSignal, createSignal, isComputed, isMutableSignal, isSignal, type MutableSignal, } from './src/signal';
+export { isAsyncFunction, isFunction, isObjectOfType, isRecord, valueString, } from './src/util';

package/types/src/errors.d.ts

@@ -1,29 +1,85 @@
-import { type MutableSignal } from './signal';
-type Guard<T> = (value: unknown) => value is T;
+/**
+ * A type guard function that validates whether an unknown value is of type T.
+ * Used to ensure type safety when updating signals.
+ *
+ * @template T - The type to guard against
+ * @param value - The value to check
+ * @returns True if the value is of type T
+ */
+type Guard<T extends {}> = (value: unknown) => value is T;
+/**
+ * Error thrown on re-entrance on an already running function.
+ */
 declare class CircularDependencyError extends Error {
+    /**
+     * Constructs a new CircularDependencyError.
+     *
+     * @param where - The location where the error occurred.
+     */
     constructor(where: string);
 }
-declare class DuplicateKeyError extends Error {
-    constructor(where: string, key: string, value?: unknown);
+/**
+ * Error thrown when a signal value is null or undefined.
+ */
+declare class NullishSignalValueError extends TypeError {
+    /**
+     * Constructs a new NullishSignalValueError.
+     *
+     * @param where - The location where the error occurred.
+     */
+    constructor(where: string);
 }
-declare class InvalidCallbackError extends TypeError {
-    constructor(where: string, value: unknown);
+/**
+ * Error thrown when a signal is read before it has a value.
+ */
+declare class UnsetSignalValueError extends Error {
+    /**
+     * Constructs a new UnsetSignalValueError.
+     *
+     * @param where - The location where the error occurred.
+     */
+    constructor(where: string);
 }
-declare class InvalidCollectionSourceError extends TypeError {
+/**
+ * Error thrown when a signal value is invalid.
+ */
+declare class InvalidSignalValueError extends TypeError {
+    /**
+     * Constructs a new InvalidSignalValueError.
+     *
+     * @param where - The location where the error occurred.
+     * @param value - The invalid value.
+     */
     constructor(where: string, value: unknown);
 }
-declare class InvalidSignalValueError extends TypeError {
+/**
+ * Error thrown when a callback is invalid.
+ */
+declare class InvalidCallbackError extends TypeError {
+    /**
+     * Constructs a new InvalidCallbackError.
+     *
+     * @param where - The location where the error occurred.
+     * @param value - The invalid value.
+     */
     constructor(where: string, value: unknown);
 }
-declare class NullishSignalValueError extends TypeError {
+/**
+ * Error thrown when an API requiring an owner is called without one.
+ */
+declare class RequiredOwnerError extends Error {
+    /**
+     * Constructs a new RequiredOwnerError.
+     *
+     * @param where - The location where the error occurred.
+     */
     constructor(where: string);
 }
-declare class ReadonlySignalError extends Error {
-    constructor(what: string, value: unknown);
+declare class DuplicateKeyError extends Error {
+    constructor(where: string, key: string, value?: unknown);
 }
-declare function assert(condition: unknown, msg?: string): asserts condition;
-declare const createError: (reason: unknown) => Error;
-declare const validateCallback: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
-declare const validateSignalValue: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
-declare const guardMutableSignal: <T extends {}>(what: string, value: unknown, signal: unknown) => signal is MutableSignal<T>;
-export { type Guard, CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidCollectionSourceError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, assert, createError, validateCallback, validateSignalValue, guardMutableSignal, };
+declare function validateSignalValue<T extends {}>(where: string, value: unknown, guard?: Guard<T>): asserts value is T;
+declare function validateReadValue<T extends {}>(where: string, value: T | null | undefined): asserts value is T;
+declare function validateCallback(where: string, value: unknown): asserts value is (...args: unknown[]) => unknown;
+declare function validateCallback<T>(where: string, value: unknown, guard: (value: unknown) => value is T): asserts value is T;
+export { type Guard, CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, UnsetSignalValueError, InvalidCallbackError, RequiredOwnerError, DuplicateKeyError, validateSignalValue, validateReadValue, validateCallback, };