@zeix/cause-effect 0.14.1 → 0.15.0

package/index.ts

@@ -1,36 +1,56 @@
 /**
  * @name Cause & Effect
- * @version 0.14.1
+ * @version 0.15.0
  * @author Esther Brunner
  */
-export { isFunction, CircularDependencyError } from './src/util'
-export {
-	type Signal,
-	type MaybeSignal,
-	type SignalValues,
-	UNSET,
-	isSignal,
-	isComputedCallback,
-	toSignal,
-} from './src/signal'
-export { type State, TYPE_STATE, state, isState } from './src/state'
+
 export {
 	type Computed,
 	type ComputedCallback,
-	TYPE_COMPUTED,
 	computed,
 	isComputed,
+	isComputedCallback,
+	TYPE_COMPUTED,
 } from './src/computed'
-export { type EffectMatcher, effect } from './src/effect'
+export { type DiffResult, diff, isEqual, type UnknownRecord } from './src/diff'
+export { type EffectCallback, effect, type MaybeCleanup } from './src/effect'
+export { type MatchHandlers, match } from './src/match'
+export { type ResolveResult, resolve } from './src/resolve'
 export {
-	type Watcher,
+	batch,
 	type Cleanup,
-	type Updater,
-	watch,
-	subscribe,
-	notify,
+	enqueue,
 	flush,
-	batch,
+	notify,
 	observe,
-	enqueue,
+	subscribe,
+	type Updater,
+	type Watcher,
+	watch,
 } from './src/scheduler'
+export {
+	isSignal,
+	type MaybeSignal,
+	type Signal,
+	type SignalValues,
+	toSignal,
+	UNSET,
+} from './src/signal'
+export { isState, type State, state, TYPE_STATE } from './src/state'
+export {
+	isStore,
+	type Store,
+	type StoreAddEvent,
+	type StoreChangeEvent,
+	type StoreEventMap,
+	type StoreRemoveEvent,
+	store,
+	TYPE_STORE,
+} from './src/store'
+export {
+	CircularDependencyError,
+	isAbortError,
+	isAsyncFunction,
+	isFunction,
+	toError,
+} from './src/util'

package/package.json

@@ -1,14 +1,13 @@
 {
 	"name": "@zeix/cause-effect",
-	"version": "0.14.1",
+	"version": "0.15.0",
 	"author": "Esther Brunner",
 	"main": "index.js",
 	"module": "index.ts",
 	"devDependencies": {
+		"@biomejs/biome": "2.1.4",
 		"@types/bun": "latest",
-		"eslint": "^9.27.0",
-		"random": "^5.4.0",
-		"typescript-eslint": "^8.32.1"
+		"random": "^5.4.1"
 	},
 	"peerDependencies": {
 		"typescript": "^5.6.3"
@@ -25,10 +24,10 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "bun build index.ts --outdir ./ --minify && bunx tsc",
+		"build": "bunx tsc && bun build index.ts --outdir ./ --minify && bun build index.ts --outfile index.dev.js",
 		"test": "bun test",
-		"lint": "bunx eslint src/"
+		"lint": "bunx biome lint --write"
 	},
 	"type": "module",
-	"types": "index.d.ts"
+	"types": "types/index.d.ts"
 }

package/src/computed.ts

@@ -1,18 +1,21 @@
+import { isEqual } from './diff'
+import {
+	flush,
+	notify,
+	observe,
+	subscribe,
+	type Watcher,
+	watch,
+} from './scheduler'
+import { UNSET } from './signal'
 import {
 	CircularDependencyError,
+	isAbortError,
+	isAsyncFunction,
 	isFunction,
 	isObjectOfType,
 	toError,
 } from './util'
-import {
-	type Watcher,
-	watch,
-	subscribe,
-	notify,
-	flush,
-	observe,
-} from './scheduler'
-import { UNSET } from './signal'
 
 /* === Types === */
 
@@ -20,7 +23,7 @@ type Computed<T extends {}> = {
 	[Symbol.toStringTag]: 'Computed'
 	get(): T
 }
-type ComputedCallback<T extends {} & { then?: void }> =
+type ComputedCallback<T extends {} & { then?: undefined }> =
 	| ((abort: AbortSignal) => Promise<T>)
 	| (() => T)
 
@@ -49,20 +52,20 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 	let computing = false
 
 	// Functions to update internal state
