@zeix/cause-effect 0.17.2 → 0.18.0

package/src/nodes/task.ts

@@ -0,0 +1,146 @@
+import {
+	validateCallback,
+	validateReadValue,
+	validateSignalValue,
+} from '../errors'
+import {
+	activeSink,
+	type ComputedOptions,
+	defaultEquals,
+	FLAG_DIRTY,
+	link,
+	refresh,
+	type SinkNode,
+	type TaskCallback,
+	type TaskNode,
+	TYPE_TASK,
+} from '../graph'
+import { isAsyncFunction, isObjectOfType } from '../util'
+
+/* === Types === */
+
+/**
+ * An asynchronous reactive computation (colorless async).
+ * Automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics and pending state tracking.
+ *
+ * @template T - The type of value resolved by the task
+ */
+type Task<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Task'
+
+	/**
+	 * Gets the current value of the task.
+	 * Returns the last resolved value, even while a new computation is pending.
+	 * When called inside another reactive context, creates a dependency.
+	 * @returns The current value
+	 * @throws UnsetSignalValueError If the task value is still unset when read.
+	 */
+	get(): T
+
+	/**
+	 * Checks if the task is currently executing.
+	 * @returns True if a computation is in progress
+	 */
+	isPending(): boolean
+
+	/**
+	 * Aborts the current computation if one is running.
+	 * The task's AbortSignal will be triggered.
+	 */
+	abort(): void
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates an asynchronous reactive computation (colorless async).
+ * The computation automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics - in-flight computations are aborted when dependencies change.
+ *
+ * @since 0.18.0
+ * @template T - The type of value resolved by the task
+ * @param fn - The async computation function that receives the previous value and an AbortSignal
+ * @param options - Optional configuration for the task
+ * @returns A Task object with get(), isPending(), and abort() methods
+ *
+ * @example
+ * ```ts
+ * const userId = createState(1);
+ * const user = createTask(async (prev, signal) => {
+ *   const response = await fetch(`/api/users/${userId.get()}`, { signal });
+ *   return response.json();
+ * });
+ *
+ * // When userId changes, the previous fetch is aborted
+ * userId.set(2);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Check pending state
+ * if (user.isPending()) {
+ *   console.log('Loading...');
+ * }
+ * ```
+ */
+function createTask<T extends {}>(
+	fn: (prev: T, signal: AbortSignal) => Promise<T>,
+	options: ComputedOptions<T> & { value: T },
+): Task<T>
+function createTask<T extends {}>(
+	fn: TaskCallback<T>,
+	options?: ComputedOptions<T>,
+): Task<T>
+function createTask<T extends {}>(
+	fn: TaskCallback<T>,
+	options?: ComputedOptions<T>,
+): Task<T> {
+	validateCallback(TYPE_TASK, fn, isAsyncFunction)
+	if (options?.value !== undefined)
+		validateSignalValue(TYPE_TASK, options.value, options?.guard)
+
+	const node: TaskNode<T> = {
+		fn,
+		value: options?.value as T,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		flags: FLAG_DIRTY,
+		equals: options?.equals ?? defaultEquals,
+		controller: undefined,
+		error: undefined,
+	}
+
+	return {
+		[Symbol.toStringTag]: TYPE_TASK,
+		get(): T {
+			if (activeSink) link(node, activeSink)
+			refresh(node as unknown as SinkNode)
+			if (node.error) throw node.error
+			validateReadValue(TYPE_TASK, node.value)
+			return node.value
+		},
+		isPending(): boolean {
+			return !!node.controller
+		},
+		abort(): void {
+			node.controller?.abort()
+			node.controller = undefined
+		},
+	}
+}
+
+/**
+ * Checks if a value is a Task signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Task
+ */
+function isTask<T extends {} = unknown & {}>(value: unknown): value is Task<T> {
+	return isObjectOfType(value, TYPE_TASK)
+}
+
+export { createTask, isTask, type Task }

package/src/signal.ts

