@zeix/cause-effect 0.13.2 → 0.14.0

package/src/computed.ts

@@ -1,220 +1,36 @@
-import { type Signal, type ComputedCallback, match, UNSET } from './signal'
-import {
-	CircularDependencyError,
-	isAbortError,
-	isAsyncFunction,
-	isFunction,
-	isObjectOfType,
-	isPromise,
-	toError,
-} from './util'
-import { type Watcher, flush, notify, subscribe, watch } from './scheduler'
-import { type TapMatcher, type EffectMatcher, effect } from './effect'
+import { isAsyncFunction, isObjectOfType } from './util'
+import { type MemoCallback, memo } from './memo'
+import { type TaskCallback, task } from './task'
 
 /* === Types === */
 
-export type ComputedMatcher<S extends Signal<{}>[], R extends {}> = {
-	signals: S
-	abort?: AbortSignal
-	ok: (
-		...values: {
-			[K in keyof S]: S[K] extends Signal<infer T> ? T : never
-		}
-	) => R | Promise<R>
-	err?: (...errors: Error[]) => R | Promise<R>
-	nil?: () => R | Promise<R>
-}
-
-export type Computed<T extends {}> = {
+type Computed<T extends {}> = {
 	[Symbol.toStringTag]: 'Computed'
 	get(): T
-	map<U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U>
-	tap(matcher: TapMatcher<T> | ((v: T) => void | (() => void))): () => void
 }
+type ComputedCallback<T extends {} & { then?: void }> =
+	| TaskCallback<T>
+	| MemoCallback<T>
 
 /* === Constants === */
 
 const TYPE_COMPUTED = 'Computed'
 
-/* === Private Functions === */
-
-const isEquivalentError = /*#__PURE__*/ (
-	error1: Error,
-	error2: Error | undefined,
-): boolean => {
-	if (!error2) return false
-	return error1.name === error2.name && error1.message === error2.message
-}
-
-/* === Computed Factory === */
+/* === Functions === */
 
 /**
  * Create a derived signal from existing signals
  *
+ * This function delegates to either memo() for synchronous computations
+ * or task() for asynchronous computations, providing better performance
+ * for each case.
+ *
  * @since 0.9.0
- * @param {ComputedMatcher<S, T> | ComputedCallback<T>} matcher - computed matcher or callback
+ * @param {ComputedCallback<T>} fn - computation callback function
  * @returns {Computed<T>} - Computed signal
  */
-export const computed = <T extends {}, S extends Signal<{}>[] = []>(
-	matcher: ComputedMatcher<S, T> | ComputedCallback<T>,
-): Computed<T> => {
-	const watchers: Set<Watcher> = new Set()
-	const m = isFunction(matcher)
-		? undefined
-		: ({
-				nil: () => UNSET,
-				err: (...errors: Error[]) => {
-					if (errors.length > 1) throw new AggregateError(errors)
-					else throw errors[0]
-				},
-				...matcher,
-			} as Required<ComputedMatcher<S, T>>)
-	const fn = (m ? m.ok : matcher) as ComputedCallback<T>
-
-	// Internal state
-	let value: T = UNSET
-	let error: Error | undefined
-	let dirty = true
-	let changed = false
-	let computing = false
-	let controller: AbortController | undefined
-
-	// Functions to update internal state
-	const ok = (v: T) => {
-		if (!Object.is(v, value)) {
-			value = v
-			dirty = false
-			error = undefined
-			changed = true
-		}
-	}
-	const nil = () => {
-		changed = UNSET !== value
-		value = UNSET
-		error = undefined
-	}
-	const err = (e: unknown) => {
-		const newError = toError(e)
-		changed = !isEquivalentError(newError, error)
-		value = UNSET
-		error = newError
-	}
-	const resolve = (v: T) => {
-		computing = false
-		controller = undefined
-		ok(v)
-		if (changed) notify(watchers)
-	}
-	const reject = (e: unknown) => {
-		computing = false
-		controller = undefined
-		err(e)
-		if (changed) notify(watchers)
-	}
-	const abort = () => {
-		computing = false
-		controller = undefined
-		compute() // retry
-	}
-
-	// Called when notified from sources (push)
-	const mark = (() => {
-		dirty = true
-		controller?.abort('Aborted because source signal changed')
-		if (watchers.size) {
-			notify(watchers)
-		} else {
-			mark.cleanups.forEach((fn: () => void) => fn())
-			mark.cleanups.clear()
-		}
-	}) as Watcher
-	mark.cleanups = new Set()
-
-	// Called when requested by dependencies (pull)
-	const compute = () =>
-		watch(() => {
-			if (computing) throw new CircularDependencyError('computed')
-			changed = false
-			if (isAsyncFunction(fn)) {
-				if (controller) return value // return current value until promise resolves
-				controller = new AbortController()
-				if (m)
-					m.abort =
-						m.abort instanceof AbortSignal
-							? AbortSignal.any([m.abort, controller.signal])
-							: controller.signal
-				controller.signal.addEventListener('abort', abort, {
-					once: true,
-				})
-			}
-			let result: T | Promise<T>
-			computing = true
-			try {
-				result =
-					m && m.signals.length
-						? match<S, T>(m)
-						: fn(controller?.signal)
-			} catch (e) {
-				if (isAbortError(e)) nil()
-				else err(e)
-				computing = false
-				return
-			}
-			if (isPromise(result)) result.then(resolve, reject)
-			else if (null == result || UNSET === result) nil()
-			else ok(result)
-			computing = false
-		}, mark)
-
-	const c: Computed<T> = {
-		[Symbol.toStringTag]: TYPE_COMPUTED,
-
-		/**
-		 * Get the current value of the computed
-		 *
-		 * @since 0.9.0
-		 * @returns {T} - current value of the computed
-		 */
-		get: (): T => {
-			subscribe(watchers)
-			flush()
-			if (dirty) compute()
-			if (error) throw error
-			return value
-		},
-
-		/**
-		 * Create a computed signal from the current computed signal
-		 *
-		 * @since 0.9.0
-		 * @param {((v: T) => U | Promise<U>)} fn - computed callback
-		 * @returns {Computed<U>} - computed signal
-		 */
-		map: <U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U> =>
-			computed({
-				signals: [c],
-				ok: fn,
-			}),
-
-		/**
-		 * Case matching for the computed signal with effect callbacks
-		 *
-		 * @since 0.13.0
-		 * @param {TapMatcher<T> | ((v: T) => void | (() => void))} matcher - tap matcher or effect callback
-		 * @returns {() => void} - cleanup function for the effect
-		 */
-		tap: (
-			matcher: TapMatcher<T> | ((v: T) => void | (() => void)),
-		): (() => void) =>
-			effect({
-				signals: [c],
-				...(isFunction(matcher) ? { ok: matcher } : matcher),
-			} as EffectMatcher<[Computed<T>]>),
-	}
-	return c
-}
-
-/* === Helper Functions === */
+const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> =>
+	isAsyncFunction<T>(fn) ? task<T>(fn) : memo<T>(fn as MemoCallback<T>)
 
 /**
  * Check if a value is a computed state
@@ -223,6 +39,16 @@ export const computed = <T extends {}, S extends Signal<{}>[] = []>(
  * @param {unknown} value - value to check
  * @returns {boolean} - true if value is a computed state, false otherwise
  */
-export const isComputed = /*#__PURE__*/ <T extends {}>(
+const isComputed = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
 ): value is Computed<T> => isObjectOfType(value, TYPE_COMPUTED)
+
+/* === Exports === */
+
+export {
+	type Computed,
+	type ComputedCallback,
+	TYPE_COMPUTED,
+	computed,
+	isComputed,
+}

package/src/effect.d.ts

@@ -1,22 +1,19 @@
 import { type Signal } from './signal';
-export type TapMatcher<T extends {}> = {
-    ok: (value: T) => void | (() => void);
-    err?: (error: Error) => void | (() => void);
-    nil?: () => void | (() => void);
-};
-export type EffectMatcher<S extends Signal<{}>[]> = {
+import { type Cleanup } from './scheduler';
+type EffectMatcher<S extends Signal<{}>[]> = {
     signals: S;
     ok: (...values: {
         [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
-    }) => void | (() => void);
-    err?: (...errors: Error[]) => void | (() => void);
-    nil?: () => void | (() => void);
+    }) => void | Cleanup;
+    err?: (...errors: Error[]) => void | Cleanup;
+    nil?: () => void | Cleanup;
 };
 /**
  * Define what happens when a reactive state changes
  *
  * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | (() => void))} matcher - effect matcher or callback
- * @returns {() => void} - cleanup function for the effect
+ * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @returns {Cleanup} - cleanup function for the effect
  */
-export declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | (() => void))): () => void;
+declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | Cleanup)): Cleanup;
+export { type EffectMatcher, effect };

