@zeix/cause-effect 0.17.1 → 0.17.3

package/src/classes/computed.ts

@@ -7,10 +7,12 @@ import {
 } from '../errors'
 import {
 	createWatcher,
-	flushPendingReactions,
-	notifyWatchers,
-	subscribeActiveWatcher,
-	trackSignalReads,
+	flush,
+	notifyOf,
+	registerWatchCallbacks,
+	type SignalOptions,
+	subscribeTo,
+	UNSET,
 	type Watcher,
 } from '../system'
 import {
@@ -18,7 +20,6 @@ import {
 	isAsyncFunction,
 	isObjectOfType,
 	isSyncFunction,
-	UNSET,
 } from '../util'
 
 /* === Types === */
@@ -28,6 +29,10 @@ type Computed<T extends {}> = {
 	get(): T
 }
 
+type ComputedOptions<T extends {}> = SignalOptions<T> & {
+	initialValue?: T
+}
+
 type MemoCallback<T extends {} & { then?: undefined }> = (oldValue: T) => T
 
 type TaskCallback<T extends {} & { then?: undefined }> = (
@@ -45,56 +50,38 @@ const TYPE_COMPUTED = 'Computed' as const
  * Create a new memoized signal for a synchronous function.
  *
  * @since 0.17.0
+ * @param {MemoCallback<T>} callback - Callback function to compute the memoized value
+ * @param {T} [initialValue = UNSET] - Initial value of the signal
+ * @throws {InvalidCallbackError} If the callback is not an sync function
+ * @throws {InvalidSignalValueError} If the initial value is not valid
  */
 class Memo<T extends {}> {
-	#watchers: Set<Watcher> = new Set()
 	#callback: MemoCallback<T>
 	#value: T
 	#error: Error | undefined
 	#dirty = true
 	#computing = false
-	#watcher: Watcher
+	#watcher: Watcher | undefined
 
-	/**
-	 * Create a new memoized signal.
-	 *
-	 * @param {MemoCallback<T>} callback - Callback function to compute the memoized value
-	 * @param {T} [initialValue = UNSET] - Initial value of the signal
-	 * @throws {InvalidCallbackError} If the callback is not an sync function
-	 * @throws {InvalidSignalValueError} If the initial value is not valid
-	 */
-	constructor(callback: MemoCallback<T>, initialValue: T = UNSET) {
-		validateCallback('memo', callback, isMemoCallback)
-		validateSignalValue('memo', initialValue)
+	constructor(callback: MemoCallback<T>, options?: ComputedOptions<T>) {
+		validateCallback(this.constructor.name, callback, isMemoCallback)
+		const initialValue = options?.initialValue ?? UNSET
+		validateSignalValue(this.constructor.name, initialValue, options?.guard)
 
 		this.#callback = callback
 		this.#value = initialValue
-
-		// Own watcher: called by notifyWatchers() in upstream signals (push)
-		this.#watcher = createWatcher(() => {
-			this.#dirty = true
-			if (this.#watchers.size) notifyWatchers(this.#watchers)
-			else this.#watcher.stop()
-		})
-	}
-
-	get [Symbol.toStringTag](): 'Computed' {
-		return TYPE_COMPUTED
+		if (options?.watched)
+			registerWatchCallbacks(this, options.watched, options.unwatched)
 	}
 
-	/**
-	 * Return the memoized value after computing it if necessary.
-	 *
-	 * @returns {T}
-	 * @throws {CircularDependencyError} If a circular dependency is detected
-	 * @throws {Error} If an error occurs during computation
-	 */
-	get(): T {
-		subscribeActiveWatcher(this.#watchers)
-		flushPendingReactions()
-
-		if (this.#dirty) {
-			trackSignalReads(this.#watcher, () => {
+	#getWatcher(): Watcher {
+		// Own watcher: called by notifyWatchers() in upstream signals (push)
+		this.#watcher ||= createWatcher(
+			() => {
+				this.#dirty = true
+				if (!notifyOf(this)) this.#watcher?.stop()
+			},
+			() => {
 				if (this.#computing) throw new CircularDependencyError('memo')
 
 				let result: T
@@ -120,9 +107,31 @@ class Memo<T extends {}> {
 					this.#dirty = false
 				}
 				this.#computing = false
-			})
-		}
+			},
+		)
+		this.#watcher.onCleanup(() => {
+			this.#watcher = undefined
+		})
+
+		return this.#watcher
+	}
+
+	get [Symbol.toStringTag](): 'Computed' {
+		return TYPE_COMPUTED
+	}
 
+	/**
+	 * Return the memoized value after computing it if necessary.
+	 *
+	 * @returns {T}
+	 * @throws {CircularDependencyError} If a circular dependency is detected
+	 * @throws {Error} If an error occurs during computation
+	 */
+	get(): T {
+		subscribeTo(this)
+		flush()
+
+		if (this.#dirty) this.#getWatcher().run()
 		if (this.#error) throw this.#error
 		return this.#value
 	}
@@ -132,43 +141,124 @@ class Memo<T extends {}> {
  * Create a new task signals that memoizes the result of an asynchronous function.
  *
  * @since 0.17.0
+ * @param {TaskCallback<T>} callback - The asynchronous function to compute the memoized value
+ * @param {T} [initialValue = UNSET] - Initial value of the signal
+ * @throws {InvalidCallbackError} If the callback is not an async function
+ * @throws {InvalidSignalValueError} If the initial value is not valid
  */
 class Task<T extends {}> {
-	#watchers: Set<Watcher> = new Set()
 	#callback: TaskCallback<T>
 	#value: T
 	#error: Error | undefined
 	#dirty = true
 	#computing = false
 	#changed = false
-	#watcher: Watcher
+	#watcher: Watcher | undefined
 	#controller: AbortController | undefined
 
-	/**
-	 * Create a new task signal for an asynchronous function.
-	 *
-	 * @param {TaskCallback<T>} callback - The asynchronous function to compute the memoized value
-	 * @param {T} [initialValue = UNSET] - Initial value of the signal
-	 * @throws {InvalidCallbackError} If the callback is not an async function
-	 * @throws {InvalidSignalValueError} If the initial value is not valid
-	 */
-	constructor(callback: TaskCallback<T>, initialValue: T = UNSET) {
-		validateCallback('task', callback, isTaskCallback)
-		validateSignalValue('task', initialValue)
+	constructor(callback: TaskCallback<T>, options?: ComputedOptions<T>) {
+		validateCallback(this.constructor.name, callback, isTaskCallback)
+		const initialValue = options?.initialValue ?? UNSET
+		validateSignalValue(this.constructor.name, initialValue, options?.guard)
 
 		this.#callback = callback
 		this.#value = initialValue
+		if (options?.watched)
+			registerWatchCallbacks(this, options.watched, options.unwatched)
+	}
 
-		// Own watcher: called by notifyWatchers() in upstream signals (push)
-		this.#watcher = createWatcher(() => {
-			this.#dirty = true
-			this.#controller?.abort()
-			if (this.#watchers.size) notifyWatchers(this.#watchers)
-			else this.#watcher.stop()
-		})
-		this.#watcher.onCleanup(() => {
-			this.#controller?.abort()
-		})
+	#getWatcher(): Watcher {
+		if (!this.#watcher) {
+			// Functions to update internal state
+			const ok = (v: T): undefined => {
+				if (!isEqual(v, this.#value)) {
+					this.#value = v
+					this.#changed = true
+				}
+				this.#error = undefined
+				this.#dirty = false
+			}
+			const nil = (): undefined => {
+				this.#changed = UNSET !== this.#value
+				this.#value = UNSET
+				this.#error = undefined
+			}
+			const err = (e: unknown): undefined => {
+				const newError = createError(e)
+				this.#changed =
+					!this.#error ||
+					newError.name !== this.#error.name ||
+					newError.message !== this.#error.message
+				this.#value = UNSET
+				this.#error = newError
+			}
+			const settle =
+				<T>(fn: (arg: T) => void) =>
+				(arg: T) => {
+					this.#computing = false
+					this.#controller = undefined
+					fn(arg)
+					if (this.#changed && !notifyOf(this)) this.#watcher?.stop()
+				}
+
+			// Own watcher: called by notifyOf() in upstream signals (push)
+			this.#watcher = createWatcher(
+				() => {
+					this.#dirty = true
+					this.#controller?.abort()
+					if (!notifyOf(this)) this.#watcher?.stop()
+				},
+				() => {
+					if (this.#computing)
+						throw new CircularDependencyError('task')
+					this.#changed = false
+
+					// Return current value until promise resolves
+					if (this.#controller) return this.#value
+
+					this.#controller = new AbortController()
+					this.#controller.signal.addEventListener(
+						'abort',
+						() => {
+							this.#computing = false
+							this.#controller = undefined
+
+							// Retry computation with updated state
+							this.#getWatcher().run()
+						},
+						{
+							once: true,
+						},
+					)
+					let result: Promise<T>
+					this.#computing = true
+					try {
+						result = this.#callback(
+							this.#value,
+							this.#controller.signal,
+						)
+					} catch (e) {
+						if (isAbortError(e)) nil()
+						else err(e)
+						this.#computing = false
+						return
+					}
+
+					if (result instanceof Promise)
+						result.then(settle(ok), settle(err))
+					else if (null == result || UNSET === result) nil()
+					else ok(result)
+					this.#computing = false
+				},
+			)
+			this.#watcher.onCleanup(() => {
+				this.#controller?.abort()
+				this.#controller = undefined
+				this.#watcher = undefined
+			})
+		}
+
+		return this.#watcher
 	}
 
 	get [Symbol.toStringTag](): 'Computed' {
@@ -183,86 +273,10 @@ class Task<T extends {}> {
 	 * @throws {Error} If an error occurs during computation
 	 */
 	get(): T {
-		subscribeActiveWatcher(this.#watchers)
-		flushPendingReactions()
-
-		// Functions to update internal state
-		const ok = (v: T): undefined => {
-			if (!isEqual(v, this.#value)) {
-				this.#value = v
-				this.#changed = true
-			}
-			this.#error = undefined
-			this.#dirty = false
-		}
-		const nil = (): undefined => {
-			this.#changed = UNSET !== this.#value
-			this.#value = UNSET
-			this.#error = undefined
-		}
-		const err = (e: unknown): undefined => {
-			const newError = createError(e)
-			this.#changed =
-				!this.#error ||
-				newError.name !== this.#error.name ||
-				newError.message !== this.#error.message
-			this.#value = UNSET
-			this.#error = newError
-		}
-		const settle =
-			<T>(fn: (arg: T) => void) =>
-			(arg: T) => {
-				this.#computing = false
-				this.#controller = undefined
-				fn(arg)
-				if (this.#changed) notifyWatchers(this.#watchers)
-			}
-
-		const compute = () =>
-			trackSignalReads(this.#watcher, () => {
-				if (this.#computing) throw new CircularDependencyError('task')
-				this.#changed = false
-
-				// Return current value until promise resolves
-				if (this.#controller) return this.#value
-
-				this.#controller = new AbortController()
-				this.#controller.signal.addEventListener(
-					'abort',
-					() => {
-						this.#computing = false
-						this.#controller = undefined
-
-						// Retry computation with updated state
-						compute()
-					},
-					{
-						once: true,
-					},
-				)
-				let result: Promise<T>
-				this.#computing = true
-				try {
-					result = this.#callback(
-						this.#value,
-						this.#controller.signal,
-					)
-				} catch (e) {
-					if (isAbortError(e)) nil()
-					else err(e)
-					this.#computing = false
-					return
-				}
-
-				if (result instanceof Promise)
-					result.then(settle(ok), settle(err))
-				else if (null == result || UNSET === result) nil()
-				else ok(result)
-				this.#computing = false
-			})
-
-		if (this.#dirty) compute()
+		subscribeTo(this)
+		flush()
 
+		if (this.#dirty) this.#getWatcher().run()
 		if (this.#error) throw this.#error
 		return this.#value
 	}
@@ -275,14 +289,15 @@ class Task<T extends {}> {
  *
  * @since 0.9.0
  * @param {MemoCallback<T> | TaskCallback<T>} callback - Computation callback function
+ * @param {ComputedOptions<T>} options - Optional configuration
  */
 const createComputed = <T extends {}>(
 	callback: TaskCallback<T> | MemoCallback<T>,
-	initialValue: T = UNSET,
+	options?: ComputedOptions<T>,
 ) =>
 	isAsyncFunction(callback)
-		? new Task(callback as TaskCallback<T>, initialValue)
-		: new Memo(callback as MemoCallback<T>, initialValue)
+		? new Task(callback as TaskCallback<T>, options)
+		: new Memo(callback as MemoCallback<T>, options)
 
 /**
  * Check if a value is a computed signal
@@ -328,6 +343,7 @@ export {
 	Memo,
 	Task,
 	type Computed,
+	type ComputedOptions,
 	type MemoCallback,
 	type TaskCallback,
 }