@zeix/cause-effect 0.16.1 → 0.17.0

package/archive/collection.ts

@@ -0,0 +1,312 @@
+import type { UnknownArray } from '../src/diff'
+import { match } from '../src/match'
+import { resolve } from '../src/resolve'
+import type { Signal } from '../src/signal'
+import {
+	type Cleanup,
+	createWatcher,
+	emitNotification,
+	type Listener,
+	type Listeners,
+	type Notifications,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	trackSignalReads,
+	type Watcher,
+} from '../src/system'
+import { isAsyncFunction, isObjectOfType, isSymbol, UNSET } from '../src/util'
+import { type Computed, createComputed } from './computed'
+import type { List } from './list'
+
+/* === Types === */
+
+type CollectionKeySignal<T extends {}> = T extends UnknownArray
+	? Collection<T>
+	: Computed<T>
+
+type CollectionCallback<T extends {} & { then?: undefined }, O extends {}> =
+	| ((originValue: O, abort: AbortSignal) => Promise<T>)
+	| ((originValue: O) => T)
+
+type Collection<T extends {}> = {
+	readonly [Symbol.toStringTag]: typeof TYPE_COLLECTION
+	readonly [Symbol.isConcatSpreadable]: boolean
+	[Symbol.iterator](): IterableIterator<CollectionKeySignal<T>>
+	readonly [n: number]: CollectionKeySignal<T>
+	readonly length: number
+
+	byKey(key: string): CollectionKeySignal<T> | undefined
+	get(): T[]
+	keyAt(index: number): string | undefined
+	indexOfKey(key: string): number
+	on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup
+	sort(compareFn?: (a: T, b: T) => number): void
+}
+
+/* === Constants === */
+
+const TYPE_COLLECTION = 'Collection' as const
+
+/* === Exported Functions === */
+
+/**
+ * Collections - Read-Only Derived Array-Like Stores
+ *
+ * Collections are the read-only, derived counterpart to array-like Stores.
+ * They provide reactive, memoized, and lazily-evaluated array transformations
+ * while maintaining the familiar array-like store interface.
+ *
+ * @since 0.16.2
+ * @param {List<O> | Collection<O>} origin - Origin of collection to derive values from
+ * @param {ComputedCallback<ArrayItem<T>>} callback - Callback function to transform array items
+ * @returns {Collection<T>} - New collection with reactive properties that preserves the original type T
+ */
+const createCollection = <T extends {}, O extends {}>(
+	origin: List<O> | Collection<O>,
+	callback: CollectionCallback<T, O>,
+): Collection<T> => {
+	const watchers = new Set<Watcher>()
+	const listeners: Listeners = {
+		add: new Set<Listener<'add'>>(),
+		change: new Set<Listener<'change'>>(),
+		remove: new Set<Listener<'remove'>>(),
+		sort: new Set<Listener<'sort'>>(),
+	}
+	const signals = new Map<string, Signal<T>>()
+	const signalWatchers = new Map<string, Watcher>()
+
+	let order: string[] = []
+
+	// Add nested signal and effect
+	const addProperty = (key: string): boolean => {
+		const computedCallback = isAsyncFunction(callback)
+			? async (_: T, abort: AbortSignal) => {
+					const originSignal = origin.byKey(key)
+					if (!originSignal) return UNSET
+
+					let result = UNSET
+					match(resolve({ originSignal }), {
+						ok: async ({ originSignal: originValue }) => {
+							result = await callback(originValue, abort)
+						},
+						err: (errors: readonly Error[]) => {
+							console.log(errors)
+						},
+					})
+					return result
+				}
+			: () => {
+					const originSignal = origin.byKey(key)
+					if (!originSignal) return UNSET
+
+					let result = UNSET
+					match(resolve({ originSignal }), {
+						ok: ({ originSignal: originValue }) => {
+							result = (callback as (originValue: O) => T)(
+								originValue as unknown as O,
+							)
+						},
+						err: (errors: readonly Error[]) => {
+							console.log(errors)
+						},
+					})
+					return result
+				}
+
+		const signal = createComputed(computedCallback)
+
+		// Set internal states
+		signals.set(key, signal)
+		if (!order.includes(key)) order.push(key)
+		const watcher = createWatcher(() =>
+			trackSignalReads(watcher, () => {
+				signal.get() // Subscribe to the signal
+				emitNotification(listeners.change, [key])
+			}),
+		)
+		watcher()
+		signalWatchers.set(key, watcher)
+		return true
+	}
+
+	// Remove nested signal and effect
+	const removeProperty = (key: string) => {
+		// Remove signal for key
+		const ok = signals.delete(key)
+		if (!ok) return
+
+		// Clean up internal states
+		const index = order.indexOf(key)
+		if (index >= 0) order.splice(index, 1)
+		const watcher = signalWatchers.get(key)
+		if (watcher) {
+			watcher.stop()
+			signalWatchers.delete(key)
+		}
+	}
+
+	// Initialize properties
+	for (let i = 0; i < origin.length; i++) {
+		const key = origin.keyAt(i)
+		if (!key) continue
+		addProperty(key)
+	}
+	origin.on('add', additions => {
+		for (const key of additions) {
+			if (!signals.has(key)) addProperty(key)
+		}
+		notifyWatchers(watchers)
+		emitNotification(listeners.add, additions)
+	})
+	origin.on('remove', removals => {
+		for (const key of Object.keys(removals)) {
+			if (!signals.has(key)) continue
+			removeProperty(key)
+		}
+		order = order.filter(() => true) // Compact array
+		notifyWatchers(watchers)
+		emitNotification(listeners.remove, removals)
+	})
+	origin.on('sort', newOrder => {
+		order = [...newOrder]
+		notifyWatchers(watchers)
+		emitNotification(listeners.sort, newOrder)
+	})
+
+	// Get signal by key or index
+	const getSignal = (prop: string): Signal<T> | undefined => {
+		let key = prop
+		const index = Number(prop)
+		if (Number.isInteger(index) && index >= 0) key = order[index] ?? prop
+		return signals.get(key)
+	}
+
+	// Get current array
+	const current = (): T =>
+		order
+			.map(key => signals.get(key)?.get())
+			.filter(v => v !== UNSET) as unknown as T
+
+	// Methods and Properties
+	const collection: Record<PropertyKey, unknown> = {}
+	Object.defineProperties(collection, {
+		[Symbol.toStringTag]: {
+			value: TYPE_COLLECTION,
+		},
+		[Symbol.isConcatSpreadable]: {
+			value: true,
+		},
+		[Symbol.iterator]: {
+			value: function* () {
+				for (const key of order) {
+					const signal = signals.get(key)
+					if (signal) yield signal
+				}
+			},
+		},
+		byKey: {
+			value(key: string) {
+				return getSignal(key)
+			},
+		},
+		keyAt: {
+			value(index: number): string | undefined {
+				return order[index]
+			},
+		},
+		indexOfKey: {
+			value(key: string): number {
+				return order.indexOf(key)
+			},
+		},
+		get: {
+			value: (): T => {
+				subscribeActiveWatcher(watchers)
+				return current()
+			},
+		},
+		sort: {
+			value: (compareFn?: (a: T, b: T) => number): void => {
+				const entries = order
+					.map((key, index) => {
+						const signal = signals.get(key)
+						return [
+							index,
+							key,
+							signal ? signal.get() : undefined,
+						] as [number, string, T]
+					})
+					.sort(
+						compareFn
+							? (a, b) => compareFn(a[2], b[2])
+							: (a, b) =>
+									String(a[2]).localeCompare(String(b[2])),
+					)
+
+				// Set new order
+				order = entries.map(([_, key]) => key)
+
+				notifyWatchers(watchers)
+				emitNotification(listeners.sort, order)
+			},
+		},
+		on: {
+			value: <K extends keyof Listeners>(
+				type: K,
+				listener: Listener<K>,
+			): Cleanup => {
+				listeners[type].add(listener)
+				return () => listeners[type].delete(listener)
+			},
+		},
+		length: {
+			get(): number {
+				subscribeActiveWatcher(watchers)
+				return signals.size
+			},
+		},
+	})
+
+	// Return proxy directly with integrated signal methods
+	return new Proxy(collection as Collection<T>, {
+		get(target, prop) {
+			if (prop in target) return Reflect.get(target, prop)
+			if (!isSymbol(prop)) return getSignal(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([...order, ...staticKeys])]
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop in target)
+				return Reflect.getOwnPropertyDescriptor(target, prop)
+			if (isSymbol(prop)) return undefined
+
+			const signal = getSignal(prop)
+			return signal
+				? {
+						enumerable: true,
+						configurable: true,
+						writable: true,
+						value: signal,
+					}
+				: undefined
+		},
+	})
+}
+
+const isCollection = /*#__PURE__*/ <T extends UnknownArray>(
+	value: unknown,
+): value is Collection<T> => isObjectOfType(value, TYPE_COLLECTION)
+
+export {
+	type Collection,
+	type CollectionCallback,
+	createCollection,
+	isCollection,
+	TYPE_COLLECTION,
+}