package/src/effect.ts

@@ -1,38 +1,37 @@
-import { type Signal, match } from './signal'
-import { CircularDependencyError, isFunction, toError } from './util'
-import { watch, type Watcher } from './scheduler'
+import { type Signal, UNSET } from './signal'
+import {
+	CircularDependencyError,
+	isFunction,
+	toError,
+	isAbortError,
+} from './util'
+import { watch, type Cleanup, type Watcher } from './scheduler'
 
 /* === Types === */
 
-export type TapMatcher<T extends {}> = {
-	ok: (value: T) => void | (() => void)
-	err?: (error: Error) => void | (() => void)
-	nil?: () => void | (() => void)
-}
-
-export type EffectMatcher<S extends Signal<{}>[]> = {
+type EffectMatcher<S extends Signal<{}>[]> = {
 	signals: S
 	ok: (
 		...values: {
 			[K in keyof S]: S[K] extends Signal<infer T> ? T : never
 		}
-	) => void | (() => void)
-	err?: (...errors: Error[]) => void | (() => void)
-	nil?: () => void | (() => void)
+	) => void | Cleanup
+	err?: (...errors: Error[]) => void | Cleanup
+	nil?: () => void | Cleanup
 }
 
-/* === Exported Functions === */
+/* === Functions === */
 
 /**
  * Define what happens when a reactive state changes
  *
  * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | (() => void))} matcher - effect matcher or callback
- * @returns {() => void} - cleanup function for the effect
+ * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @returns {Cleanup} - cleanup function for the effect
  */
