@zeix/cause-effect 0.16.1 → 0.17.1

package/{src → archive}/state.ts

@@ -1,7 +1,11 @@
-import { isEqual } from './diff'
-import { InvalidCallbackError, NullishSignalValueError } from './errors'
-import { notify, subscribe, type Watcher } from './system'
-import { isFunction, isObjectOfType, UNSET, valueString } from './util'
+import { isEqual } from '../src/diff'
+import { InvalidCallbackError, NullishSignalValueError } from '../src/errors'
+import {
+	notifyWatchers,
+	subscribeActiveWatcher,
+	type Watcher,
+} from '../src/system'
+import { isFunction, isObjectOfType, UNSET } from '../src/util'
 
 /* === Types === */
 
@@ -14,7 +18,7 @@ type State<T extends {}> = {
 
 /* === Constants === */
 
-const TYPE_STATE = 'State'
+const TYPE_STATE = 'State' as const
 
 /* === Functions === */
 
@@ -35,7 +39,7 @@ const createState = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		if (newValue == null) throw new NullishSignalValueError('state')
 		if (isEqual(value, newValue)) return
 		value = newValue
-		notify(watchers)
+		notifyWatchers(watchers)
 
 		// Setting to UNSET clears the watchers so the signal can be garbage collected
 		if (UNSET === value) watchers.clear()
@@ -48,7 +52,7 @@ const createState = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		},
 		get: {
 			value: () => {
-				subscribe(watchers)
+				subscribeActiveWatcher(watchers)
 				return value
 			},
 		},
@@ -60,10 +64,8 @@ const createState = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		update: {
 			value: (updater: (oldValue: T) => T) => {
 				if (!isFunction(updater))
-					throw new InvalidCallbackError(
-						'state update',
-						valueString(updater),
-					)
+					throw new InvalidCallbackError('state update', updater)
+
 				setValue(updater(value))
 			},
 		},

package/archive/store.ts

