@zeix/cause-effect 0.13.2 → 0.14.1

package/src/computed.ts

@@ -1,92 +1,61 @@
-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 {
+	type Watcher,
+	watch,
+	subscribe,
+	notify,
+	flush,
+	observe,
+} from './scheduler'
+import { UNSET } from './signal'
 
 /* === 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 }> =
+	| ((abort: AbortSignal) => Promise<T>)
+	| (() => 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
  *
  * @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 computed = <T extends {}>(fn: 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 controller: AbortController | 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
 		}
+		error = undefined
+		dirty = false
 	}
 	const nil = () => {
 		changed = UNSET !== value
@@ -95,72 +64,61 @@ export const computed = <T extends {}, S extends Signal<{}>[] = []>(
 	}
 	const err = (e: unknown) => {
 		const newError = toError(e)
-		changed = !isEquivalentError(newError, error)
+		changed =
+			!error ||
+			newError.name !== error.name ||
+			newError.message !== error.message
 		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
-	}
+	const settle =
+		<T>(settleFn: (arg: T) => void) =>
+		(arg: T) => {
+			computing = false
+			controller = undefined
+			settleFn(arg)
+			if (changed) notify(watchers)
+		}
 
-	// Called when notified from sources (push)
-	const mark = (() => {
+	// Own watcher: called when notified from sources (push)
+	const mark = watch(() => {
 		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()
+		if (watchers.size) notify(watchers)
+		else mark.cleanup()
+	})
 
 	// Called when requested by dependencies (pull)
 	const compute = () =>
-		watch(() => {
+		observe(() => {
 			if (computing) throw new CircularDependencyError('computed')
 			changed = false
-			if (isAsyncFunction(fn)) {
+			if (isFunction(fn) && fn.constructor.name === 'AsyncFunction') {
 				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,
-				})
+				controller.signal.addEventListener(
+					'abort',
+					() => {
+						computing = false
+						controller = undefined
+						compute() // retry
+					},
+					{
+						once: true,
+					},
+				)
 			}
 			let result: T | Promise<T>
 			computing = true
 			try {
-				result =
-					m && m.signals.length
-						? match<S, T>(m)
-						: fn(controller?.signal)
+				result = controller ? fn(controller.signal) : (fn as () => T)()
 			} catch (e) {
-				if (isAbortError(e)) nil()
+				if (e instanceof DOMException && e.name === 'AbortError') nil()
 				else err(e)
 				computing = false
 				return
 			}
-			if (isPromise(result)) result.then(resolve, reject)
+			if (result instanceof Promise) result.then(settle(ok), settle(err))
 			else if (null == result || UNSET === result) nil()
 			else ok(result)
 			computing = false
@@ -182,40 +140,10 @@ export const computed = <T extends {}, S extends Signal<{}>[] = []>(
 			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 === */
-
 /**
  * Check if a value is a computed state
  *
@@ -223,6 +151,28 @@ 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)
+
+/**
+ * Check if the provided value is a callback that may be used as input for toSignal() to derive a computed state
+ *
+ * @since 0.12.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
+ */
+const isComputedCallback = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is ComputedCallback<T> => isFunction(value) && value.length < 2
+
+/* === Exports === */
+
+export {
+	type Computed,
+	type ComputedCallback,
+	TYPE_COMPUTED,
+	computed,
+	isComputed,
+	isComputedCallback,
+}

package/src/effect.d.ts

@@ -1,22 +1,17 @@
-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 Signal, type SignalValues } from './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);
+    ok: (...values: SignalValues<S>) => 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,28 @@
-import { type Signal, match } from './signal'
+import { type Signal, type SignalValues, UNSET } from './signal'
 import { CircularDependencyError, isFunction, toError } from './util'
-import { watch, type Watcher } from './scheduler'
+import { type Cleanup, watch, observe } 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)
+	ok: (...values: SignalValues<S>) => 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,
@@ -41,29 +31,48 @@ export function effect<S extends Signal<{}>[]>(
 	} = isFunction(matcher)
 		? { signals: [] as unknown as S, ok: matcher }
 		: matcher
+
 	let running = false
-	const run = (() =>
-		watch(() => {
+	const run = watch(() =>
+		observe(() => {
 			if (running) throw new CircularDependencyError('effect')
 			running = true
-			let cleanup: void | (() => void) = undefined
+
+			// 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>
+
+			// Effectful part
+			let cleanup: void | Cleanup = undefined
 			try {
-				cleanup = match<S, void | (() => void)>({
-					signals,
-					ok,
-					err,
-					nil,
-				}) as void | (() => void)
+				cleanup = pending
+					? nil()
+					: errors.length
+						? err(...errors)
+						: ok(...values)
 			} catch (e) {
-				err(toError(e))
+				cleanup = err(toError(e))
+			} finally {
+				if (isFunction(cleanup)) run.off(cleanup)
 			}
-			if (isFunction(cleanup)) run.cleanups.add(cleanup)
+
 			running = false
-		}, run)) as Watcher
-	run.cleanups = new Set()
+		}, run),
+	)
 	run()