-export function effect<S extends Signal<{}>[]>(
-	matcher: EffectMatcher<S> | (() => void | (() => void)),
-): () => void {
+function effect<S extends Signal<{}>[]>(
+	matcher: EffectMatcher<S> | (() => void | Cleanup),
+): Cleanup {
 	const {
 		signals,
 		ok,
@@ -46,24 +45,51 @@ export function effect<S extends Signal<{}>[]>(
 		watch(() => {
 			if (running) throw new CircularDependencyError('effect')
 			running = true
-			let cleanup: void | (() => void) = undefined
+			let cleanup: void | Cleanup = undefined
 			try {
-				cleanup = match<S, void | (() => void)>({
-					signals,
-					ok,
-					err,
-					nil,
-				}) as void | (() => void)
+				const errors: Error[] = []
+				let suspense = false
+				const values = signals.map(signal => {
+					try {
+						const value = signal.get()
+						if (value === UNSET) suspense = true
+						return value
+					} catch (e) {
+						if (isAbortError(e)) throw e
+						errors.push(toError(e))
+						return UNSET
+					}
+				}) as {
+					[K in keyof S]: S[K] extends Signal<infer T extends {}>
+						? T
+						: never
+				}
+
+				try {
+					cleanup = suspense
+						? nil()
+						: errors.length
+							? err(...errors)
+							: ok(...values)
+				} catch (e) {
+					if (isAbortError(e)) throw e
+					const error = toError(e)
+					cleanup = err(error)
+				}
 			} catch (e) {
 				err(toError(e))
 			}
 			if (isFunction(cleanup)) run.cleanups.add(cleanup)
 			running = false
 		}, run)) as Watcher
-	run.cleanups = new Set()
+	run.cleanups = new Set<Cleanup>()
 	run()
 	return () => {
-		run.cleanups.forEach((fn: () => void) => fn())
+		run.cleanups.forEach(fn => fn())
 		run.cleanups.clear()
 	}
 }
+
+/* === Exports === */
+
+export { type EffectMatcher, effect }

package/src/memo.d.ts

@@ -0,0 +1,13 @@
+import { type Computed } from './computed';
+type MemoCallback<T extends {} & {
+    then?: void;
+}> = () => T;
+/**
+ * Create a derived signal for synchronous computations
+ *
+ * @since 0.14.0
+ * @param {MemoCallback<T>} fn - synchronous computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+declare const memo: <T extends {}>(fn: MemoCallback<T>) => Computed<T>;
+export { type MemoCallback, memo };

package/src/memo.ts

@@ -0,0 +1,91 @@
+import { UNSET } from './signal'
+import { CircularDependencyError } from './util'
+import {
+	type Cleanup,
+	type Watcher,
+	flush,
+	notify,
+	subscribe,
+	watch,
+} from './scheduler'
+import { type Computed, TYPE_COMPUTED } from './computed'
+
+/* === Types === */
+
+type MemoCallback<T extends {} & { then?: void }> = () => T
+
+/* === Functions === */
+
+/**
+ * Create a derived signal for synchronous computations
+ *
+ * @since 0.14.0
+ * @param {MemoCallback<T>} fn - synchronous computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+const memo = <T extends {}>(fn: MemoCallback<T>): Computed<T> => {
+	const watchers: Set<Watcher> = new Set()
+
+	// Internal state - simplified for sync only
+	let value: T = UNSET
+	let error: Error | undefined
+	let dirty = true
+	let computing = false
+
+	// Called when notified from sources (push)
+	const mark = (() => {
+		dirty = true
+		if (watchers.size) {
+			notify(watchers)
+		} else {
+			mark.cleanups.forEach(fn => fn())
+			mark.cleanups.clear()
+		}
+	}) as Watcher
+	mark.cleanups = new Set<Cleanup>()
+
+	// Called when requested by dependencies (pull)
+	const compute = () =>
+		watch(() => {
+			if (computing) throw new CircularDependencyError('memo')
+			computing = true
+			try {
+				const result = fn()
+				if (null == result || UNSET === result) {
+					value = UNSET
+					error = undefined
+				} else {
+					value = result
+					dirty = false
+					error = undefined
+				}
+			} catch (e) {
+				value = UNSET
+				error = e instanceof Error ? e : new Error(String(e))
+			} finally {
+				computing = false
+			}
+		}, mark)
+
+	const c: Computed<T> = {
+		[Symbol.toStringTag]: TYPE_COMPUTED,
+
+		/**
+		 * Get the current value of the computed
+		 *
+		 * @returns {T} - current value of the computed
+		 */
+		get: (): T => {
+			subscribe(watchers)
+			flush()
+			if (dirty) compute()
+			if (error) throw error
+			return value
+		},
+	}
+	return c
+}
+
+/* === Exports === */
+
+export { type MemoCallback, memo }

