@zeix/cause-effect 0.14.2 → 0.15.0

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,80 +1,88 @@
 import { type Cleanup, observe, watch } from './scheduler'
-import { type Signal, type SignalValues, UNSET } from './signal'
-import { CircularDependencyError, isFunction, toError } from './util'
+import {
+	CircularDependencyError,
+	isAbortError,
+	isAsyncFunction,
+	isFunction,
+} from './util'
 
 /* === Types === */
 
-type EffectMatcher<S extends Signal<unknown & {}>[]> = {
-	signals: S
-	ok: (...values: SignalValues<S>) => Cleanup | undefined
-	err?: (...errors: Error[]) => Cleanup | undefined
-	nil?: () => Cleanup | undefined
-}
+// 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> | (() => Cleanup | undefined)} 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<unknown & {}>[]>(
-	matcher: EffectMatcher<S> | (() => Cleanup | undefined),
-): Cleanup {
-	const {
-		signals,
-		ok,
-		err = (error: Error): undefined => {
-			console.error(error)
-		},
-		nil = (): undefined => {},
-	} = 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: 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/signal.ts

@@ -1,10 +1,13 @@
 import {
+	type Computed,
 	type ComputedCallback,
 	computed,
 	isComputed,
 	isComputedCallback,
 } from './computed'
-import { isState, state } from './state'
+import { isState, type State, state } from './state'
+import { isStore, type Store, store } from './store'
+import { arrayToRecord, isRecord } from './util'
 
 /* === Types === */
 
@@ -13,7 +16,7 @@ type Signal<T extends {}> = {
 }
 type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
 
-type SignalValues<S extends Signal<unknown & {}>[]> = {
+type SignalValues<S extends Record<string, Signal<unknown & {}>>> = {
 	[K in keyof S]: S[K] extends Signal<infer T> ? T : never
 }
 
@@ -33,23 +36,52 @@ const UNSET: any = Symbol()
  */
 const isSignal = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
-): value is Signal<T> => isState(value) || isComputed(value)
+): value is Signal<T> => isState(value) || isComputed(value) || isStore(value)
 
 /**
  * Convert a value to a Signal if it's not already a Signal
  *
  * @since 0.9.6
- * @param {MaybeSignal<T>} value - value to convert to a Signal
- * @returns {Signal<T>} - converted Signal
  */
-const toSignal = /*#__PURE__*/ <T extends {}>(
-	value: MaybeSignal<T>,
-): Signal<T> =>
-	isSignal<T>(value)
-		? value
-		: isComputedCallback<T>(value)
-			? computed(value)
-			: state(value as T)
+function toSignal<T extends Array<unknown & {}>>(
+	value: T[],
+): Store<Record<string, T>>
+function toSignal<T extends Record<keyof T, T[keyof T]>>(value: T): Store<T>
+function toSignal<T extends {}>(value: ComputedCallback<T>): Computed<T>
+function toSignal<T extends {}>(value: Signal<T>): Signal<T>
+function toSignal<T extends {}>(value: T): State<T>
+function toSignal<T extends {}>(
+	value: MaybeSignal<T> | T[],
+): Signal<T> | Store<Record<string, T>> {
+	if (isSignal<T>(value)) return value
+	if (isComputedCallback<T>(value)) return computed(value)
+	if (Array.isArray(value)) return store(arrayToRecord(value))
+	if (isRecord(value)) return store(value as T)
+	return state(value as T)
+}
+
+/**
+ * Convert a value to a mutable Signal if it's not already a Signal
+ *
+ * @since 0.9.6
+ */
+function toMutableSignal<T extends Array<unknown & {}>>(
+	value: T[],
+): Store<Record<string, T>>
+function toMutableSignal<T extends Record<keyof T, T[keyof T]>>(
+	value: T,
+): Store<T>
+function toMutableSignal<T extends State<T>>(value: State<T>): State<T>
+function toMutableSignal<T extends Store<T>>(value: Store<T>): Store<T>
+function toMutableSignal<T extends {}>(value: T): State<T>
+function toMutableSignal<T extends {}>(
+	value: T | State<T> | Store<T> | T[],
+): Signal<T> | Store<Record<string, T>> {
+	if (isState<T>(value) || isStore<T>(value)) return value
+	if (Array.isArray(value)) return store(arrayToRecord(value))
+	if (isRecord(value)) return store(value as T)
+	return state(value as T)
+}
 
 /* === Exports === */
 
@@ -59,6 +91,6 @@ export {
 	type SignalValues,
 	UNSET,
 	isSignal,
-	isComputedCallback,
 	toSignal,
+	toMutableSignal,
 }

package/src/state.ts

@@ -1,6 +1,7 @@
+import { isEqual } from './diff'
+import { notify, subscribe, type Watcher } from './scheduler'
 import { UNSET } from './signal'
 import { isObjectOfType } from './util'
-import { type Watcher, notify, subscribe } from './scheduler'
 
 /* === Types === */
 
@@ -50,7 +51,7 @@ const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		 * @returns {void}
 		 */
 		set: (v: T): void => {
-			if (Object.is(value, v)) return
+			if (isEqual(value, v)) return
 			value = v
 			notify(watchers)
 
@@ -86,4 +87,4 @@ const isState = /*#__PURE__*/ <T extends {}>(
 
 /* === Exports === */
 
-export { type State, TYPE_STATE, state, isState }
+export { TYPE_STATE, isState, state, type State }