@zeix/cause-effect 0.17.1 → 0.17.2

package/src/errors.ts

@@ -1,5 +1,6 @@
 import { isMutableSignal, type MutableSignal } from './signal'
-import { isFunction, isSymbol, UNSET, valueString } from './util'
+import { UNSET } from './system'
+import { isFunction, isSymbol, valueString } from './util'
 
 /* === Types === */
 
@@ -39,6 +40,13 @@ class InvalidCollectionSourceError extends TypeError {
 	}
 }
 
+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}`)
@@ -100,6 +108,7 @@ export {
 	DuplicateKeyError,
 	InvalidCallbackError,
 	InvalidCollectionSourceError,
+	InvalidHookError,
 	InvalidSignalValueError,
 	NullishSignalValueError,
 	ReadonlySignalError,

package/src/resolve.ts

@@ -1,7 +1,7 @@
 import type { UnknownRecord } from './diff'
 import { createError } from './errors'
 import type { SignalValues, UnknownSignalRecord } from './signal'
-import { UNSET } from './util'
+import { UNSET } from './system'
 
 /* === Types === */
 

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 =>
@@ -73,7 +68,6 @@ const valueString = /*#__PURE__*/ (value: unknown): string =>
 /* === Exports === */
 
 export {
-	UNSET,
 	isString,
 	isNumber,
 	isSymbol,