@@ -0,0 +1,368 @@
+import { type DiffResult, diff, type UnknownRecord } from '../src/diff'
+import {
+	DuplicateKeyError,
+	InvalidSignalValueError,
+	NullishSignalValueError,
+	ReadonlySignalError,
+} from '../src/errors'
+import { isMutableSignal, type MutableSignal } from '../src/signal'
+import {
+	batchSignalWrites,
+	type Cleanup,
+	createWatcher,
+	emitNotification,
+	type Listener,
+	type Listeners,
+	type Notifications,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	trackSignalReads,
+	type Watcher,
+} from '../src/system'
+import {
+	isFunction,
+	isObjectOfType,
+	isRecord,
+	isSymbol,
+	UNSET,
+} from '../src/util'
+import { isComputed } from './computed'
+import { createList, isList, type List } from './list'
+import { createState, isState, type State } from './state'
+
+/* === Types === */
+
+type StoreKeySignal<T extends {}> = T extends readonly (infer U extends {})[]
+	? List<U>
+	: T extends UnknownRecord
+		? Store<T>
+		: State<T>
+
+type Store<T extends UnknownRecord> = {
+	[K in keyof T]: T[K] extends readonly (infer U extends {})[]
+		? List<U>
+		: T extends Record<string, unknown>
+			? Store<T[K] & {}>
+			: State<T[K] & {}>
+} & {
+	readonly [Symbol.toStringTag]: 'Store'
+	[Symbol.iterator](): IterableIterator<
+		[
+			Extract<keyof T, string>,
+			StoreKeySignal<T[Extract<keyof T, string>] & {}>,
+		]
+	>
+	add<K extends Extract<keyof T, string>>(key: K, value: T[K]): K
+	byKey<K extends Extract<keyof T, string>>(key: K): StoreKeySignal<T[K] & {}>
+	get(): T
+	keyAt(index: number): string | undefined
+	indexOfKey(key: string): number
+	set(value: T): void
+	update(fn: (value: T) => T): void
+	sort<U = T[Extract<keyof T, string>]>(
+		compareFn?: (a: U, b: U) => number,
+	): void
+	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup
+	remove<K extends Extract<keyof T, string>>(key: K): void
+}
+
+/* === Constants === */
+
+const TYPE_STORE = 'Store' as const
+
+/* === Functions === */
+
+/**
+ * Create a new store with deeply nested reactive properties
+ *
+ * Supports both objects and arrays as initial values. Arrays are converted
+ * to records internally for storage but maintain their array type through
+ * the .get() method, which automatically converts objects with consecutive
+ * numeric keys back to arrays.
+ *
+ * For array-like stores, an optional keyConfig parameter can be provided to
+ * generate stable keys for array items. This creates persistent references
+ * that remain stable across sort and compact operations.
+ *
+ * @since 0.15.0
+ * @param {T} initialValue - initial object or array value of the store
+ * @returns {Store<T>} - new store with reactive properties that preserves the original type T
+ */
+const createStore = <T extends UnknownRecord>(initialValue: T): Store<T> => {
+	if (initialValue == null) throw new NullishSignalValueError('store')
+
+	const watchers = new Set<Watcher>()
+	const listeners: Omit<Listeners, 'sort'> = {
+		add: new Set<Listener<'add'>>(),
+		change: new Set<Listener<'change'>>(),
+		remove: new Set<Listener<'remove'>>(),
+	}
+	const signals = new Map<
+		string,
+		MutableSignal<T[Extract<keyof T, string>] & {}>
+	>()
+	const ownWatchers = new Map<string, Watcher>()
+
+	// Get current record
+	const current = (): T => {
+		const record = {} as Record<string, unknown>
+		for (const [key, signal] of signals) record[key] = signal.get()
+		return record as T
+	}
+
+	// Validate input
+	const isValidValue = <T>(
+		key: string,
+		value: T,
+	): value is NonNullable<T> => {
+		if (value == null)
+			throw new NullishSignalValueError(`store for key "${key}"`)
+		if (value === UNSET) return true
+		if (isSymbol(value) || isFunction(value) || isComputed(value))
+			throw new InvalidSignalValueError(`store for key "${key}"`, value)
+		return true
+	}
+
+	// Add own watcher for nested signal
+	const addOwnWatcher = <K extends keyof T & string>(
+		key: K,
+		signal: MutableSignal<T[K] & {}>,
+	) => {
+		const watcher = createWatcher(() => {
+			trackSignalReads(watcher, () => {
+				signal.get() // Subscribe to the signal
+				emitNotification(listeners.change, [key])
+			})
+		})
+		ownWatchers.set(key, watcher)
+	}
+
+	// Add nested signal and effect
+	const addProperty = <K extends keyof T & string>(
+		key: K,
+		value: T[K],
+		single = false,
+	): boolean => {
+		if (!isValidValue(key, value)) return false
+
+		// Create signal for key
+		// @ts-expect-error non-matching signal types
+		const signal: MutableSignal<T[K] & {}> =
+			isState(value) || isStore(value) || isList(value)
+				? (value as unknown as MutableSignal<T[K] & {}>)
+				: isRecord(value)
+					? createStore(value)
+					: Array.isArray(value)
+						? createList(value)
+						: createState(value)
+
+		// Set internal states
+		// @ts-expect-error non-matching signal types
+		signals.set(key, signal)
+		if (listeners.change.size) addOwnWatcher(key, signal)
+
+		if (single) {
+			notifyWatchers(watchers)
+			emitNotification(listeners.add, [key])
+		}
+		return true
+	}
+
+	// Remove nested signal and effect
+	const removeProperty = (key: string, single = false) => {
+		// Remove signal for key
+		const ok = signals.delete(key)
+		if (!ok) return
+
+		// Clean up internal states
+		const watcher = ownWatchers.get(key)
+		if (watcher) {
+			watcher.stop()
+			ownWatchers.delete(key)
+		}
+
+		if (single) {
+			notifyWatchers(watchers)
+			emitNotification(listeners.remove, [key])
+		}
+	}
+
+	// Commit batched changes and emit notifications
+	const batchChanges = (changes: DiffResult, initialRun?: boolean) => {
+		// Additions
+		if (Object.keys(changes.add).length) {
+			for (const key in changes.add)
+				addProperty(
+					key,
+					changes.add[key] as T[Extract<keyof T, string>] & {},
+					false,
+				)
+
+			// Queue initial additions event to allow listeners to be added first
+			if (initialRun)
+				setTimeout(() => {
+					emitNotification(listeners.add, Object.keys(changes.add))
+				}, 0)
+			else emitNotification(listeners.add, Object.keys(changes.add))
+		}
+
+		// Changes
+		if (Object.keys(changes.change).length) {
+			batchSignalWrites(() => {
+				for (const key in changes.change) {
+					const value = changes.change[key] as T[Extract<
+						keyof T,
+						string
+					>]
+					if (!isValidValue(key, value)) continue
+
+					const signal = signals.get(key)
+					if (isMutableSignal(signal)) signal.set(value)
+					else throw new ReadonlySignalError(key, value)
+				}
+				emitNotification(listeners.change, Object.keys(changes.change))
+			})
+		}
+
+		// Removals
+		if (Object.keys(changes.remove).length) {
+			for (const key in changes.remove) removeProperty(key)
+			emitNotification(listeners.remove, Object.keys(changes.remove))
+		}
+
+		return changes.changed
+	}
+
+	// Reconcile data and dispatch events
+	const reconcile = (
+		oldValue: T,
+		newValue: T,
+		initialRun?: boolean,
+	): boolean => batchChanges(diff(oldValue, newValue), initialRun)
+
+	// Initialize data
+	reconcile({} as T, initialValue, true)
+
+	// Methods and Properties
+	const prototype: Record<PropertyKey, unknown> = {}
+	Object.defineProperties(prototype, {
+		[Symbol.toStringTag]: {
+			value: TYPE_STORE,
+		},
+		[Symbol.iterator]: {
+			value: function* () {
+				for (const [key, signal] of signals) yield [key, signal]
+			},
+		},
+		add: {
+			value: <K extends Extract<keyof T, string>>(
+				key: K,
+				value: T[K],
+			): K => {
+				if (signals.has(key))
+					throw new DuplicateKeyError('store', key, value)
+
+				addProperty(key, value, true)
+				return key
+			},
+		},
+		byKey: {
+			value: (key: string) => {
+				return signals.get(key)
+			},
+		},
+		get: {
+			value: (): T => {
+				subscribeActiveWatcher(watchers)
+				return current()
+			},
+		},
+		remove: {
+			value: (key: string): void => {
+				if (signals.has(key)) removeProperty(key, true)
+			},
+		},
+		set: {
+			value: (newValue: T): void => {
+				if (reconcile(current(), newValue)) {
+					notifyWatchers(watchers)
+					if (UNSET === newValue) watchers.clear()
+				}
+			},
+		},
+		update: {
+			value: (fn: (oldValue: T) => T): void => {
+				store.set(fn(current()))
+			},
+		},
+		on: {
+			value: <K extends keyof Omit<Listeners, 'sort'>>(
+				type: K,
+				listener: Listener<K>,
+			): Cleanup => {
+				listeners[type].add(listener)
+				if (type === 'change' && !ownWatchers.size) {
+					for (const [key, signal] of signals)
+						// @ts-expect-error ignore
+						addOwnWatcher(key, signal)
+				}
+				return () => {
+					listeners[type].delete(listener)
+					if (type === 'change' && !listeners.change.size) {
+						if (ownWatchers.size) {
+							for (const watcher of ownWatchers.values())
+								watcher.stop()
+							ownWatchers.clear()
+						}
+					}
+				}
+			},
+		},
+	})
+
+	// Return proxy directly with integrated signal methods
+	const store = new Proxy(prototype as Store<T>, {
+		get(target, prop) {
+			if (prop in target) return Reflect.get(target, prop)
+			if (!isSymbol(prop)) return signals.get(prop)
+		},
+		has(target, prop) {
+			if (prop in target) return true
+			return signals.has(String(prop))
+		},
+		ownKeys(target) {
+			const staticKeys = Reflect.ownKeys(target)
+			return [...new Set([...signals.keys(), ...staticKeys])]
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop in target)
+				return Reflect.getOwnPropertyDescriptor(target, prop)
+			if (isSymbol(prop)) return undefined
+
+			const signal = signals.get(prop)
+			return signal
+				? {
+						enumerable: true,
+						configurable: true,
+						writable: true,
+						value: signal,
+					}
+				: undefined
+		},
+	})
+	return store
+}
+
+/**
+ * Check if the provided value is a Store instance
+ *
+ * @since 0.15.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a Store instance, false otherwise
+ */
+const isStore = <T extends UnknownRecord>(value: unknown): value is Store<T> =>
+	isObjectOfType(value, TYPE_STORE)
+
+/* === Exports === */
+
+export { TYPE_STORE, isStore, createStore, type Store }