package/{src → archive}/computed.ts

@@ -1,17 +1,17 @@
-import { isEqual } from './diff'
+import { isEqual } from '../src/diff'
 import {
 	CircularDependencyError,
 	InvalidCallbackError,
 	NullishSignalValueError,
-} from './errors'
+} from '../src/errors'
 import {
 	createWatcher,
-	flush,
-	notify,
-	observe,
-	subscribe,
+	flushPendingReactions,
+	notifyWatchers,
+	subscribeActiveWatcher,
+	trackSignalReads,
 	type Watcher,
-} from './system'
+} from '../src/system'
 import {
 	isAbortError,
 	isAsyncFunction,
@@ -19,8 +19,7 @@ import {
 	isObjectOfType,
 	toError,
 	UNSET,
-	valueString,
-} from './util'
+} from '../src/util'
 
 /* === Types === */
 
@@ -28,13 +27,14 @@ type Computed<T extends {}> = {
 	readonly [Symbol.toStringTag]: 'Computed'
 	get(): T
 }
+
 type ComputedCallback<T extends {} & { then?: undefined }> =
 	| ((oldValue: T, abort: AbortSignal) => Promise<T>)
 	| ((oldValue: T) => T)
 
 /* === Constants === */
 
-const TYPE_COMPUTED = 'Computed'
+const TYPE_COMPUTED = 'Computed' as const
 
 /* === Functions === */
 
