@zeix/cause-effect 0.17.0 → 0.17.2

package/src/diff.ts

@@ -1,5 +1,6 @@
 import { CircularDependencyError } from './errors'
-import { isNonNullObject, isRecord, isRecordOrArray, UNSET } from './util'
+import { UNSET } from './system'
+import { isNonNullObject, isRecord, isRecordOrArray } from './util'
 
 /* === Types === */
 

package/src/effect.ts

@@ -1,12 +1,15 @@
 import { CircularDependencyError, InvalidCallbackError } from './errors'
-import { type Cleanup, createWatcher, trackSignalReads } from './system'
+import {
+	type Cleanup,
+	createWatcher,
+	HOOK_CLEANUP,
+	type MaybeCleanup,
+	trackSignalReads,
+} from './system'
 import { isAbortError, isAsyncFunction, isFunction } from './util'
 
 /* === Types === */
 
-// biome-ignore lint/suspicious/noConfusingVoidType: optional Cleanup return type
-type MaybeCleanup = Cleanup | undefined | void
-
 type EffectCallback =
 	| (() => MaybeCleanup)
 	| ((abort: AbortSignal) => Promise<MaybeCleanup>)
@@ -55,19 +58,22 @@ const createEffect = (callback: EffectCallback): Cleanup => {
 								isFunction(cleanup) &&
 								controller === currentController
 							)
-								watcher.onCleanup(cleanup)
+								watcher.on(HOOK_CLEANUP, cleanup)
 						})
 						.catch(error => {
 							if (!isAbortError(error))
-								console.error('Async effect error:', error)
+								console.error(
+									'Error in async effect callback:',
+									error,
+								)
 						})
 				} else {
 					cleanup = callback()
-					if (isFunction(cleanup)) watcher.onCleanup(cleanup)
+					if (isFunction(cleanup)) watcher.on(HOOK_CLEANUP, cleanup)
 				}
 			} catch (error) {
 				if (!isAbortError(error))
-					console.error('Effect callback error:', error)
+					console.error('Error in effect callback:', error)
 			}
 
 			running = false
@@ -77,7 +83,11 @@ const createEffect = (callback: EffectCallback): Cleanup => {
 	watcher()
 	return () => {
 		controller?.abort()
-		watcher.stop()
+		try {
+			watcher.stop()
+		} catch (error) {
+			console.error('Error in effect cleanup:', error)
+		}
 	}
 }
 

package/src/errors.ts

@@ -1,5 +1,12 @@
 import { isMutableSignal, type MutableSignal } from './signal'
