@zeix/cause-effect 0.16.0 → 0.17.0

package/src/classes/computed.ts

@@ -0,0 +1,333 @@
+import { isEqual } from '../diff'
+import {
+	CircularDependencyError,
+	validateCallback,
+	validateSignalValue,
+} from '../errors'
+import {
+	createWatcher,
+	flushPendingReactions,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	trackSignalReads,
+	type Watcher,
+} from '../system'
+import {
+	isAbortError,
+	isAsyncFunction,
+	isObjectOfType,
+	isSyncFunction,
+	toError,
+	UNSET,
+} from '../util'
+
+/* === Types === */
+
+type Computed<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Computed'
+	get(): T
+}
+
+type MemoCallback<T extends {} & { then?: undefined }> = (oldValue: T) => T
+
+type TaskCallback<T extends {} & { then?: undefined }> = (
+	oldValue: T,
+	abort: AbortSignal,
+) => Promise<T>
+
+/* === Constants === */
+
+const TYPE_COMPUTED = 'Computed' as const
+
+/* === Classes === */
+
+/**
+ * Create a new memoized signal for a synchronous function.
+ *
+ * @since 0.17.0
+ */
+class Memo<T extends {}> {
+	#watchers: Set<Watcher> = new Set()
+	#callback: MemoCallback<T>
+	#value: T
+	#error: Error | undefined
+	#dirty = true
+	#computing = false
+	#watcher: Watcher
+
+	/**
+	 * 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)
+
+		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
+	}
+
+	/**
+	 * 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, () => {
+				if (this.#computing) throw new CircularDependencyError('memo')
+
+				let result: T
+				this.#computing = true
+				try {
+					result = this.#callback(this.#value)
+				} catch (e) {
+					// Err track
+					this.#value = UNSET
+					this.#error = toError(e)
+					this.#computing = false
+					return
+				}
+
+				if (null == result || UNSET === result) {
+					// Nil track
+					this.#value = UNSET
+					this.#error = undefined
+				} else {
+					// Ok track
+					this.#value = result
+					this.#error = undefined
+					this.#dirty = false
+				}
+				this.#computing = false
+			})
+		}
+
+		if (this.#error) throw this.#error
+		return this.#value
+	}
+}
+
+/**
+ * Create a new task signals that memoizes the result of an asynchronous function.
+ *
+ * @since 0.17.0
+ */
+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
+	#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)
+
+		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()
+		})
+	}
+
+	get [Symbol.toStringTag](): 'Computed' {
+		return TYPE_COMPUTED
+	}
+
+	/**
+	 * Return the memoized value after executing the async function 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()
+
+		// 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 = toError(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()
+
+		if (this.#error) throw this.#error
+		return this.#value
+	}
+}
+
+/* === Functions === */
+
+/**
+ * Create a derived signal from existing signals
+ *
+ * @since 0.9.0
+ * @param {MemoCallback<T> | TaskCallback<T>} callback - Computation callback function
+ */
+const createComputed = <T extends {}>(
+	callback: TaskCallback<T> | MemoCallback<T>,
+	initialValue: T = UNSET,
+) =>
+	isAsyncFunction(callback)
+		? new Task(callback as TaskCallback<T>, initialValue)
+		: new Memo(callback as MemoCallback<T>, initialValue)
+
+/**
+ * Check if a value is a computed signal
+ *
+ * @since 0.9.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if value is a computed signal, false otherwise
+ */
+const isComputed = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is Memo<T> => isObjectOfType(value, TYPE_COMPUTED)
+
+/**
+ * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
+ *
+ * @since 0.12.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if value is a sync callback, false otherwise
+ */
+const isMemoCallback = /*#__PURE__*/ <T extends {} & { then?: undefined }>(
+	value: unknown,
+): value is MemoCallback<T> => isSyncFunction(value) && value.length < 2
+
+/**
+ * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
+ *
+ * @since 0.17.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_COMPUTED,
+	createComputed,
+	isComputed,
+	isMemoCallback,
+	isTaskCallback,
+	Memo,
+	Task,
+	type Computed,
+	type MemoCallback,
+	type TaskCallback,
+}

package/src/classes/list.ts

@@ -0,0 +1,304 @@
+import { diff, isEqual, type UnknownArray } from '../diff'
+import { DuplicateKeyError, validateSignalValue } from '../errors'
+import {
+	type Cleanup,
+	emitNotification,
+	type Listener,
+	type Listeners,
+	type Notifications,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	type Watcher,
+} from '../system'
+import { isFunction, isNumber, isObjectOfType, isString, UNSET } from '../util'
+import { Collection, type CollectionCallback } from './collection'
+import { Composite } from './composite'
+import { State } from './state'
+
+/* === Types === */
+
+type ArrayToRecord<T extends UnknownArray> = {
+	[key: string]: T extends Array<infer U extends {}> ? U : never
+}
+
+type KeyConfig<T> = string | ((item: T) => string)
+
+/* === Constants === */
+
+const TYPE_LIST = 'List' as const
+
+/* === Class === */
+
+class List<T extends {}> {
+	#composite: Composite<Record<string, T>, State<T>>
+	#watchers = new Set<Watcher>()
+	#listeners: Pick<Listeners, 'sort'> = {
+		sort: new Set<Listener<'sort'>>(),
+	}
+	#order: string[] = []
+	#generateKey: (item: T) => string
+
+	constructor(initialValue: T[], keyConfig?: KeyConfig<T>) {
+		validateSignalValue('list', initialValue, Array.isArray)
+
+		let keyCounter = 0
+		this.#generateKey = isString(keyConfig)
+			? () => `${keyConfig}${keyCounter++}`
+			: isFunction<string>(keyConfig)
+				? (item: T) => keyConfig(item)
+				: () => String(keyCounter++)
+
+		this.#composite = new Composite<ArrayToRecord<T[]>, State<T>>(
+			this.#toRecord(initialValue),
+			(key: string, value: unknown): value is T => {
+				validateSignalValue(`list for key "${key}"`, value)
+				return true
+			},
+			value => new State(value),
+		)
+	}
+
+	// Convert array to record with stable keys
+	#toRecord(array: T[]): ArrayToRecord<T[]> {
+		const record = {} as Record<string, T>
+
+		for (let i = 0; i < array.length; i++) {
+			const value = array[i]
+			if (value === undefined) continue // Skip sparse array positions
+
+			let key = this.#order[i]
+			if (!key) {
+				key = this.#generateKey(value)
+				this.#order[i] = key
+			}
+			record[key] = value
+		}
+		return record
+	}
+
+	get #value(): T[] {
+		return this.#order
+			.map(key => this.#composite.signals.get(key)?.get())
+			.filter(v => v !== undefined) as T[]
+	}
+
+	// Public methods
+	get [Symbol.toStringTag](): 'List' {
+		return TYPE_LIST
+	}
+
+	get [Symbol.isConcatSpreadable](): boolean {
+		return true
+	}
+
+	*[Symbol.iterator](): IterableIterator<State<T>> {
+		for (const key of this.#order) {
+			const signal = this.#composite.signals.get(key)
+			if (signal) yield signal as State<T>
+		}
+	}
+
+	get length(): number {
+		subscribeActiveWatcher(this.#watchers)
+		return this.#order.length
+	}
+
+	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 changes = diff(this.#toRecord(oldValue), this.#toRecord(newValue))
+		const removedKeys = Object.keys(changes.remove)
+
+		const changed = this.#composite.change(changes)
+		if (changed) {
+			for (const key of removedKeys) {
+				const index = this.#order.indexOf(key)
+				if (index !== -1) this.#order.splice(index, 1)
+			}
+			this.#order = this.#order.filter(() => true)
+			notifyWatchers(this.#watchers)
+		}
+	}
+
+	update(fn: (oldValue: T[]) => T[]): void {
+		this.set(fn(this.get()))
+	}
+
+	at(index: number): State<T> | undefined {
+		return this.#composite.signals.get(this.#order[index])
+	}
+
+	keys(): IterableIterator<string> {
+		return this.#order.values()
+	}
+
+	byKey(key: string): State<T> | undefined {
+		return this.#composite.signals.get(key)
+	}
+
+	keyAt(index: number): string | undefined {
+		return this.#order[index]
+	}
+
+	indexOfKey(key: string): number {
+		return this.#order.indexOf(key)
+	}
+
+	add(value: T): string {
+		const key = this.#generateKey(value)
+		if (this.#composite.signals.has(key))
+			throw new DuplicateKeyError('store', key, value)
+
+		if (!this.#order.includes(key)) this.#order.push(key)
+		const ok = this.#composite.add(key, value)
+		if (ok) notifyWatchers(this.#watchers)
+		return key
+	}
+
+	remove(keyOrIndex: string | number): void {
+		const key = isNumber(keyOrIndex) ? this.#order[keyOrIndex] : keyOrIndex
+		const ok = this.#composite.remove(key)
+		if (ok) {
+			const index = isNumber(keyOrIndex)
+				? keyOrIndex
+				: this.#order.indexOf(key)
+			if (index >= 0) this.#order.splice(index, 1)
+			this.#order = this.#order.filter(() => true)
+			notifyWatchers(this.#watchers)
+		}
+	}
+
+	sort(compareFn?: (a: T, b: T) => number): void {
+		const entries = this.#order
+			.map(
+				key =>
+					[key, this.#composite.signals.get(key)?.get()] as [
+						string,
+						T,
+					],
+			)
+			.sort(
+				isFunction(compareFn)
+					? (a, b) => compareFn(a[1], b[1])
+					: (a, b) => String(a[1]).localeCompare(String(b[1])),
+			)
+		const newOrder = entries.map(([key]) => key)
+
+		if (!isEqual(this.#order, newOrder)) {
+			this.#order = newOrder
+			notifyWatchers(this.#watchers)
+			emitNotification(this.#listeners.sort, this.#order)
+		}
+	}
+
+	splice(start: number, deleteCount?: number, ...items: T[]): T[] {
+		const length = this.#order.length
+		const actualStart =
+			start < 0 ? Math.max(0, length + start) : Math.min(start, length)
+		const actualDeleteCount = Math.max(
+			0,
+			Math.min(
+				deleteCount ?? Math.max(0, length - Math.max(0, actualStart)),
+				length - actualStart,
+			),
+		)
+
+		const add = {} as Record<string, T>
+		const remove = {} as Record<string, T>
+
+		// Collect items to delete and their keys
+		for (let i = 0; i < actualDeleteCount; i++) {
+			const index = actualStart + i
+			const key = this.#order[index]
+			if (key) {
+				const signal = this.#composite.signals.get(key)
+				if (signal) remove[key] = signal.get() as T
+			}
+		}
+
+		// Build new order: items before splice point
+		const newOrder = this.#order.slice(0, actualStart)
+
+		// Add new items
+		for (const item of items) {
+			const key = this.#generateKey(item)
+			newOrder.push(key)
+			add[key] = item as T
+		}
+
+		// Add items after splice point
+		newOrder.push(...this.#order.slice(actualStart + actualDeleteCount))
+
+		const changed = !!(
+			Object.keys(add).length || Object.keys(remove).length
+		)
+
+		if (changed) {
+			this.#composite.change({
+				add,
+				change: {} as Record<string, T>,
+				remove,
+				changed,
+			})
+			this.#order = newOrder.filter(() => true) // Update order array
+			notifyWatchers(this.#watchers)
+		}
+
+		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'>)
+		}
+
+		// For other types, delegate to the composite
+		return this.#composite.on(
+			type,
+			listener as Listener<
+				keyof Pick<Notifications, 'add' | 'remove' | 'change'>
+			>,
+		)
+	}
+
+	deriveCollection<R extends {}>(
+		callback: (sourceValue: T) => R,
+	): Collection<R, T>
+	deriveCollection<R extends {}>(
+		callback: (sourceValue: T, abort: AbortSignal) => Promise<R>,
+	): Collection<R, T>
+	deriveCollection<R extends {}>(
+		callback: CollectionCallback<R, T>,
+	): Collection<R, T> {
+		return new Collection(this, callback)
+	}
+}
+
+/* === Functions === */
+
+/**
+ * Check if the provided value is a List instance
+ *
+ * @since 0.15.0
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a List instance, false otherwise
+ */
+const isList = <T extends {}>(value: unknown): value is List<T> =>
+	isObjectOfType(value, TYPE_LIST)
+
+/* === Exports === */
+
+export { isList, List, TYPE_LIST, type ArrayToRecord, type KeyConfig }