-	return () => {
-		run.cleanups.forEach((fn: () => void) => fn())
-		run.cleanups.clear()
-	}
+	return () => run.cleanup()
 }
+
+/* === Exports === */
+
+export { type EffectMatcher, effect }

package/src/scheduler.d.ts

@@ -1,42 +1,55 @@
-export type EnqueueDedupe = [Element, string];
-export type Watcher = {
+type Cleanup = () => void;
+type Watcher = {
     (): void;
-    cleanups: Set<() => void>;
+    off(cleanup: Cleanup): void;
+    cleanup(): void;
 };
-export type Updater = <T>() => T | boolean | void;
+type Updater = <T>() => T | boolean | void;
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} notice - function to be called when the state changes
+ * @returns {Watcher} - watcher object with off and cleanup methods
+ */
+declare const watch: (notice: () => void) => Watcher;
 /**
  * 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)
+ * @param {Watcher} watcher - 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 observe: (run: () => void, watcher?: 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, observe, enqueue, };

package/src/scheduler.ts

@@ -1,13 +1,14 @@
 /* === Types === */
 
-export type EnqueueDedupe = [Element, string]
+type Cleanup = () => void
 
-export type Watcher = {
+type Watcher = {
 	(): void
-	cleanups: Set<() => void>
+	off(cleanup: Cleanup): void
+	cleanup(): void
 }
 
-export type Updater = <T>() => T | boolean | void
+type Updater = <T>() => T | boolean | void
 
 /* === Internal === */
 
@@ -18,16 +19,16 @@ 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 = () => {
 	requestId = undefined
 	const updates = Array.from(updateMap.values())
 	updateMap.clear()
-	for (const fn of updates) {
-		fn()
+	for (const update of updates) {
+		update()
 	}
 }
 
@@ -39,19 +40,40 @@ const requestTick = () => {
 // Initial render when the call stack is empty
 queueMicrotask(updateDOM)
 
-/* === Exported Functions === */
+/* === Functions === */
+
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} notice - function to be called when the state changes
+ * @returns {Watcher} - watcher object with off and cleanup methods
+ */
+const watch = (notice: () => void): Watcher => {
+	const cleanups = new Set<Cleanup>()
+	const w = notice as Partial<Watcher>
+	w.off = (on: Cleanup) => {
+		cleanups.add(on)
+	}
+	w.cleanup = () => {
+		for (const cleanup of cleanups) {
+			cleanup()
+		}
+		cleanups.clear()
+	}
+	return w as Watcher
+}
 
 /**
  * Add active watcher to the Set of watchers
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const subscribe = (watchers: Set<Watcher>) => {
-	// if (!active) console.warn('Calling .get() outside of a reactive context')
+const subscribe = (watchers: Set<Watcher>) => {
 	if (active && !watchers.has(active)) {
 		const watcher = active
 		watchers.add(watcher)
-		active.cleanups.add(() => {
+		active.off(() => {
 			watchers.delete(watcher)
 		})
 	}
@@ -62,22 +84,22 @@ export const subscribe = (watchers: Set<Watcher>) => {
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const notify = (watchers: Set<Watcher>) => {
-	for (const mark of watchers) {
-		if (batchDepth) pending.add(mark)
-		else mark()
+const notify = (watchers: Set<Watcher>) => {
+	for (const watcher of watchers) {
+		if (batchDepth) pending.add(watcher)
+		else watcher()
 	}
 }
 
 /**
  * Flush all pending changes to notify watchers
  */
-export const flush = () => {
+const flush = () => {
 	while (pending.size) {
 		const watchers = Array.from(pending)
 		pending.clear()
-		for (const mark of watchers) {
-			mark()
+		for (const watcher of watchers) {
+			watcher()
 		}
 	}
 }
@@ -87,7 +109,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()
@@ -101,11 +123,11 @@ export const batch = (fn: () => 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)
+ * @param {Watcher} watcher - 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 observe = (run: () => void, watcher?: Watcher): void => {
 	const prev = active
-	active = mark
+	active = watcher
 	try {
 		run()
 	} finally {
@@ -116,12 +138,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 +155,18 @@ export const enqueue = <T>(fn: Updater, dedupe: EnqueueDedupe) =>
 		})
 		requestTick()
 	})
+
+/* === Exports === */
+
+export {
+	type Cleanup,
+	type Watcher,
+	type Updater,
+	subscribe,
+	notify,
+	flush,
+	batch,
+	watch,
+	observe,
+	enqueue,
+}