-import { isFunction, isSymbol, UNSET, valueString } from './util'
+import { UNSET } from './system'
+import { isFunction, isSymbol, valueString } from './util'
+
+/* === Types === */
+
+type Guard<T> = (value: unknown) => value is T
+
+/* === Classes === */
 
 class CircularDependencyError extends Error {
 	constructor(where: string) {
@@ -26,6 +33,20 @@ class InvalidCallbackError extends TypeError {
 	}
 }
 
+class InvalidCollectionSourceError extends TypeError {
+	constructor(where: string, value: unknown) {
+		super(`Invalid ${where} source ${valueString(value)}`)
+		this.name = 'InvalidCollectionSourceError'
+	}
+}
+
+class InvalidHookError extends TypeError {
+	constructor(where: string, type: string) {
+		super(`Invalid hook "${type}" in  ${where}`)
+		this.name = 'InvalidHookError'
+	}
+}
+
 class InvalidSignalValueError extends TypeError {
 	constructor(where: string, value: unknown) {
 		super(`Invalid signal value ${valueString(value)} in ${where}`)
@@ -49,6 +70,11 @@ class ReadonlySignalError extends Error {
 	}
 }
 
+/* === Functions === */
+
+const createError = /*#__PURE__*/ (reason: unknown): Error =>
+	reason instanceof Error ? reason : Error(String(reason))
+
 const validateCallback = (
 	where: string,
 	value: unknown,
@@ -77,12 +103,16 @@ const guardMutableSignal = <T extends {}>(
 }
 
 export {
+	type Guard,
 	CircularDependencyError,
 	DuplicateKeyError,
 	InvalidCallbackError,
+	InvalidCollectionSourceError,
+	InvalidHookError,
 	InvalidSignalValueError,
 	NullishSignalValueError,
 	ReadonlySignalError,
+	createError,
 	validateCallback,
 	validateSignalValue,
 	guardMutableSignal,

package/src/match.ts

@@ -1,6 +1,6 @@
+import { createError } from './errors'
 import type { ResolveResult } from './resolve'
 import type { SignalValues, UnknownSignalRecord } from './signal'
-import { toError } from './util'
 
 /* === Types === */
 
@@ -32,17 +32,10 @@ function match<S extends UnknownSignalRecord>(
 		if (result.pending) handlers.nil?.()
 		else if (result.errors) handlers.err?.(result.errors)
 		else if (result.ok) handlers.ok(result.values)
-	} catch (error) {
-		// If handler throws, try error handler, otherwise rethrow
-		if (
-			handlers.err &&
-			(!result.errors || !result.errors.includes(toError(error)))
-		)
-			handlers.err(
-				result.errors
-					? [...result.errors, toError(error)]
-					: [toError(error)],
-			)
+	} catch (e) {
+		const error = createError(e)
+		if (handlers.err && (!result.errors || !result.errors.includes(error)))
+			handlers.err(result.errors ? [...result.errors, error] : [error])
 		else throw error
 	}
 }

package/src/resolve.ts

@@ -1,6 +1,7 @@
 import type { UnknownRecord } from './diff'
+import { createError } from './errors'
 import type { SignalValues, UnknownSignalRecord } from './signal'
-import { toError, UNSET } from './util'
+import { UNSET } from './system'
 
 /* === Types === */
 
@@ -33,7 +34,7 @@ function resolve<S extends UnknownSignalRecord>(signals: S): ResolveResult<S> {
 			if (value === UNSET) pending = true
 			else values[key] = value
 		} catch (e) {
-			errors.push(toError(e))
+			errors.push(createError(e))
 		}
 	}
 

package/src/signal.ts

@@ -10,7 +10,6 @@ import { isList, List } from './classes/list'
 import { isState, State } from './classes/state'
 import { createStore, isStore, type Store } from './classes/store'
 import type { UnknownRecord } from './diff'
-// import type { Collection } from './signals/collection'
 import { isRecord, isUniformArray } from './util'
 
 /* === Types === */

package/src/system.ts

@@ -1,26 +1,27 @@
 /* === Types === */
 
+import { createError, InvalidHookError } from './errors'
+import { isFunction } from './util'
+
 type Cleanup = () => void
 
-type Watcher = {
-	(): void
-	onCleanup(cleanup: Cleanup): void
-	stop(): void
-}
+// biome-ignore lint/suspicious/noConfusingVoidType: optional Cleanup return type
+type MaybeCleanup = Cleanup | undefined | void
 
-type Notifications = {
-	add: readonly string[]
-	change: readonly string[]
-	remove: readonly string[]
-	sort: readonly string[]
-}
+type Hook = 'add' | 'change' | 'cleanup' | 'remove' | 'sort' | 'watch'
+type CleanupHook = 'cleanup'
+type WatchHook = 'watch'
 
-type Listener<K extends keyof Notifications> = (
-	payload: Notifications[K],
-) => void
+type HookCallback = (payload?: readonly string[]) => MaybeCleanup
 
-type Listeners = {
-	[K in keyof Notifications]: Set<Listener<K>>
+type HookCallbacks = {
+	[K in Hook]?: Set<HookCallback>
+}
+
+type Watcher = {
+	(): void
+	on(type: CleanupHook, cleanup: Cleanup): void
+	stop(): void
 }
 
 /* === Internal === */
@@ -28,14 +29,29 @@ type Listeners = {
 // Currently active watcher
 let activeWatcher: Watcher | undefined
 
+// Map of signal watchers to their cleanup functions
+const unwatchMap = new WeakMap<Set<Watcher>, Set<Cleanup>>()
+
 // Queue of pending watcher reactions for batched change notifications
 const pendingReactions = new Set<() => void>()
 let batchDepth = 0
 
+/* === Constants === */
+
+// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
+const UNSET: any = Symbol()
+
+const HOOK_ADD = 'add'
+const HOOK_CHANGE = 'change'
+const HOOK_CLEANUP = 'cleanup'
+const HOOK_REMOVE = 'remove'
+const HOOK_SORT = 'sort'
+const HOOK_WATCH = 'watch'
+
 /* === Functions === */
 
 /**
- * Create a watcher that can be used to observe changes to a signal
+ * Create a watcher to observe changes to a signal.
  *
  * A watcher is a reaction function with onCleanup and stop methods
  *
@@ -46,43 +62,86 @@ let batchDepth = 0
 const createWatcher = (react: () => void): Watcher => {
 	const cleanups = new Set<Cleanup>()
 	const watcher = react as Partial<Watcher>
-	watcher.onCleanup = (cleanup: Cleanup) => {
-		cleanups.add(cleanup)
+	watcher.on = (type: CleanupHook, cleanup: Cleanup) => {
+		if (type === HOOK_CLEANUP) cleanups.add(cleanup)
+		else throw new InvalidHookError('watcher', type)
 	}
 	watcher.stop = () => {
-		for (const cleanup of cleanups) cleanup()
-		cleanups.clear()
+		try {
+			for (const cleanup of cleanups) cleanup()
+		} finally {
+			cleanups.clear()
+		}
 	}
 	return watcher as Watcher
 }
 
 /**
- * Subscribe by adding active watcher to the Set of watchers of a signal
+ * Subscribe by adding active watcher to the Set of watchers of a signal.
  *
  * @param {Set<Watcher>} watchers - Watchers of the signal
+ * @param {Set<HookCallback>} watchHookCallbacks - HOOK_WATCH callbacks of the signal
  */
-const subscribeActiveWatcher = (watchers: Set<Watcher>) => {
+const subscribeActiveWatcher = (
+	watchers: Set<Watcher>,
+	watchHookCallbacks?: Set<HookCallback>,
+): void => {
+	// Check if we need to trigger HOOK_WATCH callbacks
+	if (!watchers.size && watchHookCallbacks?.size) {
+		const unwatch = triggerHook(watchHookCallbacks)
+		if (unwatch) {
+			const unwatchCallbacks =
+				unwatchMap.get(watchers) ?? new Set<Cleanup>()
+			unwatchCallbacks.add(unwatch)
+			if (!unwatchMap.has(watchers))
+				unwatchMap.set(watchers, unwatchCallbacks)
+		}
+	}
+
+	// Only if active watcher is not already subscribed
 	if (activeWatcher && !watchers.has(activeWatcher)) {
 		const watcher = activeWatcher
-		watcher.onCleanup(() => watchers.delete(watcher))
+
+		watcher.on(HOOK_CLEANUP, () => {
+			// Remove the watcher from the Set of watchers
+			watchers.delete(watcher)
+
+			// If it was the last watcher, call unwatch callbacks
+			if (!watchers.size) {
+				const unwatchCallbacks = unwatchMap.get(watchers)
+				if (unwatchCallbacks) {
+					try {
+						for (const unwatch of unwatchCallbacks) unwatch()
+					} finally {
+						unwatchCallbacks.clear()
+						unwatchMap.delete(watchers)
+					}
+				}
+			}
+		})
+
+		// Here the active watcher is added to the Set of watchers
 		watchers.add(watcher)
 	}
 }
 
 /**
- * Notify watchers of a signal change
+ * Notify watchers of a signal change.
  *
  * @param {Set<Watcher>} watchers - Watchers of the signal
+ * @returns {boolean} - Whether any watchers were notified
  */
-const notifyWatchers = (watchers: Set<Watcher>) => {
+const notifyWatchers = (watchers: Set<Watcher>): boolean => {
+	if (!watchers.size) return false
 	for (const react of watchers) {
 		if (batchDepth) pendingReactions.add(react)
 		else react()
 	}
+	return true
 }
 
 /**
- * Flush all pending reactions of enqueued watchers
+ * Flush all pending reactions of enqueued watchers.
  */
 const flushPendingReactions = () => {
 	while (pendingReactions.size) {
@@ -93,7 +152,7 @@ const flushPendingReactions = () => {
 }
 
 /**
- * Batch multiple signal writes
+ * Batch multiple signal writes.
  *
  * @param {() => void} callback - Function with multiple signal writes to be batched
  */
@@ -108,7 +167,7 @@ const batchSignalWrites = (callback: () => void) => {
 }
 
 /**
- * Run a function with signal reads in a tracking context (or temporarily untrack)
+ * Run a function with signal reads in a tracking context (or temporarily untrack).
  *
  * @param {Watcher | false} watcher - Watcher to be called when the signal changes
  *                                    or false for temporary untracking while inserting auto-hydrating DOM nodes
@@ -126,34 +185,91 @@ const trackSignalReads = (watcher: Watcher | false, run: () => void): void => {
 }
 
 /**
- * Emit a notification to listeners
+ * Trigger a hook.
  *
- * @param {Set<Listener>} listeners - Listeners to be notified
- * @param {Notifications[K]} payload - Payload to be sent to listeners
+ * @param {Set<HookCallback> | undefined} callbacks - Callbacks to be called when the hook is triggered
+ * @param {readonly string[] | undefined} payload - Payload to be sent to listeners
+ * @return {Cleanup | undefined} Cleanup function to be called when the hook is unmounted
  */
-const emitNotification = <T extends keyof Notifications>(
-	listeners: Set<Listener<T>>,
-	payload: Notifications[T],
-) => {
-	for (const listener of listeners) {
-		if (batchDepth) pendingReactions.add(() => listener(payload))
-		else listener(payload)
+const triggerHook = (
+	callbacks: Set<HookCallback> | undefined,
+	payload?: readonly string[],
+): Cleanup | undefined => {
+	if (!callbacks) return
+
+	const cleanups: Cleanup[] = []
+	const errors: Error[] = []
+
+	const throwError = (inCleanup?: boolean) => {
+		if (errors.length) {
+			if (errors.length === 1) throw errors[0]
+			throw new AggregateError(
+				errors,
+				`Errors in hook ${inCleanup ? 'cleanup' : 'callback'}:`,
+			)
+		}
+	}
+
+	for (const callback of callbacks) {
+		try {
+			const cleanup = callback(payload)
+			if (isFunction(cleanup)) cleanups.push(cleanup)
+		} catch (error) {
+			errors.push(createError(error))
+		}
+	}
+	throwError()
+
+	if (!cleanups.length) return
+	if (cleanups.length === 1) return cleanups[0]
+	return () => {
+		for (const cleanup of cleanups) {
+			try {
+				cleanup()
+			} catch (error) {
+				errors.push(createError(error))
+			}
+		}
+		throwError(true)
 	}
 }
 
+/**
+ * Check whether a hook type is handled in a signal.
+ *
+ * @param {Hook} type - Type of hook to check
+ * @param {T} handled - List of handled hook types
+ * @returns {type is T[number]} - Whether the hook type is handled
+ */
+const isHandledHook = <T extends readonly Hook[]>(
+	type: Hook,
+	handled: T,
+): type is T[number] => handled.includes(type)
+
 /* === Exports === */
 
 export {
 	type Cleanup,
+	type MaybeCleanup,
 	type Watcher,
-	type Notifications,
-	type Listener,
-	type Listeners,
+	type Hook,
+	type CleanupHook,
+	type WatchHook,
+	type HookCallback,
+	type HookCallbacks,
+	HOOK_ADD,
+	HOOK_CHANGE,
+	HOOK_CLEANUP,
+	HOOK_REMOVE,
+	HOOK_SORT,
+	HOOK_WATCH,
+	UNSET,
 	createWatcher,
 	subscribeActiveWatcher,
 	notifyWatchers,
 	flushPendingReactions,
 	batchSignalWrites,
 	trackSignalReads,
-	emitNotification,
+	triggerHook,
+	isHandledHook,
 }

package/src/util.ts

@@ -1,8 +1,3 @@
-/* === Constants === */
-
-// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
-const UNSET: any = Symbol()
-
 /* === Utility Functions === */
 
 const isString = /*#__PURE__*/ (value: unknown): value is string =>
@@ -63,9 +58,6 @@ const hasMethod = /*#__PURE__*/ <
 const isAbortError = /*#__PURE__*/ (error: unknown): boolean =>
 	error instanceof DOMException && error.name === 'AbortError'
 
-const toError = /*#__PURE__*/ (reason: unknown): Error =>
-	reason instanceof Error ? reason : Error(String(reason))
-
 const valueString = /*#__PURE__*/ (value: unknown): string =>
 	isString(value)
 		? `"${value}"`
@@ -76,7 +68,6 @@ const valueString = /*#__PURE__*/ (value: unknown): string =>
 /* === Exports === */
 
 export {
-	UNSET,
 	isString,
 	isNumber,
 	isSymbol,
@@ -90,6 +81,5 @@ export {
 	isUniformArray,
 	hasMethod,
 	isAbortError,
-	toError,
 	valueString,
 }