@zeix/cause-effect 0.17.2 → 0.18.0

package/src/classes/computed.ts

@@ -1,392 +0,0 @@
-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,
-} 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 | undefined
-	#watchHookCallbacks: Set<HookCallback> | undefined
-
-	/**
-	 * 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(this.constructor.name, callback, isMemoCallback)
-		validateSignalValue(this.constructor.name, initialValue)
-
-		this.#callback = callback
-		this.#value = initialValue
-	}
-
-	#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' {
-		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, this.#watchHookCallbacks)
-		flushPendingReactions()
-
-		if (this.#dirty) {
-			const watcher = this.#getWatcher()
-			trackSignalReads(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 = createError(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
-	}
-
-	/**
-	 * 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)
-	}
-}
-
-/**
- * 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 | undefined
-	#controller: AbortController | undefined
-	#watchHookCallbacks: Set<HookCallback> | 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(this.constructor.name, callback, isTaskCallback)
-		validateSignalValue(this.constructor.name, initialValue)
-
-		this.#callback = callback
-		this.#value = initialValue
-	}
-
-	#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' {
-		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, this.#watchHookCallbacks)
-		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 = createError(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))
-					this.#watcher?.stop()
-			}
-
-		const compute = () =>
-			trackSignalReads(this.#getWatcher(), () => {
-				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
-	}
-
-	/**
-	 * 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 === */
-
-/**
- * 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

@@ -1,310 +0,0 @@
-import { diff, isEqual, type UnknownArray } from '../diff'
-import {
-	DuplicateKeyError,
-	InvalidHookError,
-	validateSignalValue,
-} from '../errors'
-import {
-	type Cleanup,
-	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 } from '../util'
-import { type CollectionCallback, DerivedCollection } 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>()
-	#hookCallbacks: HookCallbacks = {}
-	#order: string[] = []
-	#generateKey: (item: T) => string
-
-	constructor(initialValue: T[], keyConfig?: KeyConfig<T>) {
-		validateSignalValue(TYPE_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(`${TYPE_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](): true {
-		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, this.#hookCallbacks[HOOK_WATCH])
-		return this.#order.length
-	}
-
-	get(): T[] {
-		subscribeActiveWatcher(this.#watchers, this.#hookCallbacks[HOOK_WATCH])
-		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)
-			triggerHook(this.#hookCallbacks.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(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)
-		}
-		throw new InvalidHookError(TYPE_LIST, type)
-	}
-
-	deriveCollection<R extends {}>(
-		callback: (sourceValue: T) => R,
-	): DerivedCollection<R, T>
-	deriveCollection<R extends {}>(
-		callback: (sourceValue: T, abort: AbortSignal) => Promise<R>,
-	): DerivedCollection<R, T>
-	deriveCollection<R extends {}>(
-		callback: CollectionCallback<R, T>,
-	): DerivedCollection<R, T> {
-		return new DerivedCollection(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 }