-	const ok = (v: T) => {
-		if (!Object.is(v, value)) {
+	const ok = (v: T): undefined => {
+		if (!isEqual(v, value)) {
 			value = v
 			changed = true
 		}
 		error = undefined
 		dirty = false
 	}
-	const nil = () => {
+	const nil = (): undefined => {
 		changed = UNSET !== value
 		value = UNSET
 		error = undefined
 	}
-	const err = (e: unknown) => {
+	const err = (e: unknown): undefined => {
 		const newError = toError(e)
 		changed =
 			!error ||
@@ -83,25 +86,31 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 	// Own watcher: called when notified from sources (push)
 	const mark = watch(() => {
 		dirty = true
-		controller?.abort('Aborted because source signal changed')
+		controller?.abort()
 		if (watchers.size) notify(watchers)
 		else mark.cleanup()
 	})
+	mark.off(() => {
+		controller?.abort()
+	})
 
 	// Called when requested by dependencies (pull)
 	const compute = () =>
 		observe(() => {
 			if (computing) throw new CircularDependencyError('computed')
 			changed = false
-			if (isFunction(fn) && fn.constructor.name === 'AsyncFunction') {
-				if (controller) return value // return current value until promise resolves
+			if (isAsyncFunction(fn)) {
+				// Return current value until promise resolves
+				if (controller) return value
 				controller = new AbortController()
 				controller.signal.addEventListener(
 					'abort',
 					() => {
 						computing = false
 						controller = undefined
-						compute() // retry
+
+						// Retry computation with updated state
+						compute()
 					},
 					{
 						once: true,
@@ -113,7 +122,7 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 			try {
 				result = controller ? fn(controller.signal) : (fn as () => T)()
 			} catch (e) {
-				if (e instanceof DOMException && e.name === 'AbortError') nil()
+				if (isAbortError(e)) nil()
 				else err(e)
 				computing = false
 				return
@@ -169,10 +178,10 @@ const isComputedCallback = /*#__PURE__*/ <T extends {}>(
 /* === Exports === */
 
 export {
-	type Computed,
-	type ComputedCallback,
 	TYPE_COMPUTED,
 	computed,
 	isComputed,
 	isComputedCallback,
+	type Computed,
+	type ComputedCallback,
 }

package/src/diff.ts

@@ -0,0 +1,136 @@
+import { UNSET } from './signal'
+import { CircularDependencyError, isRecord } from './util'
+
+/* === Types === */
+
+type UnknownRecord = Record<string, unknown & {}>
+
+type DiffResult<T extends UnknownRecord = UnknownRecord> = {
+	changed: boolean
+	add: Partial<T>
+	change: Partial<T>
+	remove: Partial<T>
+}
+
+/* === Functions === */
+
+/**
+ * Checks if two values are equal with cycle detection
+ *
+ * @since 0.15.0
+ * @param {T} a - First value to compare
+ * @param {T} b - Second value to compare
+ * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
+ * @returns {boolean} Whether the two values are equal
+ */
+const isEqual = <T>(a: T, b: T, visited?: WeakSet<object>): boolean => {
+	// Fast paths
+	if (Object.is(a, b)) return true
+	if (typeof a !== typeof b) return false
+	if (typeof a !== 'object' || a === null || b === null) return false
+
+	// Cycle detection
+	if (!visited) visited = new WeakSet()
+	if (visited.has(a as object) || visited.has(b as object))
+		throw new CircularDependencyError('isEqual')
+	visited.add(a as object)
+	visited.add(b as object)
+
+	try {
+		if (Array.isArray(a) && Array.isArray(b)) {
+			if (a.length !== b.length) return false
+			for (let i = 0; i < a.length; i++) {
+				if (!isEqual(a[i], b[i], visited)) return false
+			}
+			return true
+		}
+
+		if (Array.isArray(a) !== Array.isArray(b)) return false
+
+		if (isRecord(a) && isRecord(b)) {
+			const aKeys = Object.keys(a)
+			const bKeys = Object.keys(b)
+
+			if (aKeys.length !== bKeys.length) return false
+			for (const key of aKeys) {
+				if (!(key in b)) return false
+				if (
+					!isEqual(
+						(a as Record<string, unknown>)[key],
+						(b as Record<string, unknown>)[key],
+						visited,
+					)
+				)
+					return false
+			}
+			return true
+		}
+
+		return false
+	} finally {
+		visited.delete(a as object)
+		visited.delete(b as object)
+	}
+}
+
+/**
+ * Compares two records and returns a result object containing the differences.
+ *
+ * @since 0.15.0
+ * @param {T} oldObj - The old record to compare
+ * @param {T} newObj - The new record to compare
+ * @returns {DiffResult<T>} The result of the comparison
+ */
+const diff = <T extends UnknownRecord>(oldObj: T, newObj: T): DiffResult<T> => {
+	const visited = new WeakSet<object>()
+
+	const diffRecords = (
+		oldRecord: Record<string, unknown>,
+		newRecord: Record<string, unknown>,
+	): DiffResult<T> => {
+		const add: Partial<T> = {}
+		const change: Partial<T> = {}
+		const remove: Partial<T> = {}
+
+		const oldKeys = Object.keys(oldRecord)
+		const newKeys = Object.keys(newRecord)
+		const allKeys = new Set([...oldKeys, ...newKeys])
+
+		for (const key of allKeys) {
+			const oldHas = key in oldRecord
+			const newHas = key in newRecord
+
+			if (!oldHas && newHas) {
+				add[key as keyof T] = newRecord[key] as T[keyof T]
+				continue
+			} else if (oldHas && !newHas) {
+				remove[key as keyof T] = UNSET
+				continue
+			}
+
+			const oldValue = oldRecord[key] as T[keyof T]
+			const newValue = newRecord[key] as T[keyof T]
+
+			if (!isEqual(oldValue, newValue, visited))
+				change[key as keyof T] = newValue
+		}
+
+		const changed =
+			Object.keys(add).length > 0 ||
+			Object.keys(change).length > 0 ||
+			Object.keys(remove).length > 0
+
+		return {
+			changed,
+			add,
+			change,
+			remove,
+		}
+	}
+
+	return diffRecords(oldObj, newObj)
+}
+
+/* === Exports === */
+
+export { type DiffResult, diff, isEqual, type UnknownRecord }

package/src/effect.ts

@@ -1,78 +1,88 @@
-import { type Signal, type SignalValues, UNSET } from './signal'
-import { CircularDependencyError, isFunction, toError } from './util'
-import { type Cleanup, watch, observe } from './scheduler'
+import { type Cleanup, observe, watch } from './scheduler'
+import {
+	CircularDependencyError,
+	isAbortError,
+	isAsyncFunction,
+	isFunction,
+} from './util'
 
 /* === Types === */
 
-type EffectMatcher<S extends Signal<{}>[]> = {
-	signals: S
-	ok: (...values: SignalValues<S>) => void | Cleanup
-	err?: (...errors: Error[]) => void | Cleanup
-	nil?: () => void | Cleanup
-}
+// biome-ignore lint/suspicious/noConfusingVoidType: optional Cleanup return type
+type MaybeCleanup = Cleanup | undefined | void
+
+type EffectCallback =
+	| (() => MaybeCleanup)
+	| ((abort: AbortSignal) => Promise<MaybeCleanup>)
 
 /* === Functions === */
 
 /**
  * Define what happens when a reactive state changes
  *
+ * The callback can be synchronous or asynchronous. Async callbacks receive
+ * an AbortSignal parameter, which is automatically aborted when the effect
+ * re-runs or is cleaned up, preventing stale async operations.
+ *
  * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
- * @returns {Cleanup} - cleanup function for the effect
+ * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
+ * @returns {Cleanup} - Cleanup function for the effect
  */
-function effect<S extends Signal<{}>[]>(
-	matcher: EffectMatcher<S> | (() => void | Cleanup),
-): Cleanup {
-	const {
-		signals,
-		ok,
-		err = console.error,
-		nil = () => {},
-	} = isFunction(matcher)
-		? { signals: [] as unknown as S, ok: matcher }
-		: matcher
-
+const effect = (callback: EffectCallback): Cleanup => {
+	const isAsync = isAsyncFunction<MaybeCleanup>(callback)
 	let running = false
+	let controller: AbortController | undefined
+
 	const run = watch(() =>
 		observe(() => {
 			if (running) throw new CircularDependencyError('effect')
 			running = true
 
-			// Pure part
-			const errors: Error[] = []
-			let pending = false
-			const values = signals.map(signal => {
-				try {
-					const value = signal.get()
-					if (value === UNSET) pending = true
-					return value
-				} catch (e) {
-					errors.push(toError(e))
-					return UNSET
-				}
-			}) as SignalValues<S>
+			// Abort any previous async operations
+			controller?.abort()
+			controller = undefined
+
+			let cleanup: MaybeCleanup | Promise<MaybeCleanup>
 
-			// Effectful part
-			let cleanup: void | Cleanup = undefined
 			try {
-				cleanup = pending
-					? nil()
-					: errors.length
-						? err(...errors)
-						: ok(...values)
-			} catch (e) {
-				cleanup = err(toError(e))
-			} finally {
-				if (isFunction(cleanup)) run.off(cleanup)
+				if (isAsync) {
+					// Create AbortController for async callback
+					controller = new AbortController()
+					const currentController = controller
+					callback(controller.signal)
+						.then(cleanup => {
+							// Only register cleanup if this is still the current controller
+							if (
+								isFunction(cleanup) &&
+								controller === currentController
+							) {
+								run.off(cleanup)
+							}
+						})
+						.catch(error => {
+							if (!isAbortError(error))
+								console.error('Async effect error:', error)
+						})
+				} else {
+					cleanup = (callback as () => MaybeCleanup)()
+					if (isFunction(cleanup)) run.off(cleanup)
+				}
+			} catch (error) {
+				if (!isAbortError(error))
+					console.error('Effect callback error:', error)
 			}
 
 			running = false
 		}, run),
 	)
+
 	run()
-	return () => run.cleanup()
+	return () => {
+		controller?.abort()
+		run.cleanup()
+	}
 }
 
 /* === Exports === */
 
-export { type EffectMatcher, effect }
+export { type MaybeCleanup, type EffectCallback, effect }

package/src/match.ts

@@ -0,0 +1,57 @@
+import type { ResolveResult } from './resolve'
+import type { Signal, SignalValues } from './signal'
+import { toError } from './util'
+
+/* === Types === */
+
+type MatchHandlers<S extends Record<string, Signal<unknown & {}>>> = {
+	ok?: (values: SignalValues<S>) => void
+	err?: (errors: readonly Error[]) => void
+	nil?: () => void
+}
+
+/* === Functions === */
+
+/**
+ * Match on resolve result and call appropriate handler for side effects
+ *
+ * This is a utility function for those who prefer the handler pattern.
+ * All handlers are for side effects only and return void. If you need
+ * cleanup logic, use a hoisted let variable in your effect.
+ *
+ * @since 0.15.0
+ * @param {ResolveResult<S>} result - Result from resolve()
+ * @param {MatchHandlers<S>} handlers - Handlers for different states (side effects only)
+ * @returns {void} - Always returns void
+ */
+function match<S extends Record<string, Signal<unknown & {}>>>(
+	result: ResolveResult<S>,
+	handlers: MatchHandlers<S>,
+): void {
+	try {
+		if (result.pending) {
+			handlers.nil?.()
+		} else if (result.errors) {
+			handlers.err?.(result.errors)
+		} else {
+			handlers.ok?.(result.values as SignalValues<S>)
+		}
+	} catch (error) {
+		// If handler throws, try error handler, otherwise rethrow
+		if (
+			handlers.err &&
+			(!result.errors || !result.errors.includes(toError(error)))
+		) {
+			const allErrors = result.errors
+				? [...result.errors, toError(error)]
+				: [toError(error)]
+			handlers.err(allErrors)
+		} else {
+			throw error
+		}
+	}
+}
+
+/* === Exports === */
+
+export { match, type MatchHandlers }

package/src/resolve.ts

@@ -0,0 +1,58 @@
+import type { UnknownRecord } from './diff'
+import { type Signal, type SignalValues, UNSET } from './signal'
+import { toError } from './util'
+
+/* === Types === */
+
+type ResolveResult<S extends Record<string, Signal<unknown & {}>>> =
+	| { ok: true; values: SignalValues<S>; errors?: never; pending?: never }
+	| { ok: false; errors: readonly Error[]; values?: never; pending?: never }
+	| { ok: false; pending: true; values?: never; errors?: never }
+
+/* === Functions === */
+
+/**
+ * Resolve signal values with perfect type inference
+ *
+ * Always returns a discriminated union result, regardless of whether
+ * handlers are provided or not. This ensures a predictable API.
+ *
+ * @since 0.15.0
+ * @param {S} signals - Signals to resolve
+ * @returns {ResolveResult<S>} - Discriminated union result
+ */
+function resolve<S extends Record<string, Signal<unknown & {}>>>(
+	signals: S,
+): ResolveResult<S> {
+	const errors: Error[] = []
+	let pending = false
+	const values: UnknownRecord = {}
+
+	// Collect values and errors
+	for (const [key, signal] of Object.entries(signals)) {
+		try {
+			const value = signal.get()
+
+			if (value === UNSET) {
+				pending = true
+			} else {
+				values[key] = value
+			}
+		} catch (e) {
+			errors.push(toError(e))
+		}
+	}
+
+	// Return discriminated union
+	if (pending) {
+		return { ok: false, pending: true }
+	}
+	if (errors.length > 0) {
+		return { ok: false, errors }
+	}
+	return { ok: true, values: values as SignalValues<S> }
+}
+
+/* === Exports === */
+
+export { resolve, type ResolveResult }

package/src/scheduler.ts

@@ -8,7 +8,7 @@ type Watcher = {
 	cleanup(): void
 }
 
-type Updater = <T>() => T | boolean | void
+type Updater = <T>() => T | boolean | undefined
 
 /* === Internal === */
 
@@ -145,8 +145,8 @@ const observe = (run: () => void, watcher?: Watcher): void => {
  * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
 const enqueue = <T>(fn: Updater, dedupe?: symbol) =>
-	new Promise<T | boolean | void>((resolve, reject) => {
-		updateMap.set(dedupe || Symbol(), () => {
+	new Promise<T | boolean | undefined>((resolve, reject) => {
+		updateMap.set(dedupe || Symbol(), (): undefined => {
 			try {
 				resolve(fn())
 			} catch (error) {