@@ -50,7 +50,7 @@ const createComputed = <T extends {}>(
 	initialValue: T = UNSET,
 ): Computed<T> => {
 	if (!isComputedCallback(callback))
-		throw new InvalidCallbackError('computed', valueString(callback))
+		throw new InvalidCallbackError('computed', callback)
 	if (initialValue == null) throw new NullishSignalValueError('computed')
 
 	const watchers: Set<Watcher> = new Set()
@@ -92,23 +92,23 @@ const createComputed = <T extends {}>(
 			computing = false
 			controller = undefined
 			fn(arg)
-			if (changed) notify(watchers)
+			if (changed) notifyWatchers(watchers)
 		}
 
 	// Own watcher: called when notified from sources (push)
 	const watcher = createWatcher(() => {
 		dirty = true
 		controller?.abort()
-		if (watchers.size) notify(watchers)
-		else watcher.cleanup()
+		if (watchers.size) notifyWatchers(watchers)
+		else watcher.stop()
 	})
-	watcher.unwatch(() => {
+	watcher.onCleanup(() => {
 		controller?.abort()
 	})
 
 	// Called when requested by dependencies (pull)
 	const compute = () =>
-		observe(() => {
+		trackSignalReads(watcher, () => {
 			if (computing) throw new CircularDependencyError('computed')
 			changed = false
 			if (isAsyncFunction(callback)) {
@@ -143,7 +143,7 @@ const createComputed = <T extends {}>(
 			else if (null == result || UNSET === result) nil()
 			else ok(result)
 			computing = false
-		}, watcher)
+		})
 
 	const computed: Record<PropertyKey, unknown> = {}
 	Object.defineProperties(computed, {
@@ -152,8 +152,8 @@ const createComputed = <T extends {}>(
 		},
 		get: {
 			value: (): T => {
-				subscribe(watchers)
-				flush()
+				subscribeActiveWatcher(watchers)
+				flushPendingReactions()
 				if (dirty) compute()
 				if (error) throw error
 				return value