@@ -1,77 +1,79 @@
+import { InvalidSignalValueError } from './errors'
 import {
-	type Computed,
-	isComputed,
-	isMemoCallback,
-	isTaskCallback,
-	Memo,
-	Task,
-} from './classes/computed'
-import { isList, List } from './classes/list'
-import { isState, State } from './classes/state'
-import { createStore, isStore, type Store } from './classes/store'
-import type { UnknownRecord } from './diff'
-import { isRecord, isUniformArray } from './util'
+	type ComputedOptions,
+	type MemoCallback,
+	type Signal,
+	type TaskCallback,
+	TYPE_COLLECTION,
+	TYPE_LIST,
+	TYPE_MEMO,
+	TYPE_SENSOR,
+	TYPE_STATE,
+	TYPE_STORE,
+	TYPE_TASK,
+} from './graph'
+import { createList, isList, type List, type UnknownRecord } from './nodes/list'
+import { createMemo, isMemo, type Memo } from './nodes/memo'
+import { createState, isState, type State } from './nodes/state'
+import { createStore, isStore, type Store } from './nodes/store'
+import { createTask, isTask, type Task } from './nodes/task'
+import { isAsyncFunction, isFunction, isRecord, isUniformArray } from './util'
 
 /* === Types === */
 
-type Signal<T extends {}> = {
+type MutableSignal<T extends {}> = {
 	get(): T
+	set(value: T): void
+	update(callback: (value: T) => T): void
 }
 
-type MutableSignal<T extends {}> = T extends readonly (infer U extends {})[]
-	? List<U>
-	: T extends UnknownRecord
-		? Store<T>
-		: State<T>
-type ReadonlySignal<T extends {}> = Computed<T> // | Collection<T>
-
-type UnknownSignalRecord = Record<string, Signal<unknown & {}>>
-
-type SignalValues<S extends UnknownSignalRecord> = {
-	[K in keyof S]: S[K] extends Signal<infer T> ? T : never
-}
-
-/* === Functions === */
+/* === Factory Functions === */
 
 /**
- * Check whether a value is a Signal
+ * Create a derived signal from existing signals
  *
  * @since 0.9.0
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a Signal, false otherwise
+ * @param callback - Computation callback function
+ * @param options - Optional configuration
  */
-const isSignal = /*#__PURE__*/ <T extends {}>(
-	value: unknown,
-): value is Signal<T> => isState(value) || isComputed(value) || isStore(value)
-
-/**
- * Check whether a value is a State, Store, or List
- *
- * @since 0.15.2
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a State, Store, or List, false otherwise
- */
-const isMutableSignal = /*#__PURE__*/ (
-	value: unknown,
-): value is MutableSignal<unknown & {}> =>
-	isState(value) || isStore(value) || isList(value)
+function createComputed<T extends {}>(
+	callback: TaskCallback<T>,
+	options?: ComputedOptions<T>,
+): Task<T>
+function createComputed<T extends {}>(
+	callback: MemoCallback<T>,
+	options?: ComputedOptions<T>,
+): Memo<T>
+function createComputed<T extends {}>(
+	callback: TaskCallback<T> | MemoCallback<T>,
+	options?: ComputedOptions<T>,
+): Memo<T> | Task<T> {
+	return isAsyncFunction(callback)
+		? createTask(callback as TaskCallback<T>, options)
+		: createMemo(callback as MemoCallback<T>, options)
+}
 
 /**
  * Convert a value to a Signal.
  *
  * @since 0.9.6
  */
+function createSignal<T extends {}>(value: Signal<T>): Signal<T>
 function createSignal<T extends {}>(value: readonly T[]): List<T>
-function createSignal<T extends {}>(value: T[]): List<T>
 function createSignal<T extends UnknownRecord>(value: T): Store<T>
-function createSignal<T extends {}>(value: () => T): Computed<T>
+function createSignal<T extends {}>(value: TaskCallback<T>): Task<T>
+function createSignal<T extends {}>(value: MemoCallback<T>): Memo<T>
 function createSignal<T extends {}>(value: T): State<T>
 function createSignal(value: unknown): unknown {
-	if (isMemoCallback(value)) return new Memo(value)
-	if (isTaskCallback(value)) return new Task(value)
-	if (isUniformArray<unknown & {}>(value)) return new List(value)
-	if (isRecord(value)) return createStore(value as UnknownRecord)
-	return new State(value as unknown & {})
+	if (isSignal(value)) return value
+	if (value == null) throw new InvalidSignalValueError('createSignal', value)
+	if (isAsyncFunction(value))
+		return createTask(value as TaskCallback<unknown & {}>)
+	if (isFunction(value))
+		return createMemo(value as MemoCallback<unknown & {}>)
+	if (isUniformArray<unknown & {}>(value)) return createList(value)
+	if (isRecord(value)) return createStore(value)
+	return createState(value as unknown & {})
 }
 
 /**
@@ -79,26 +81,72 @@ function createSignal(value: unknown): unknown {
  *
  * @since 0.17.0
  */
+function createMutableSignal<T extends {}>(
+	value: MutableSignal<T>,
+): MutableSignal<T>
 function createMutableSignal<T extends {}>(value: readonly T[]): List<T>
-function createMutableSignal<T extends {}>(value: T[]): List<T>
 function createMutableSignal<T extends UnknownRecord>(value: T): Store<T>
 function createMutableSignal<T extends {}>(value: T): State<T>
 function createMutableSignal(value: unknown): unknown {
-	if (isUniformArray<unknown & {}>(value)) return new List(value)
-	if (isRecord(value)) return createStore(value as UnknownRecord)
-	return new State(value as unknown & {})
+	if (isMutableSignal(value)) return value
+	if (value == null || isFunction(value) || isSignal(value))
+		throw new InvalidSignalValueError('createMutableSignal', value)
+	if (isUniformArray<unknown & {}>(value)) return createList(value)
+	if (isRecord(value)) return createStore(value)
+	return createState(value as unknown & {})
+}
+
+/* === Guards === */
+
+/**
+ * Check if a value is a computed signal
+ *
+ * @since 0.9.0
+ * @param value - Value to check
+ * @returns True if value is a computed signal, false otherwise
+ */
+function isComputed<T extends {}>(value: unknown): value is Memo<T> {
+	return isMemo(value) || isTask(value)
 }
 
-/* === Exports === */
+/**
+ * Check whether a value is a Signal
+ *
+ * @since 0.9.0
+ * @param value - Value to check
+ * @returns True if value is a Signal, false otherwise
+ */
+function isSignal<T extends {}>(value: unknown): value is Signal<T> {
+	const signalsTypes = [
+		TYPE_STATE,
+		TYPE_MEMO,
+		TYPE_TASK,
+		TYPE_SENSOR,
+		TYPE_LIST,
+		TYPE_COLLECTION,
+		TYPE_STORE,
+	]
+	const typeStyle = Object.prototype.toString.call(value).slice(8, -1)
+	return signalsTypes.includes(typeStyle)
+}
+
+/**
+ * Check whether a value is a State, Store, or List
+ *
+ * @since 0.15.2
+ * @param value - Value to check
+ * @returns True if value is a State, Store, or List, false otherwise
+ */
+function isMutableSignal(value: unknown): value is MutableSignal<unknown & {}> {
+	return isState(value) || isStore(value) || isList(value)
+}
 
 export {
-	createMutableSignal,
+	type MutableSignal,
+	createComputed,
 	createSignal,
-	isMutableSignal,
+	createMutableSignal,
+	isComputed,
 	isSignal,
-	type MutableSignal,
-	type ReadonlySignal,
-	type Signal,
-	type SignalValues,
-	type UnknownSignalRecord,
+	isMutableSignal,
 }

package/src/util.ts

@@ -1,85 +1,54 @@
 /* === Utility Functions === */
 
-const isString = /*#__PURE__*/ (value: unknown): value is string =>
-	typeof value === 'string'
-
-const isNumber = /*#__PURE__*/ (value: unknown): value is number =>
-	typeof value === 'number'
-
-const isSymbol = /*#__PURE__*/ (value: unknown): value is symbol =>
-	typeof value === 'symbol'
-
-const isFunction = /*#__PURE__*/ <T>(
-	fn: unknown,
-): fn is (...args: unknown[]) => T => typeof fn === 'function'
+function isFunction<T>(fn: unknown): fn is (...args: unknown[]) => T {
+	return typeof fn === 'function'
+}
 
-const isAsyncFunction = /*#__PURE__*/ <T>(
+function isAsyncFunction<T>(
 	fn: unknown,
-): fn is (...args: unknown[]) => Promise<T> =>
-	isFunction(fn) && fn.constructor.name === 'AsyncFunction'
+): fn is (...args: unknown[]) => Promise<T> {
+	return isFunction(fn) && fn.constructor.name === 'AsyncFunction'
+}
 
-const isSyncFunction = /*#__PURE__*/ <T extends unknown & { then?: undefined }>(
+function isSyncFunction<T extends unknown & { then?: undefined }>(
 	fn: unknown,
-): fn is (...args: unknown[]) => T =>
-	isFunction(fn) && fn.constructor.name !== 'AsyncFunction'
-
-const isNonNullObject = /*#__PURE__*/ (
-	value: unknown,
-): value is NonNullable<object> => value != null && typeof value === 'object'
-
-const isObjectOfType = /*#__PURE__*/ <T>(
-	value: unknown,
-	type: string,
-): value is T => Object.prototype.toString.call(value) === `[object ${type}]`
+): fn is (...args: unknown[]) => T {
+	return isFunction(fn) && fn.constructor.name !== 'AsyncFunction'
+}
 
-const isRecord = /*#__PURE__*/ <T extends Record<string, unknown>>(
-	value: unknown,
-): value is T => isObjectOfType(value, 'Object')
+function isObjectOfType<T>(value: unknown, type: string): value is T {
+	return Object.prototype.toString.call(value) === `[object ${type}]`
+}
 
-const isRecordOrArray = /*#__PURE__*/ <
-	T extends Record<string | number, unknown> | ReadonlyArray<unknown>,
->(
+function isRecord<T extends Record<string, unknown>>(
 	value: unknown,
-): value is T => isRecord(value) || Array.isArray(value)
+): value is T {
+	return isObjectOfType(value, 'Object')
+}
 
-const isUniformArray = <T>(
+function isUniformArray<T>(
 	value: unknown,
-	guard = (item: T): item is T & {} => item != null,
-): value is T[] => Array.isArray(value) && value.every(guard)
-
-const hasMethod = /*#__PURE__*/ <
-	T extends object & Record<string, (...args: unknown[]) => unknown>,
->(
-	obj: T,
-	methodName: string,
-): obj is T & Record<string, (...args: unknown[]) => unknown> =>
-	methodName in obj && isFunction(obj[methodName])
-
-const isAbortError = /*#__PURE__*/ (error: unknown): boolean =>
-	error instanceof DOMException && error.name === 'AbortError'
+	guard: (item: T) => item is T & {} = (item): item is T & {} => item != null,
+): value is T[] {
+	return Array.isArray(value) && value.every(guard)
+}
 
-const valueString = /*#__PURE__*/ (value: unknown): string =>
-	isString(value)
+function valueString(value: unknown): string {
+	return typeof value === 'string'
 		? `"${value}"`
 		: !!value && typeof value === 'object'
 			? JSON.stringify(value)
 			: String(value)
+}
 
 /* === Exports === */
 
 export {
-	isString,
-	isNumber,
-	isSymbol,
 	isFunction,
 	isAsyncFunction,
 	isSyncFunction,
-	isNonNullObject,
 	isObjectOfType,
 	isRecord,
-	isRecordOrArray,
 	isUniformArray,
-	hasMethod,
-	isAbortError,
 	valueString,
 }

package/test/batch.test.ts

@@ -1,104 +1,131 @@
 import { describe, expect, test } from 'bun:test'
 import {
-	batchSignalWrites,
+	batch,
 	createEffect,
-	Memo,
-	match,
-	resolve,
-	State,
+	createList,
+	createMemo,
+	createState,
+	createStore,
 } from '../index.ts'
 
 /* === Tests === */
 
-describe('Batch', () => {
-	test('should be triggered only once after repeated state change', () => {
-		const cause = new State(0)
+describe('batch', () => {
+	test('should trigger effect only once after repeated state changes', () => {
+		const source = createState(0)
 		let result = 0
 		let count = 0
 		createEffect((): undefined => {
-			result = cause.get()
+			result = source.get()
 			count++
 		})
-		batchSignalWrites(() => {
-			for (let i = 1; i <= 10; i++) cause.set(i)
+		expect(count).toBe(1)
+		batch(() => {
+			for (let i = 1; i <= 10; i++) source.set(i)
 		})
 		expect(result).toBe(10)
-		expect(count).toBe(2) // + 1 for effect initialization
+		expect(count).toBe(2)
 	})
 
-	test('should be triggered only once when multiple signals are set', () => {
-		const a = new State(3)
-		const b = new State(4)
-		const c = new State(5)
-		const sum = new Memo(() => a.get() + b.get() + c.get())
+	test('should trigger effect only once when multiple states change', () => {
+		const a = createState(3)
+		const b = createState(4)
+		const c = createState(5)
+		const sum = createMemo(() => a.get() + b.get() + c.get())
 		let result = 0
 		let count = 0
-		createEffect(() => {
-			const resolved = resolve({ sum })
-			match(resolved, {
-				ok: ({ sum: res }) => {
-					result = res
-					count++
-				},
-				err: () => {},
-			})
+		createEffect((): undefined => {
+			result = sum.get()
+			count++
 		})
-		batchSignalWrites(() => {
+		expect(result).toBe(12)
+		expect(count).toBe(1)
+		batch(() => {
 			a.set(6)
 			b.set(8)
 			c.set(10)
 		})
 		expect(result).toBe(24)
-		expect(count).toBe(2) // + 1 for effect initialization
+		expect(count).toBe(2)
 	})
 
-	test('should prove example from README works', () => {
-		// State: define an array of Signal<number>
-		const signals = [new State(2), new State(3), new State(5)]
-
-		// Computed: derive a calculation ...
-		const sum = new Memo(() => {
-			const v = signals.reduce((total, v) => total + v.get(), 0)
-			if (!Number.isFinite(v)) throw new Error('Invalid value')
-			return v
+	test('should batch store property updates', () => {
+		const user = createStore({ name: 'Alice', age: 30 })
+		let result = ''
+		let count = 0
+		createEffect((): undefined => {
+			result = `${user.name.get()} (${user.age.get()})`
+			count++
+		})
+		expect(result).toBe('Alice (30)')
+		expect(count).toBe(1)
+		batch(() => {
+			user.name.set('Bob')
+			user.age.set(25)
 		})
+		expect(result).toBe('Bob (25)')
+		expect(count).toBe(2)
+	})
 
+	test('should batch list mutations', () => {
+		const list = createList([1, 2, 3])
 		let result = 0
-		let okCount = 0
-		let errCount = 0
-
-		// Effect: switch cases for the result
-		createEffect(() => {
-			const resolved = resolve({ sum })
-			match(resolved, {
-				ok: ({ sum: v }) => {
-					result = v
-					okCount++
-					// console.log('Sum:', v)
-				},
-				err: () => {
-					errCount++
-					// console.error('Error:', error)
-				},
-			})
+		let count = 0
+		createEffect((): undefined => {
+			result = list.get().reduce((sum, v) => sum + v, 0)
+			count++
 		})
-
-		expect(okCount).toBe(1)
-		expect(result).toBe(10)
-
-		// Batch: apply changes to all signals in a single transaction
-		batchSignalWrites(() => {
-			signals.forEach(signal => signal.update(v => v * 2))
+		expect(result).toBe(6)
+		expect(count).toBe(1)
+		batch(() => {
+			list.add(4)
+			list.add(5)
 		})
+		expect(result).toBe(15)
+		expect(count).toBe(2)
+	})
 
-		expect(okCount).toBe(2)
-		expect(result).toBe(20)
-
-		// Provoke an error
-		signals[0].set(NaN)
+	test('should batch mixed signal type updates', () => {
+		const count = createState(1)
+		const items = createList([10, 20])
+		const config = createStore({ multiplier: 2 })
+		let result = 0
+		let runs = 0
+		createEffect((): undefined => {
+			const sum = items.get().reduce((s, v) => s + v, 0)
+			result = (count.get() + sum) * config.multiplier.get()
+			runs++
+		})
+		expect(result).toBe(62) // (1 + 30) * 2
+		expect(runs).toBe(1)
+		batch(() => {
+			count.set(5)
+			items.add(30)
+			config.multiplier.set(3)
+		})
+		expect(result).toBe(195) // (5 + 60) * 3
+		expect(runs).toBe(2)
+	})
 
-		expect(errCount).toBe(1)
-		expect(okCount).toBe(2) // should not have changed due to error
-		expect(result).toBe(20) // should not have changed due to error
+	test('should support nested batches', () => {
+		const a = createState(1)
+		const b = createState(2)
+		let result = 0
+		let count = 0
+		createEffect((): undefined => {
+			result = a.get() + b.get()
+			count++
+		})
+		expect(count).toBe(1)
+		batch(() => {
+			a.set(10)
+			batch(() => {
+				b.set(20)
+			})
+			// inner batch should not flush yet
+			expect(count).toBe(1)
+		})
+		expect(result).toBe(30)
+		expect(count).toBe(2)
 	})
 })