@zeix/cause-effect 0.17.0 → 0.17.2

package/src/classes/computed.ts

@@ -1,24 +1,30 @@
 import { isEqual } from '../diff'
 import {
 	CircularDependencyError,
+	createError,
+	InvalidHookError,
 	validateCallback,
 	validateSignalValue,
 } from '../errors'
 import {
+	type Cleanup,
 	createWatcher,
 	flushPendingReactions,
+	HOOK_CLEANUP,
+	HOOK_WATCH,
+	type HookCallback,
 	notifyWatchers,
 	subscribeActiveWatcher,
 	trackSignalReads,
+	UNSET,
 	type Watcher,
+	type WatchHook,
 } from '../system'
 import {
 	isAbortError,
 	isAsyncFunction,
 	isObjectOfType,
 	isSyncFunction,
-	toError,
-	UNSET,
 } from '../util'
 
 /* === Types === */
@@ -53,7 +59,8 @@ class Memo<T extends {}> {
 	#error: Error | undefined
 	#dirty = true
 	#computing = false
-	#watcher: Watcher
+	#watcher: Watcher | undefined
+	#watchHookCallbacks: Set<HookCallback> | undefined
 
 	/**
 	 * Create a new memoized signal.
@@ -64,18 +71,25 @@ class Memo<T extends {}> {
 	 * @throws {InvalidSignalValueError} If the initial value is not valid
 	 */
 	constructor(callback: MemoCallback<T>, initialValue: T = UNSET) {
-		validateCallback('memo', callback, isMemoCallback)
-		validateSignalValue('memo', initialValue)
+		validateCallback(this.constructor.name, callback, isMemoCallback)
+		validateSignalValue(this.constructor.name, initialValue)
 
 		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()
-		})
+	#getWatcher(): Watcher {
+		if (!this.#watcher) {
+			// Own watcher: called by notifyWatchers() in upstream signals (push)
+			this.#watcher = createWatcher(() => {
+				this.#dirty = true
+				if (!notifyWatchers(this.#watchers)) this.#watcher?.stop()
+			})
+			this.#watcher.on(HOOK_CLEANUP, () => {
+				this.#watcher = undefined
+			})
+		}
+		return this.#watcher
 	}
 
 	get [Symbol.toStringTag](): 'Computed' {
@@ -90,11 +104,12 @@ class Memo<T extends {}> {
 	 * @throws {Error} If an error occurs during computation
 	 */
 	get(): T {
-		subscribeActiveWatcher(this.#watchers)
+		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
 		flushPendingReactions()
 
 		if (this.#dirty) {
-			trackSignalReads(this.#watcher, () => {
+			const watcher = this.#getWatcher()
+			trackSignalReads(watcher, () => {
 				if (this.#computing) throw new CircularDependencyError('memo')
 
 				let result: T
@@ -104,7 +119,7 @@ class Memo<T extends {}> {
 				} catch (e) {
 					// Err track
 					this.#value = UNSET
-					this.#error = toError(e)
+					this.#error = createError(e)
 					this.#computing = false
 					return
 				}
@@ -126,6 +141,24 @@ class Memo<T extends {}> {
 		if (this.#error) throw this.#error
 		return this.#value
 	}
+
+	/**
+	 * Register a callback to be called when HOOK_WATCH is triggered.
+	 *
+	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
+	 * @param {HookCallback} callback - The callback to register
+	 * @returns {Cleanup} - A function to unregister the callback
+	 */
+	on(type: WatchHook, callback: HookCallback): Cleanup {
+		if (type === HOOK_WATCH) {
+			this.#watchHookCallbacks ||= new Set()
+			this.#watchHookCallbacks.add(callback)
+			return () => {
+				this.#watchHookCallbacks?.delete(callback)
+			}
+		}
+		throw new InvalidHookError(this.constructor.name, type)
+	}
 }
 
 /**
@@ -141,8 +174,9 @@ class Task<T extends {}> {
 	#dirty = true
 	#computing = false
 	#changed = false
-	#watcher: Watcher
+	#watcher: Watcher | undefined
 	#controller: AbortController | undefined
+	#watchHookCallbacks: Set<HookCallback> | undefined
 
 	/**
 	 * Create a new task signal for an asynchronous function.
@@ -153,22 +187,28 @@ class Task<T extends {}> {
 	 * @throws {InvalidSignalValueError} If the initial value is not valid
 	 */
 	constructor(callback: TaskCallback<T>, initialValue: T = UNSET) {
-		validateCallback('task', callback, isTaskCallback)
-		validateSignalValue('task', initialValue)
+		validateCallback(this.constructor.name, callback, isTaskCallback)
+		validateSignalValue(this.constructor.name, initialValue)
 
 		this.#callback = callback
 		this.#value = initialValue
+	}
 
-		// 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) {
+			// Own watcher: called by notifyWatchers() in upstream signals (push)
+			this.#watcher = createWatcher(() => {
+				this.#dirty = true
+				this.#controller?.abort()
+				if (!notifyWatchers(this.#watchers)) this.#watcher?.stop()
+			})
+			this.#watcher.on(HOOK_CLEANUP, () => {
+				this.#controller?.abort()
+				this.#controller = undefined
+				this.#watcher = undefined
+			})
+		}
+		return this.#watcher
 	}
 
 	get [Symbol.toStringTag](): 'Computed' {
@@ -183,7 +223,7 @@ class Task<T extends {}> {
 	 * @throws {Error} If an error occurs during computation
 	 */
 	get(): T {
-		subscribeActiveWatcher(this.#watchers)
+		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
 		flushPendingReactions()
 
 		// Functions to update internal state
@@ -201,7 +241,7 @@ class Task<T extends {}> {
 			this.#error = undefined
 		}
 		const err = (e: unknown): undefined => {
-			const newError = toError(e)
+			const newError = createError(e)
 			this.#changed =
 				!this.#error ||
 				newError.name !== this.#error.name ||
@@ -215,11 +255,12 @@ class Task<T extends {}> {
 				this.#computing = false
 				this.#controller = undefined
 				fn(arg)
-				if (this.#changed) notifyWatchers(this.#watchers)
+				if (this.#changed && !notifyWatchers(this.#watchers))
+					this.#watcher?.stop()
 			}
 
 		const compute = () =>
-			trackSignalReads(this.#watcher, () => {
+			trackSignalReads(this.#getWatcher(), () => {
 				if (this.#computing) throw new CircularDependencyError('task')
 				this.#changed = false
 
@@ -266,6 +307,24 @@ class Task<T extends {}> {
 		if (this.#error) throw this.#error
 		return this.#value
 	}
+
+	/**
+	 * Register a callback to be called when HOOK_WATCH is triggered.
+	 *
+	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
+	 * @param {HookCallback} callback - The callback to register
+	 * @returns {Cleanup} - A function to unregister the callback
+	 */
+	on(type: WatchHook, callback: HookCallback): Cleanup {
+		if (type === HOOK_WATCH) {
+			this.#watchHookCallbacks ||= new Set()
+			this.#watchHookCallbacks.add(callback)
+			return () => {
+				this.#watchHookCallbacks?.delete(callback)
+			}
+		}
+		throw new InvalidHookError(this.constructor.name, type)
+	}
 }
 
 /* === Functions === */

package/src/classes/list.ts

@@ -1,17 +1,28 @@
 import { diff, isEqual, type UnknownArray } from '../diff'
-import { DuplicateKeyError, validateSignalValue } from '../errors'
+import {
+	DuplicateKeyError,
+	InvalidHookError,
+	validateSignalValue,
+} from '../errors'
 import {
 	type Cleanup,
-	emitNotification,
-	type Listener,
-	type Listeners,
-	type Notifications,
+	HOOK_ADD,
+	HOOK_CHANGE,
+	HOOK_REMOVE,
+	HOOK_SORT,
+	HOOK_WATCH,
+	type Hook,
+	type HookCallback,
+	type HookCallbacks,
+	isHandledHook,
 	notifyWatchers,
 	subscribeActiveWatcher,
+	triggerHook,
+	UNSET,
 	type Watcher,
 } from '../system'
-import { isFunction, isNumber, isObjectOfType, isString, UNSET } from '../util'
-import { Collection, type CollectionCallback } from './collection'
+import { isFunction, isNumber, isObjectOfType, isString } from '../util'
+import { type CollectionCallback, DerivedCollection } from './collection'
 import { Composite } from './composite'
 import { State } from './state'
 
@@ -32,14 +43,12 @@ const TYPE_LIST = 'List' as const
 class List<T extends {}> {
 	#composite: Composite<Record<string, T>, State<T>>
 	#watchers = new Set<Watcher>()
-	#listeners: Pick<Listeners, 'sort'> = {
-		sort: new Set<Listener<'sort'>>(),
-	}
+	#hookCallbacks: HookCallbacks = {}
 	#order: string[] = []
 	#generateKey: (item: T) => string
 
 	constructor(initialValue: T[], keyConfig?: KeyConfig<T>) {
-		validateSignalValue('list', initialValue, Array.isArray)
+		validateSignalValue(TYPE_LIST, initialValue, Array.isArray)
 
 		let keyCounter = 0
 		this.#generateKey = isString(keyConfig)
@@ -51,7 +60,7 @@ class List<T extends {}> {
 		this.#composite = new Composite<ArrayToRecord<T[]>, State<T>>(
 			this.#toRecord(initialValue),
 			(key: string, value: unknown): value is T => {
-				validateSignalValue(`list for key "${key}"`, value)
+				validateSignalValue(`${TYPE_LIST} for key "${key}"`, value)
 				return true
 			},
 			value => new State(value),
@@ -87,7 +96,7 @@ class List<T extends {}> {
 		return TYPE_LIST
 	}
 
-	get [Symbol.isConcatSpreadable](): boolean {
+	get [Symbol.isConcatSpreadable](): true {
 		return true
 	}
 
@@ -99,12 +108,12 @@ class List<T extends {}> {
 	}
 
 	get length(): number {
-		subscribeActiveWatcher(this.#watchers)
+		subscribeActiveWatcher(this.#watchers, this.#hookCallbacks[HOOK_WATCH])
 		return this.#order.length
 	}
 
 	get(): T[] {
-		subscribeActiveWatcher(this.#watchers)
+		subscribeActiveWatcher(this.#watchers, this.#hookCallbacks[HOOK_WATCH])
 		return this.#value
 	}
 
@@ -198,7 +207,7 @@ class List<T extends {}> {
 		if (!isEqual(this.#order, newOrder)) {
 			this.#order = newOrder
 			notifyWatchers(this.#watchers)
-			emitNotification(this.#listeners.sort, this.#order)
+			triggerHook(this.#hookCallbacks.sort, this.#order)
 		}
 	}
 
@@ -258,32 +267,29 @@ class List<T extends {}> {
 		return Object.values(remove)
 	}
 
-	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup {
-		if (type === 'sort') {
-			this.#listeners.sort.add(listener as Listener<'sort'>)
-			return () =>
-				this.#listeners.sort.delete(listener as Listener<'sort'>)
+	on(type: Hook, callback: HookCallback): Cleanup {
+		if (isHandledHook(type, [HOOK_SORT, HOOK_WATCH])) {
+			this.#hookCallbacks[type] ||= new Set<HookCallback>()
+			this.#hookCallbacks[type].add(callback)
+			return () => {
+				this.#hookCallbacks[type]?.delete(callback)
+			}
+		} else if (isHandledHook(type, [HOOK_ADD, HOOK_CHANGE, HOOK_REMOVE])) {
+			return this.#composite.on(type, callback)
 		}
-
-		// For other types, delegate to the composite
-		return this.#composite.on(
-			type,
-			listener as Listener<
-				keyof Pick<Notifications, 'add' | 'remove' | 'change'>
-			>,
-		)
+		throw new InvalidHookError(TYPE_LIST, type)
 	}
 
 	deriveCollection<R extends {}>(
 		callback: (sourceValue: T) => R,
-	): Collection<R, T>
+	): DerivedCollection<R, T>
 	deriveCollection<R extends {}>(
 		callback: (sourceValue: T, abort: AbortSignal) => Promise<R>,
-	): Collection<R, T>
+	): DerivedCollection<R, T>
 	deriveCollection<R extends {}>(
 		callback: CollectionCallback<R, T>,
-	): Collection<R, T> {
-		return new Collection(this, callback)
+	): DerivedCollection<R, T> {
+		return new DerivedCollection(this, callback)
 	}
 }
 

package/src/classes/ref.ts

@@ -0,0 +1,96 @@
+import { type Guard, InvalidHookError, validateSignalValue } from '../errors'
+import {
+	type Cleanup,
+	HOOK_WATCH,
+	type HookCallback,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	type Watcher,
+	type WatchHook,
+} from '../system'
+import { isObjectOfType } from '../util'
+
+/* === Constants === */
+
+const TYPE_REF = 'Ref'
+
+/* === Class === */
+
+/**
+ * Create a new ref signal.
+ *
+ * @since 0.17.1
+ */
+class Ref<T extends {}> {
+	#watchers = new Set<Watcher>()
+	#value: T
+	#watchHookCallbacks: Set<HookCallback> | undefined
+
+	/**
+	 * Create a new ref signal.
+	 *
+	 * @param {T} value - Reference to external object
+	 * @param {Guard<T>} guard - Optional guard function to validate the value
+	 * @throws {NullishSignalValueError} - If the value is null or undefined
+	 * @throws {InvalidSignalValueError} - If the value is invalid
+	 */
+	constructor(value: T, guard?: Guard<T>) {
+		validateSignalValue(TYPE_REF, value, guard)
+
+		this.#value = value
+	}
+
+	get [Symbol.toStringTag](): string {
+		return TYPE_REF
+	}
+
+	/**
+	 * Get the value of the ref signal.
+	 *
+	 * @returns {T} - Object reference
+	 */
+	get(): T {
+		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
+
+		return this.#value
+	}
+
+	/**
+	 * Notify watchers of relevant changes in the external reference.
+	 */
+	notify(): void {
+		notifyWatchers(this.#watchers)
+	}
+
+	/**
+	 * Register a callback to be called when HOOK_WATCH is triggered.
+	 *
+	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
+	 * @param {HookCallback} callback - The callback to register
+	 * @returns {Cleanup} - A function to unregister the callback
+	 */
+	on(type: WatchHook, callback: HookCallback): Cleanup {
+		if (type === HOOK_WATCH) {
+			this.#watchHookCallbacks ||= new Set()
+			this.#watchHookCallbacks.add(callback)
+			return () => {
+				this.#watchHookCallbacks?.delete(callback)
+			}
+		}
+		throw new InvalidHookError(TYPE_REF, type)
+	}
+}
+
+/* === Functions === */
+
+/**
+ * Check if the provided value is a Ref instance
+ *
+ * @since 0.17.1
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a Ref instance, false otherwise
+ */
+const isRef = /*#__PURE__*/ <T extends {}>(value: unknown): value is Ref<T> =>
+	isObjectOfType(value, TYPE_REF)
+
+export { TYPE_REF, Ref, isRef }

package/src/classes/state.ts

@@ -1,7 +1,20 @@
 import { isEqual } from '../diff'
-import { validateCallback, validateSignalValue } from '../errors'
-import { notifyWatchers, subscribeActiveWatcher, type Watcher } from '../system'
-import { isObjectOfType, UNSET } from '../util'
+import {
+	InvalidHookError,
+	validateCallback,
+	validateSignalValue,
+} from '../errors'
+import {
+	type Cleanup,
+	HOOK_WATCH,
+	type HookCallback,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	UNSET,
+	type Watcher,
+	type WatchHook,
+} from '../system'
+import { isObjectOfType } from '../util'
 
 /* === Constants === */
 
@@ -17,6 +30,7 @@ const TYPE_STATE = 'State' as const
 class State<T extends {}> {
 	#watchers = new Set<Watcher>()
 	#value: T
+	#watchHookCallbacks: Set<HookCallback> | undefined
 
 	/**
 	 * Create a new state signal.
@@ -26,7 +40,7 @@ class State<T extends {}> {
 	 * @throws {InvalidSignalValueError} - If the initial value is invalid
 	 */
 	constructor(initialValue: T) {
-		validateSignalValue('state', initialValue)
+		validateSignalValue(TYPE_STATE, initialValue)
 
 		this.#value = initialValue
 	}
@@ -41,7 +55,8 @@ class State<T extends {}> {
 	 * @returns {T} - Current value of the state
 	 */
 	get(): T {
-		subscribeActiveWatcher(this.#watchers)
+		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
+
 		return this.#value
 	}
 
@@ -54,11 +69,11 @@ class State<T extends {}> {
 	 * @throws {InvalidSignalValueError} - If the initial value is invalid
 	 */
 	set(newValue: T): void {
-		validateSignalValue('state', newValue)
+		validateSignalValue(TYPE_STATE, newValue)
 
 		if (isEqual(this.#value, newValue)) return
 		this.#value = newValue
-		notifyWatchers(this.#watchers)
+		if (this.#watchers.size) notifyWatchers(this.#watchers)
 
 		// Setting to UNSET clears the watchers so the signal can be garbage collected
 		if (UNSET === this.#value) this.#watchers.clear()
@@ -74,10 +89,28 @@ class State<T extends {}> {
 	 * @throws {InvalidSignalValueError} - If the initial value is invalid
 	 */
 	update(updater: (oldValue: T) => T): void {
-		validateCallback('state update', updater)
+		validateCallback(`${TYPE_STATE} update`, updater)
 
 		this.set(updater(this.#value))
 	}
+
+	/**
+	 * Register a callback to be called when HOOK_WATCH is triggered.
+	 *
+	 * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
+	 * @param {HookCallback} callback - The callback to register
+	 * @returns {Cleanup} - A function to unregister the callback
+	 */
+	on(type: WatchHook, callback: HookCallback): Cleanup {
+		if (type === HOOK_WATCH) {
+			this.#watchHookCallbacks ||= new Set()
+			this.#watchHookCallbacks.add(callback)
+			return () => {
+				this.#watchHookCallbacks?.delete(callback)
+			}
+		}
+		throw new InvalidHookError(this.constructor.name, type)
+	}
 }
 
 /* === Functions === */

package/src/classes/store.ts

@@ -1,15 +1,25 @@
 import { diff, type UnknownRecord } from '../diff'
-import { DuplicateKeyError, validateSignalValue } from '../errors'
+import {
+	DuplicateKeyError,
+	InvalidHookError,
+	validateSignalValue,
+} from '../errors'
 import { createMutableSignal, type MutableSignal, type Signal } from '../signal'
 import {
 	type Cleanup,
-	type Listener,
-	type Listeners,
+	HOOK_ADD,
+	HOOK_CHANGE,
+	HOOK_REMOVE,
+	HOOK_WATCH,
+	type Hook,
+	type HookCallback,
+	isHandledHook,
 	notifyWatchers,
 	subscribeActiveWatcher,
+	UNSET,
 	type Watcher,
 } from '../system'
-import { isFunction, isObjectOfType, isRecord, isSymbol, UNSET } from '../util'
+import { isFunction, isObjectOfType, isRecord, isSymbol } from '../util'
 import { Composite } from './composite'
 import type { List } from './list'
 import type { State } from './state'
@@ -33,6 +43,7 @@ const TYPE_STORE = 'Store' as const
 class BaseStore<T extends UnknownRecord> {
 	#composite: Composite<T, Signal<T[keyof T] & {}>>
 	#watchers = new Set<Watcher>()
+	#watchHookCallbacks: Set<HookCallback> | undefined
 
 	/**
 	 * Create a new store with the given initial value.
@@ -42,7 +53,7 @@ class BaseStore<T extends UnknownRecord> {
 	 * @throws {InvalidSignalValueError} - If the initial value is not an object
 	 */
 	constructor(initialValue: T) {
-		validateSignalValue('store', initialValue, isRecord)
+		validateSignalValue(TYPE_STORE, initialValue, isRecord)
 
 		this.#composite = new Composite<T, Signal<T[keyof T] & {}>>(
 			initialValue,
@@ -50,7 +61,7 @@ class BaseStore<T extends UnknownRecord> {
 				key: K,
 				value: unknown,
 			): value is T[K] & {} => {
-				validateSignalValue(`store for key "${key}"`, value)
+				validateSignalValue(`${TYPE_STORE} for key "${key}"`, value)
 				return true
 			},
 			value => createMutableSignal(value),
@@ -80,24 +91,6 @@ class BaseStore<T extends UnknownRecord> {
 			yield [key, signal as MutableSignal<T[keyof T] & {}>]
 	}
 
-	get(): T {
-		subscribeActiveWatcher(this.#watchers)
-		return this.#value
-	}
-
-	set(newValue: T): void {
-		if (UNSET === newValue) {
-			this.#composite.clear()
-			notifyWatchers(this.#watchers)
-			this.#watchers.clear()
-			return
-		}
-
-		const oldValue = this.#value
-		const changed = this.#composite.change(diff(oldValue, newValue))
-		if (changed) notifyWatchers(this.#watchers)
-	}
-
 	keys(): IterableIterator<string> {
 		return this.#composite.signals.keys()
 	}
@@ -122,13 +115,31 @@ class BaseStore<T extends UnknownRecord> {
 					: State<T[K] & {}> | undefined
 	}
 
+	get(): T {
+		subscribeActiveWatcher(this.#watchers, this.#watchHookCallbacks)
+		return this.#value
+	}
+
+	set(newValue: T): void {
+		if (UNSET === newValue) {
+			this.#composite.clear()
+			notifyWatchers(this.#watchers)
+			this.#watchers.clear()
+			return
+		}
+
+		const oldValue = this.#value
+		const changed = this.#composite.change(diff(oldValue, newValue))
+		if (changed) notifyWatchers(this.#watchers)
+	}
+
 	update(fn: (oldValue: T) => T): void {
 		this.set(fn(this.get()))
 	}
 
 	add<K extends keyof T & string>(key: K, value: T[K]): K {
 		if (this.#composite.signals.has(key))
-			throw new DuplicateKeyError('store', key, value)
+			throw new DuplicateKeyError(TYPE_STORE, key, value)
 
 		const ok = this.#composite.add(key, value)
 		if (ok) notifyWatchers(this.#watchers)
@@ -140,11 +151,17 @@ class BaseStore<T extends UnknownRecord> {
 		if (ok) notifyWatchers(this.#watchers)
 	}
 
-	on<K extends keyof Omit<Listeners, 'sort'>>(
-		type: K,
-		listener: Listener<K>,
-	): Cleanup {
-		return this.#composite.on(type, listener)
+	on(type: Hook, callback: HookCallback): Cleanup {
+		if (type === HOOK_WATCH) {
+			this.#watchHookCallbacks ||= new Set<HookCallback>()
+			this.#watchHookCallbacks.add(callback)
+			return () => {
+				this.#watchHookCallbacks?.delete(callback)
+			}
+		} else if (isHandledHook(type, [HOOK_ADD, HOOK_CHANGE, HOOK_REMOVE])) {
+			return this.#composite.on(type, callback)
+		}
+		throw new InvalidHookError(TYPE_STORE, type)
 	}
 }