package/archive/task.ts

@@ -0,0 +1,194 @@
+import { isEqual } from '../src/diff'
+import {
+	CircularDependencyError,
+	createError,
+	InvalidCallbackError,
+	NullishSignalValueError,
+} from '../src/errors'
+import {
+	createWatcher,
+	flushPendingReactions,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	trackSignalReads,
+	type Watcher,
+} from '../src/system'
+import {
+	isAbortError,
+	isAsyncFunction,
+	isObjectOfType,
+	UNSET,
+} from '../src/util'
+
+/* === Types === */
+
+type Task<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Task'
+	get(): T
+}
+
+type TaskCallback<T extends {} & { then?: undefined }> = (
+	oldValue: T,
+	abort: AbortSignal,
+) => Promise<T>
+
+/* === Constants === */
+
+const TYPE_TASK = 'Task' as const
+
+/* === Functions === */
+
+/**
+ * Create a derived signal from existing signals
+ *
+ * @since 0.9.0
+ * @param {TaskCallback<T>} callback - Computation callback function
+ * @returns {Task<T>} - Computed signal
+ */
+const createTask = <T extends {}>(
+	callback: TaskCallback<T>,
+	initialValue: T = UNSET,
+): Task<T> => {
+	if (!isTaskCallback(callback))
+		throw new InvalidCallbackError('task', callback)
+	if (initialValue == null) throw new NullishSignalValueError('task')
+
+	const watchers: Set<Watcher> = new Set()
+
+	// Internal state
+	let value: T = initialValue
+	let error: Error | undefined
+	let controller: AbortController | undefined
+	let dirty = true
+	let changed = false
+	let computing = false
+
+	// Functions to update internal state
+	const ok = (v: T): undefined => {
+		if (!isEqual(v, value)) {
+			value = v
+			changed = true
+		}
+		error = undefined
+		dirty = false
+	}
+	const nil = (): undefined => {
+		changed = UNSET !== value
+		value = UNSET
+		error = undefined
+	}
+	const err = (e: unknown): undefined => {
+		const newError = createError(e)
+		changed =
+			!error ||
+			newError.name !== error.name ||
+			newError.message !== error.message
+		value = UNSET
+		error = newError
+	}
+	const settle =
+		<T>(fn: (arg: T) => void) =>
+		(arg: T) => {
+			computing = false
+			controller = undefined
+			fn(arg)
+			if (changed) notifyWatchers(watchers)
+		}
+
+	// Own watcher: called when notified from sources (push)
+	const watcher = createWatcher(() => {
+		dirty = true
+		controller?.abort()
+		if (watchers.size) notifyWatchers(watchers)
+		else watcher.stop()
+	})
+	watcher.onCleanup(() => {
+		controller?.abort()
+	})
+
+	// Called when requested by dependencies (pull)
+	const compute = () =>
+		trackSignalReads(watcher, () => {
+			if (computing) throw new CircularDependencyError('computed')
+			changed = false
+			// Return current value until promise resolves
+			if (controller) return value
+
+			controller = new AbortController()
+			controller.signal.addEventListener(
+				'abort',
+				() => {
+					computing = false
+					controller = undefined
+					compute() // Retry computation with updated state
+				},
+				{
+					once: true,
+				},
+			)
+			let result: T | Promise<T>
+			computing = true
+			try {
+				result = callback(value, controller.signal)
+			} catch (e) {
+				if (isAbortError(e)) nil()
+				else err(e)
+				computing = false
+				return
+			}
+
+			if (result instanceof Promise) result.then(settle(ok), settle(err))
+			else if (null == result || UNSET === result) nil()
+			else ok(result)
+			computing = false
+		})
+
+	const task: Record<PropertyKey, unknown> = {}
+	Object.defineProperties(task, {
+		[Symbol.toStringTag]: {
+			value: TYPE_TASK,
+		},
+		get: {
+			value: (): T => {
+				subscribeActiveWatcher(watchers)
+				flushPendingReactions()
+				if (dirty) compute()
+				if (error) throw error
+				return value
+			},
+		},
+	})
+	return task as Task<T>
+}
+
+/**
+ * Check if a value is a task signal
+ *
+ * @since 0.9.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if value is a task signal, false otherwise
+ */
+const isTask = /*#__PURE__*/ <T extends {}>(value: unknown): value is Task<T> =>
+	isObjectOfType(value, TYPE_TASK)
+
+/**
+ * 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 an async callback, false otherwise
+ */
+const isTaskCallback = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is TaskCallback<T> => isAsyncFunction(value) && value.length < 3
+
+/* === Exports === */
+
+export {
+	TYPE_TASK,
+	createTask,
+	isTask,
+	isTaskCallback,
+	type Task,
+	type TaskCallback,
+}

package/eslint.config.js

@@ -18,6 +18,7 @@ export default [
 			// we know what we're doing ;-)
 			'@typescript-eslint/no-empty-object-type': 'off',
 			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/no-this-alias': 'off',
 			'@typescript-eslint/no-unused-vars': [
 				'error',
 				{