package/src/scheduler.d.ts

@@ -1,42 +1,46 @@
-export type EnqueueDedupe = [Element, string];
-export type Watcher = {
+type Cleanup = () => void;
+type Watcher = {
     (): void;
-    cleanups: Set<() => void>;
+    cleanups: Set<Cleanup>;
 };
-export type Updater = <T>() => T | boolean | void;
+type Updater = <T>() => T | boolean | void;
 /**
  * Add active watcher to the Set of watchers
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export declare const subscribe: (watchers: Set<Watcher>) => void;
+declare const subscribe: (watchers: Set<Watcher>) => void;
 /**
  * Add watchers to the pending set of change notifications
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export declare const notify: (watchers: Set<Watcher>) => void;
+declare const notify: (watchers: Set<Watcher>) => void;
 /**
  * Flush all pending changes to notify watchers
  */
-export declare const flush: () => void;
+declare const flush: () => void;
 /**
  * Batch multiple changes in a single signal graph and DOM update cycle
  *
  * @param {() => void} fn - function with multiple signal writes to be batched
  */
-export declare const batch: (fn: () => void) => void;
+declare const batch: (fn: () => void) => void;
 /**
  * Run a function in a reactive context
  *
  * @param {() => void} run - function to run the computation or effect
  * @param {Watcher} mark - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
  */
-export declare const watch: (run: () => void, mark?: Watcher) => void;
+declare const watch: (run: () => void, mark?: Watcher) => void;
 /**
  * Enqueue a function to be executed on the next animation frame
  *
+ * If the same Symbol is provided for multiple calls before the next animation frame,
+ * only the latest call will be executed (deduplication).
+ *
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
- * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
+ * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-export declare const enqueue: <T>(fn: Updater, dedupe: EnqueueDedupe) => Promise<boolean | void | T>;
+declare const enqueue: <T>(fn: Updater, dedupe?: symbol) => Promise<boolean | void | T>;
+export { type Cleanup, type Watcher, type Updater, subscribe, notify, flush, batch, watch, enqueue, };

package/src/scheduler.ts

@@ -1,13 +1,13 @@
 /* === Types === */
 
-export type EnqueueDedupe = [Element, string]
+type Cleanup = () => void
 
-export type Watcher = {
+type Watcher = {
 	(): void
-	cleanups: Set<() => void>
+	cleanups: Set<Cleanup>
 }
 
-export type Updater = <T>() => T | boolean | void
+type Updater = <T>() => T | boolean | void
 
 /* === Internal === */
 
@@ -18,8 +18,8 @@ let active: Watcher | undefined
 const pending = new Set<Watcher>()
 let batchDepth = 0
 
-// Map of DOM elements to update functions
-const updateMap = new Map<EnqueueDedupe, () => void>()
+// Map of deduplication symbols to update functions (using Symbol keys prevents unintended overwrites)
+const updateMap = new Map<symbol, Updater>()
 let requestId: number | undefined
 
 const updateDOM = () => {
@@ -39,14 +39,14 @@ const requestTick = () => {
 // Initial render when the call stack is empty
 queueMicrotask(updateDOM)
 
-/* === Exported Functions === */
+/* === Functions === */
 
 /**
  * Add active watcher to the Set of watchers
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const subscribe = (watchers: Set<Watcher>) => {
+const subscribe = (watchers: Set<Watcher>) => {
 	// if (!active) console.warn('Calling .get() outside of a reactive context')
 	if (active && !watchers.has(active)) {
 		const watcher = active
@@ -62,7 +62,7 @@ export const subscribe = (watchers: Set<Watcher>) => {
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const notify = (watchers: Set<Watcher>) => {
+const notify = (watchers: Set<Watcher>) => {
 	for (const mark of watchers) {
 		if (batchDepth) pending.add(mark)
 		else mark()
@@ -72,7 +72,7 @@ export const notify = (watchers: Set<Watcher>) => {
 /**
  * Flush all pending changes to notify watchers
  */
-export const flush = () => {
+const flush = () => {
 	while (pending.size) {
 		const watchers = Array.from(pending)
 		pending.clear()
@@ -87,7 +87,7 @@ export const flush = () => {
  *
  * @param {() => void} fn - function with multiple signal writes to be batched
  */
-export const batch = (fn: () => void) => {
+const batch = (fn: () => void) => {
 	batchDepth++
 	try {
 		fn()
@@ -103,7 +103,7 @@ export const batch = (fn: () => void) => {
  * @param {() => void} run - function to run the computation or effect
  * @param {Watcher} mark - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
  */
-export const watch = (run: () => void, mark?: Watcher): void => {
+const watch = (run: () => void, mark?: Watcher): void => {
 	const prev = active
 	active = mark
 	try {
@@ -116,12 +116,15 @@ export const watch = (run: () => void, mark?: Watcher): void => {
 /**
  * Enqueue a function to be executed on the next animation frame
  *
+ * If the same Symbol is provided for multiple calls before the next animation frame,
+ * only the latest call will be executed (deduplication).
+ *
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
- * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
+ * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-export const enqueue = <T>(fn: Updater, dedupe: EnqueueDedupe) =>
+const enqueue = <T>(fn: Updater, dedupe?: symbol) =>
 	new Promise<T | boolean | void>((resolve, reject) => {
-		updateMap.set(dedupe, () => {
+		updateMap.set(dedupe || Symbol(), () => {
 			try {
 				resolve(fn())
 			} catch (error) {
@@ -130,3 +133,17 @@ export const enqueue = <T>(fn: Updater, dedupe: EnqueueDedupe) =>
 		})
 		requestTick()
 	})
+
+/* === Exports === */
+
+export {
+	type Cleanup,
+	type Watcher,
+	type Updater,
+	subscribe,
+	notify,
+	flush,
+	batch,
+	watch,
+	enqueue,
+}