@zeix/cause-effect 0.17.3 → 0.18.0

package/src/classes/collection.ts

@@ -1,245 +0,0 @@
-import { InvalidCollectionSourceError, validateCallback } from '../errors'
-import type { Signal } from '../signal'
-import {
-	createWatcher,
-	notifyOf,
-	registerWatchCallbacks,
-	type SignalOptions,
-	subscribeTo,
-	UNSET,
-	type Watcher,
-} from '../system'
-import { isAsyncFunction, isFunction, isObjectOfType } from '../util'
-import { type Computed, createComputed } from './computed'
-import { isList, type List } from './list'
-
-/* === Types === */
-
-type CollectionSource<T extends {}> = List<T> | Collection<T>
-
-type CollectionCallback<T extends {}, U extends {}> =
-	| ((sourceValue: U) => T)
-	| ((sourceValue: U, abort: AbortSignal) => Promise<T>)
-
-type Collection<T extends {}> = {
-	readonly [Symbol.toStringTag]: 'Collection'
-	readonly [Symbol.isConcatSpreadable]: true
-	[Symbol.iterator](): IterableIterator<Signal<T>>
-	keys(): IterableIterator<string>
-	get: () => T[]
-	at: (index: number) => Signal<T> | undefined
-	byKey: (key: string) => Signal<T> | undefined
-	keyAt: (index: number) => string | undefined
-	indexOfKey: (key: string) => number | undefined
-	deriveCollection: <R extends {}>(
-		callback: CollectionCallback<R, T>,
-	) => DerivedCollection<R, T>
-	readonly length: number
-}
-
-/* === Constants === */
-
-const TYPE_COLLECTION = 'Collection' as const
-
-/* === Class === */
-
-class DerivedCollection<T extends {}, U extends {}> implements Collection<T> {
-	#source: CollectionSource<U>
-	#callback: CollectionCallback<T, U>
-	#signals = new Map<string, Computed<T>>()
-	#keys: string[] = []
-	#dirty = true
-	#watcher: Watcher | undefined
-
-	constructor(
-		source: CollectionSource<U> | (() => CollectionSource<U>),
-		callback: CollectionCallback<T, U>,
-		options?: SignalOptions<T[]>,
-	) {
-		validateCallback(TYPE_COLLECTION, callback)
-
-		if (isFunction(source)) source = source()
-		if (!isCollectionSource(source))
-			throw new InvalidCollectionSourceError(TYPE_COLLECTION, source)
-		this.#source = source
-
-		this.#callback = callback
-
-		for (let i = 0; i < this.#source.length; i++) {
-			const key = this.#source.keyAt(i)
-			if (!key) continue
-
-			this.#add(key)
-		}
-
-		if (options?.watched)
-			registerWatchCallbacks(this, options.watched, options.unwatched)
-	}
-
-	#getWatcher(): Watcher {
-		this.#watcher ||= createWatcher(
-			() => {
-				this.#dirty = true
-				if (!notifyOf(this)) this.#watcher?.stop()
-			},
-			() => {
-				const newKeys = Array.from(this.#source.keys())
-				const allKeys = new Set([...this.#keys, ...newKeys])
-				const addedKeys: string[] = []
-				const removedKeys: string[] = []
-
-				for (const key of allKeys) {
-					const oldHas = this.#keys.includes(key)
-					const newHas = newKeys.includes(key)
-
-					if (!oldHas && newHas) addedKeys.push(key)
-					else if (oldHas && !newHas) removedKeys.push(key)
-				}
-
-				for (const key of removedKeys) this.#signals.delete(key)
-				for (const key of addedKeys) this.#add(key)
-				this.#keys = newKeys
-				this.#dirty = false
-			},
-		)
-		this.#watcher.onCleanup(() => {
-			this.#watcher = undefined
-		})
-
-		return this.#watcher
-	}
-
-	#add(key: string): boolean {
-		const computedCallback = isAsyncCollectionCallback<T>(this.#callback)
-			? async (_: T, abort: AbortSignal) => {
-					const sourceValue = this.#source.byKey(key)?.get() as U
-					if (sourceValue === UNSET) return UNSET
-					return this.#callback(sourceValue, abort)
-				}
-			: () => {
-					const sourceValue = this.#source.byKey(key)?.get() as U
-					if (sourceValue === UNSET) return UNSET
-					return (this.#callback as (sourceValue: U) => T)(
-						sourceValue,
-					)
-				}
-
-		const signal = createComputed(computedCallback)
-
-		this.#signals.set(key, signal)
-		if (!this.#keys.includes(key)) this.#keys.push(key)
-		return true
-	}
-
-	get [Symbol.toStringTag](): 'Collection' {
-		return TYPE_COLLECTION
-	}
-
-	get [Symbol.isConcatSpreadable](): true {
-		return true
-	}
-
-	*[Symbol.iterator](): IterableIterator<Computed<T>> {
-		for (const key of this.#keys) {
-			const signal = this.#signals.get(key)
-			if (signal) yield signal as Computed<T>
-		}
-	}
-
-	keys(): IterableIterator<string> {
-		subscribeTo(this)
-		if (this.#dirty) this.#getWatcher().run()
-		return this.#keys.values()
-	}
-
-	get(): T[] {
-		subscribeTo(this)
-
-		if (this.#dirty) this.#getWatcher().run()
-		return this.#keys
-			.map(key => this.#signals.get(key)?.get())
-			.filter(v => v != null && v !== UNSET) as T[]
-	}
-
-	at(index: number): Computed<T> | undefined {
-		return this.#signals.get(this.#keys[index])
-	}
-
-	byKey(key: string): Computed<T> | undefined {
-		return this.#signals.get(key)
-	}
-
-	keyAt(index: number): string | undefined {
-		return this.#keys[index]
-	}
-
-	indexOfKey(key: string): number {
-		return this.#keys.indexOf(key)
-	}
-
-	deriveCollection<R extends {}>(
-		callback: (sourceValue: T) => R,
-		options?: SignalOptions<R[]>,
-	): DerivedCollection<R, T>
-	deriveCollection<R extends {}>(
-		callback: (sourceValue: T, abort: AbortSignal) => Promise<R>,
-		options?: SignalOptions<R[]>,
-	): DerivedCollection<R, T>
-	deriveCollection<R extends {}>(
-		callback: CollectionCallback<R, T>,
-		options?: SignalOptions<R[]>,
-	): DerivedCollection<R, T> {
-		return new DerivedCollection(this, callback, options)
-	}
-
-	get length(): number {
-		subscribeTo(this)
-		if (this.#dirty) this.#getWatcher().run()
-		return this.#keys.length
-	}
-}
-
-/* === Functions === */
-
-/**
- * Check if a value is a collection signal
- *
- * @since 0.17.2
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a collection signal, false otherwise
- */
-const isCollection = /*#__PURE__*/ <T extends {}>(
-	value: unknown,
-): value is Collection<T> => isObjectOfType(value, TYPE_COLLECTION)
-
-/**
- * Check if a value is a collection source
- *
- * @since 0.17.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a collection source, false otherwise
- */
-const isCollectionSource = /*#__PURE__*/ <T extends {}>(
-	value: unknown,
-): value is CollectionSource<T> => isList(value) || isCollection(value)
-
-/**
- * Check if the provided callback is an async function
- *
- * @since 0.17.0
- * @param {unknown} callback - Value to check
- * @returns {boolean} - True if value is an async collection callback, false otherwise
- */
-const isAsyncCollectionCallback = <T extends {}>(
-	callback: unknown,
-): callback is (sourceValue: unknown, abort: AbortSignal) => Promise<T> =>
-	isAsyncFunction(callback)
-
-export {
-	type Collection,
-	type CollectionSource,
-	type CollectionCallback,
-	DerivedCollection,
-	isCollection,
-	TYPE_COLLECTION,
-}

package/src/classes/computed.ts

@@ -1,349 +0,0 @@
-import { isEqual } from '../diff'
-import {
-	CircularDependencyError,
-	createError,
-	validateCallback,
-	validateSignalValue,
-} from '../errors'
-import {
-	createWatcher,
-	flush,
-	notifyOf,
-	registerWatchCallbacks,
-	type SignalOptions,
-	subscribeTo,
-	UNSET,
-	type Watcher,
-} from '../system'
-import {
-	isAbortError,
-	isAsyncFunction,
-	isObjectOfType,
-	isSyncFunction,
-} from '../util'
-
-/* === Types === */
-
-type Computed<T extends {}> = {
-	readonly [Symbol.toStringTag]: 'Computed'
-	get(): T
-}
-
-type ComputedOptions<T extends {}> = SignalOptions<T> & {
-	initialValue?: 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
- * @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
- */
-class Memo<T extends {}> {
-	#callback: MemoCallback<T>
-	#value: T
-	#error: Error | undefined
-	#dirty = true
-	#computing = false
-	#watcher: Watcher | undefined
-
-	constructor(callback: MemoCallback<T>, options?: ComputedOptions<T>) {
-		validateCallback(this.constructor.name, callback, isMemoCallback)
-		const initialValue = options?.initialValue ?? UNSET
-		validateSignalValue(this.constructor.name, initialValue, options?.guard)
-
-		this.#callback = callback
-		this.#value = initialValue
-		if (options?.watched)
-			registerWatchCallbacks(this, options.watched, options.unwatched)
-	}
-
-	#getWatcher(): Watcher {
-		// Own watcher: called by notifyWatchers() in upstream signals (push)
-		this.#watcher ||= createWatcher(
-			() => {
-				this.#dirty = true
-				if (!notifyOf(this)) this.#watcher?.stop()
-			},
-			() => {
-				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
-			},
-		)
-		this.#watcher.onCleanup(() => {
-			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 {
-		subscribeTo(this)
-		flush()
-
-		if (this.#dirty) this.#getWatcher().run()
-		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
- * @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
- */
-class Task<T extends {}> {
-	#callback: TaskCallback<T>
-	#value: T
-	#error: Error | undefined
-	#dirty = true
-	#computing = false
-	#changed = false
-	#watcher: Watcher | undefined
-	#controller: AbortController | undefined
-
-	constructor(callback: TaskCallback<T>, options?: ComputedOptions<T>) {
-		validateCallback(this.constructor.name, callback, isTaskCallback)
-		const initialValue = options?.initialValue ?? UNSET
-		validateSignalValue(this.constructor.name, initialValue, options?.guard)
-
-		this.#callback = callback
-		this.#value = initialValue
-		if (options?.watched)
-			registerWatchCallbacks(this, options.watched, options.unwatched)
-	}
-
-	#getWatcher(): Watcher {
-		if (!this.#watcher) {
-			// 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 && !notifyOf(this)) this.#watcher?.stop()
-				}
-
-			// Own watcher: called by notifyOf() in upstream signals (push)
-			this.#watcher = createWatcher(
-				() => {
-					this.#dirty = true
-					this.#controller?.abort()
-					if (!notifyOf(this)) this.#watcher?.stop()
-				},
-				() => {
-					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
-							this.#getWatcher().run()
-						},
-						{
-							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
-				},
-			)
-			this.#watcher.onCleanup(() => {
-				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 {
-		subscribeTo(this)
-		flush()
-
-		if (this.#dirty) this.#getWatcher().run()
-		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
- * @param {ComputedOptions<T>} options - Optional configuration
- */
-const createComputed = <T extends {}>(
-	callback: TaskCallback<T> | MemoCallback<T>,
-	options?: ComputedOptions<T>,
-) =>
-	isAsyncFunction(callback)
-		? new Task(callback as TaskCallback<T>, options)
-		: new Memo(callback as MemoCallback<T>, options)
-
-/**
- * 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 ComputedOptions,
-	type MemoCallback,
-	type TaskCallback,
-}