@zeix/cause-effect 0.15.1 → 0.16.0

package/src/store.ts

@@ -1,82 +1,123 @@
-import { diff, type UnknownRecord, type UnknownRecordOrArray } from './diff'
-import { effect } from './effect'
+import { isComputed } from './computed'
+import {
+	type ArrayToRecord,
+	diff,
+	type UnknownArray,
+	type UnknownRecord,
+	type UnknownRecordOrArray,
+} from './diff'
+
+import {
+	InvalidSignalValueError,
+	NullishSignalValueError,
+	StoreKeyExistsError,
+	StoreKeyRangeError,
+	StoreKeyReadonlyError,
+} from './errors'
+import { isMutableSignal, type Signal } from './signal'
+import { createState, isState, type State } from './state'
 import {
 	batch,
 	type Cleanup,
+	createWatcher,
 	notify,
+	observe,
 	subscribe,
 	type Watcher,
-} from './scheduler'
-import { type Signal, toMutableSignal, UNSET } from './signal'
-import { type State, state } from './state'
-import { hasMethod, isObjectOfType, validArrayIndexes } from './util'
-
-/* === Constants === */
-
-const TYPE_STORE = 'Store'
+} from './system'
+import {
+	isFunction,
+	isObjectOfType,
+	isRecord,
+	isSymbol,
+	recordToArray,
+	UNSET,
+	valueString,
+} from './util'
 
 /* === Types === */
 
-interface StoreAddEvent<T extends UnknownRecordOrArray> extends CustomEvent {
-	type: 'store-add'
-	detail: Partial<T>
-}
+type ArrayItem<T> = T extends readonly (infer U extends {})[] ? U : never
 
-interface StoreChangeEvent<T extends UnknownRecordOrArray> extends CustomEvent {
-	type: 'store-change'
-	detail: Partial<T>
+type StoreChanges<T> = {
+	add: Partial<T>
+	change: Partial<T>
+	remove: Partial<T>
+	sort: string[]
 }
 
-interface StoreRemoveEvent<T extends UnknownRecordOrArray> extends CustomEvent {
-	type: 'store-remove'
-	detail: Partial<T>
+type StoreListeners<T> = {
+	[K in keyof StoreChanges<T>]: Set<(change: StoreChanges<T>[K]) => void>
 }
 
-type StoreEventMap<T extends UnknownRecordOrArray> = {
-	'store-add': StoreAddEvent<T>
-	'store-change': StoreChangeEvent<T>
-	'store-remove': StoreRemoveEvent<T>
+interface BaseStore {
+	readonly [Symbol.toStringTag]: 'Store'
+	readonly size: State<number>
 }
 
-interface StoreEventTarget<T extends UnknownRecordOrArray> extends EventTarget {
-	addEventListener<K extends keyof StoreEventMap<T>>(
-		type: K,
-		listener: (event: StoreEventMap<T>[K]) => void,
-		options?: boolean | AddEventListenerOptions,
+type RecordStore<T extends UnknownRecord> = BaseStore & {
+	[K in keyof T]: T[K] extends readonly unknown[] | Record<string, unknown>
+		? Store<T[K]>
+		: State<T[K]>
+} & {
+	[Symbol.iterator](): IterableIterator<
+		[
+			Extract<keyof T, string>,
+			T[Extract<keyof T, string>] extends
+				| readonly unknown[]
+				| Record<string, unknown>
+				? Store<T[Extract<keyof T, string>]>
+				: State<T[Extract<keyof T, string>]>,
+		]
+	>
+	add<K extends Extract<keyof T, string>>(key: K, value: T[K]): void
+	get(): T
+	set(value: T): void
+	update(fn: (value: T) => T): void
+	sort<U = T[Extract<keyof T, string>]>(
+		compareFn?: (a: U, b: U) => number,
 	): void
-	addEventListener(
-		type: string,
-		listener: EventListenerOrEventListenerObject,
-		options?: boolean | AddEventListenerOptions,
-	): void
-
-	removeEventListener<K extends keyof StoreEventMap<T>>(
+	on<K extends keyof StoreChanges<T>>(
 		type: K,
-		listener: (event: StoreEventMap<T>[K]) => void,
-		options?: boolean | EventListenerOptions,
-	): void
-	removeEventListener(
-		type: string,
-		listener: EventListenerOrEventListenerObject,
-		options?: boolean | EventListenerOptions,
-	): void
+		listener: (change: StoreChanges<T>[K]) => void,
+	): Cleanup
+	remove<K extends Extract<keyof T, string>>(key: K): void
+}
 
-	dispatchEvent(event: Event): boolean
+type ArrayStore<T extends UnknownArray> = BaseStore & {
+	[Symbol.iterator](): IterableIterator<
+		ArrayItem<T> extends readonly unknown[] | Record<string, unknown>
+			? Store<ArrayItem<T>>
+			: State<ArrayItem<T>>
+	>
+	readonly [Symbol.isConcatSpreadable]: boolean
+	[n: number]: ArrayItem<T> extends
+		| readonly unknown[]
+		| Record<string, unknown>
+		? Store<ArrayItem<T>>
+		: State<ArrayItem<T>>
+	add(value: ArrayItem<T>): void
+	get(): T
+	set(value: T): void
+	update(fn: (value: T) => T): void
+	sort<U = ArrayItem<T>>(compareFn?: (a: U, b: U) => number): void
+	on<K extends keyof StoreChanges<T>>(
+		type: K,
+		listener: (change: StoreChanges<T>[K]) => void,
+	): Cleanup
+	remove(index: number): void
+	readonly length: number
 }
 
-type Store<T extends UnknownRecordOrArray = UnknownRecord> = {
-	[K in keyof T]: T[K] extends UnknownRecord ? Store<T[K]> : State<T[K]>
-} & StoreEventTarget<T> & {
-		[Symbol.toStringTag]: 'Store'
-		[Symbol.iterator](): IterableIterator<[keyof T, Signal<T[keyof T]>]>
-
-		add<K extends keyof T>(key: K, value: T[K]): void
-		get(): T
-		remove<K extends keyof T>(key: K): void
-		set(value: T): void
-		update(updater: (value: T) => T): void
-		size: State<number>
-	}
+type Store<T extends UnknownRecord | UnknownArray> = T extends UnknownRecord
+	? RecordStore<T>
+	: T extends UnknownArray
+		? ArrayStore<T>
+		: never
+
+/* === Constants === */
+
+const TYPE_STORE = 'Store'
 
 /* === Functions === */
 
@@ -92,87 +133,178 @@ type Store<T extends UnknownRecordOrArray = UnknownRecord> = {
  * @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 store = <T extends UnknownRecordOrArray>(initialValue: T): Store<T> => {
-	const watchers: Set<Watcher> = new Set()
-	const eventTarget = new EventTarget()
-	const signals: Map<keyof T, Store<T[keyof T]> | State<T[keyof T]>> =
-		new Map()
-	const cleanups = new Map<keyof T, Cleanup>()
+const createStore = <T extends UnknownRecord | UnknownArray>(
+	initialValue: T,
+): Store<T> => {
+	if (initialValue == null) throw new NullishSignalValueError('store')
+
+	const watchers = new Set<Watcher>()
+	const listeners: StoreListeners<T> = {
+		add: new Set<(change: Partial<T>) => void>(),
+		change: new Set<(change: Partial<T>) => void>(),
+		remove: new Set<(change: Partial<T>) => void>(),
+		sort: new Set<(change: string[]) => void>(),
+	}
+	const signals = new Map<string, Signal<T[Extract<keyof T, string>] & {}>>()
+	const signalWatchers = new Map<string, Watcher>()
+
+	// Determine if this is an array-like store at creation time
+	const isArrayLike = Array.isArray(initialValue)
 
 	// Internal state
-	const size = state(0)
-
-	// Get current record or array
-	const current = (): T => {
-		const keys = Array.from(signals.keys())
-		const arrayIndexes = validArrayIndexes(keys)
-		if (arrayIndexes)
-			return arrayIndexes.map(index =>
-				signals.get(String(index))?.get(),
-			) as unknown as T
-		const record: Partial<T> = {}
+	const size = createState(0)
+
+	// Get current record
+	const current = () => {
+		const record: Record<string, unknown> = {}
 		for (const [key, signal] of signals) {
 			record[key] = signal.get()
 		}
-		return record as T
+		return record
 	}
 
-	// Emit event
-	const emit = (type: keyof StoreEventMap<T>, detail: Partial<T>) =>
-		eventTarget.dispatchEvent(new CustomEvent(type, { detail }))
+	// Emit change notifications
+	const emit = <K extends keyof StoreChanges<T>>(
+		key: K,
+		changes: StoreChanges<T>[K],
+	) => {
+		Object.freeze(changes)
+		for (const listener of listeners[key]) {
+			listener(changes)
+		}
+	}
+
+	// Get sorted indexes
+	const getSortedIndexes = () =>
+		Array.from(signals.keys())
+			.map(k => Number(k))
+			.filter(n => Number.isInteger(n))
+			.sort((a, b) => a - b)
+
+	// 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}"`,
+				valueString(value),
+			)
+		return true
+	}
 
 	// Add nested signal and effect
-	const addProperty = <K extends keyof T>(key: K, value: T[K]) => {
-		const stringKey = String(key)
-		const signal = toMutableSignal(value)
-		signals.set(stringKey, signal as Store<T[keyof T]> | State<T[keyof T]>)
-		const cleanup = effect(() => {
-			const currentValue = signal.get()
-			if (currentValue != null)
-				emit('store-change', { [key]: currentValue } as Partial<T>)
-		})
-		cleanups.set(stringKey, cleanup)
+	const addProperty = <K extends Extract<keyof T, string>>(
+		key: K,
+		value: T[K] | ArrayItem<T>,
+		single = false,
+	): boolean => {
+		if (!isValidValue(key, value)) return false
+		const signal =
+			isState(value) || isStore(value)
+				? value
+				: isRecord(value) || Array.isArray(value)
+					? createStore(value)
+					: createState(value)
+		// @ts-expect-error non-matching signal types
+		signals.set(key, signal)
+		const watcher = createWatcher(() =>
+			observe(() => {
+				emit('change', {
+					[key]: signal.get(),
+				} as unknown as Partial<T>)
+			}, watcher),
+		)
+		watcher()
+		signalWatchers.set(key, watcher)
+
+		if (single) {
+			size.set(signals.size)
+			notify(watchers)
+			emit('add', {
+				[key]: value,
+			} as unknown as Partial<T>)
+		}
+		return true
 	}
 
 	// Remove nested signal and effect
-	const removeProperty = <K extends keyof T>(key: K) => {
-		const stringKey = String(key)
-		signals.delete(stringKey)
-		const cleanup = cleanups.get(stringKey)
-		if (cleanup) cleanup()
-		cleanups.delete(stringKey)
+	const removeProperty = <K extends Extract<keyof T, string>>(
+		key: K,
+		single = false,
+	) => {
+		const ok = signals.delete(key)
+		if (ok) {
+			const watcher = signalWatchers.get(key)
+			if (watcher) watcher.cleanup()
+			signalWatchers.delete(key)
+		}
+
+		if (single) {
+			size.set(signals.size)
+			notify(watchers)
+			emit('remove', {
+				[key]: UNSET,
+			} as unknown as Partial<T>)
+		}
+		return ok
 	}
 
 	// Reconcile data and dispatch events
-	const reconcile = (oldValue: T, newValue: T): boolean => {
-		const changes = diff(oldValue, newValue)
+	const reconcile = (
+		oldValue: T,
+		newValue: T,
+		initialRun?: boolean,
+	): boolean => {
+		const changes = diff(
+			oldValue as T extends UnknownArray ? ArrayToRecord<T> : T,
+			newValue as T extends UnknownArray ? ArrayToRecord<T> : T,
+		)
 
 		batch(() => {
+			// Additions
 			if (Object.keys(changes.add).length) {
 				for (const key in changes.add) {
-					const value = changes.add[key]
-					if (value != null) addProperty(key, value as T[keyof T])
+					const value = changes.add[key] ?? UNSET
+					addProperty(
+						key as Extract<keyof T, string>,
+						value as T[Extract<keyof T, string>] & {},
+					)
+				}
+
+				// Queue initial additions event to allow listeners to be added first
+				if (initialRun) {
+					setTimeout(() => {
+						emit('add', changes.add as Partial<T>)
+					}, 0)
+				} else {
+					emit('add', changes.add as Partial<T>)
 				}
-				emit('store-add', changes.add)
 			}
+
+			// Changes
 			if (Object.keys(changes.change).length) {
 				for (const key in changes.change) {
-					const signal = signals.get(key)
 					const value = changes.change[key]
-					if (
-						signal &&
-						value != null &&
-						hasMethod<Signal<T[keyof T]>>(signal, 'set')
-					)
-						signal.set(value)
+					if (!isValidValue(key, value)) continue
+					const signal = signals.get(key as Extract<keyof T, string>)
+					if (isMutableSignal(signal))
+						signal.set(value as T[Extract<keyof T, string>] & {})
+					else
+						throw new StoreKeyReadonlyError(key, valueString(value))
 				}
-				emit('store-change', changes.change)
+				emit('change', changes.change as Partial<T>)
 			}
+
+			// Removals
 			if (Object.keys(changes.remove).length) {
-				for (const key in changes.remove) {
-					removeProperty(key)
-				}
-				emit('store-remove', changes.remove)
+				for (const key in changes.remove)
+					removeProperty(key as Extract<keyof T, string>)
+				emit('remove', changes.remove as Partial<T>)
 			}
 
 			size.set(signals.size)
@@ -181,112 +313,190 @@ const store = <T extends UnknownRecordOrArray>(initialValue: T): Store<T> => {
 		return changes.changed
 	}
 
-	// Initialize data
-	reconcile({} as T, initialValue)
+	// Initialize data - convert arrays to records for internal storage
+	reconcile({} as T, initialValue, true)
 
-	// Queue initial additions event to allow listeners to be added first
-	setTimeout(() => {
-		const initialAdditionsEvent = new CustomEvent('store-add', {
-			detail: initialValue,
-		})
-		eventTarget.dispatchEvent(initialAdditionsEvent)
-	}, 0)
-
-	const storeProps = [
-		'add',
-		'get',
-		'remove',
-		'set',
-		'update',
-		'addEventListener',
-		'removeEventListener',
-		'dispatchEvent',
-		'size',
-	]
+	// Methods and Properties
+	const store: Record<string, unknown> = {
+		add: isArrayLike
+			? (v: ArrayItem<T>): void => {
+					const nextIndex = signals.size
+					const key = String(nextIndex) as Extract<keyof T, string>
+					addProperty(key, v, true)
+				}
+			: <K extends Extract<keyof T, string>>(k: K, v: T[K]): void => {
+					if (!signals.has(k)) addProperty(k, v, true)
+					else throw new StoreKeyExistsError(k, valueString(v))
+				},
+		get: (): T => {
+			subscribe(watchers)
+			return recordToArray(current()) as T
+		},
+		remove: isArrayLike
+			? (index: number): void => {
+					const currentArray = recordToArray(current()) as T
+					const currentLength = signals.size
+					if (
+						!Array.isArray(currentArray) ||
+						index <= -currentLength ||
+						index >= currentLength
+					)
+						throw new StoreKeyRangeError(index)
+					const newArray = [...currentArray]
+					newArray.splice(index, 1)
+
+					if (reconcile(currentArray, newArray as unknown as T))
+						notify(watchers)
+				}
+			: <K extends Extract<keyof T, string>>(k: K): void => {
+					if (signals.has(k)) removeProperty(k, true)
+				},
+		set: (v: T): void => {
+			if (reconcile(current() as T, v)) {
+				notify(watchers)
+				if (UNSET === v) watchers.clear()
+			}
+		},
+		update: (fn: (v: T) => T): void => {
+			const oldValue = current()
+			const newValue = fn(recordToArray(oldValue) as T)
+			if (reconcile(oldValue as T, newValue)) {
+				notify(watchers)
+				if (UNSET === newValue) watchers.clear()
+			}
+		},
+		sort: (
+			compareFn?: <
+				U = T extends UnknownArray
+					? ArrayItem<T>
+					: T[Extract<keyof T, string>],
+			>(
+				a: U,
+				b: U,
+			) => number,
+		): void => {
+			// Get all entries as [key, value] pairs
+			const entries = Array.from(signals.entries())
+				.map(
+					([key, signal]) =>
+						[key, signal.get()] as [
+							string,
+							T[Extract<keyof T, string>],
+						],
+				)
+				.sort(
+					compareFn
+						? (a, b) => compareFn(a[1], b[1])
+						: (a, b) => String(a[1]).localeCompare(String(b[1])),
+				)
+
+			// Create array of original keys in their new sorted order
+			const newOrder: string[] = entries.map(([key]) => String(key))
+			const newSignals = new Map<
+				string,
+				Signal<T[Extract<keyof T, string>] & {}>
+			>()
+
+			entries.forEach(([key], newIndex) => {
+				const oldKey = String(key)
+				const newKey = isArrayLike ? String(newIndex) : String(key)
+
+				const signal = signals.get(oldKey)
+				if (signal) newSignals.set(newKey, signal)
+			})
+
+			// Replace signals map
+			signals.clear()
+			newSignals.forEach((signal, key) => signals.set(key, signal))
+			notify(watchers)
+			emit('sort', newOrder)
+		},
+		on: <K extends keyof StoreChanges<T>>(
+			type: K,
+			listener: (change: StoreChanges<T>[K]) => void,
+		): Cleanup => {
+			listeners[type].add(listener)
+			return () => listeners[type].delete(listener)
+		},
+		size,
+	}
 
 	// Return proxy directly with integrated signal methods
 	return new Proxy({} as Store<T>, {
 		get(_target, prop) {
-			// Handle signal methods and size property
-			switch (prop) {
-				case 'add':
-					return <K extends keyof T>(k: K, v: T[K]): void => {
-						if (!signals.has(k)) {
-							addProperty(k, v)
-							notify(watchers)
-							emit('store-add', {
-								[k]: v,
-							} as unknown as Partial<T>)
-							size.set(signals.size)
-						}
-					}
-				case 'get':
-					return (): T => {
-						subscribe(watchers)
-						return current()
-					}
-				case 'remove':
-					return <K extends keyof T>(k: K): void => {
-						if (signals.has(k)) {
-							removeProperty(k)
-							notify(watchers)
-							emit('store-remove', { [k]: UNSET } as Partial<T>)
-							size.set(signals.size)
-						}
-					}
-				case 'set':
-					return (v: T): void => {
-						if (reconcile(current(), v)) {
-							notify(watchers)
-							if (UNSET === v) watchers.clear()
+			// Symbols
+			if (prop === Symbol.toStringTag) return TYPE_STORE
+			if (prop === Symbol.isConcatSpreadable) return isArrayLike
+			if (prop === Symbol.iterator)
+				return isArrayLike
+					? function* () {
+							const indexes = getSortedIndexes()
+							for (const index of indexes) {
+								const signal = signals.get(
+									String(index) as Extract<keyof T, string>,
+								)
+								if (signal) yield signal
+							}
 						}
-					}
-				case 'update':
-					return (fn: (v: T) => T): void => {
-						const oldValue = current()
-						const newValue = fn(oldValue)
-						if (reconcile(oldValue, newValue)) {
-							notify(watchers)
-							if (UNSET === newValue) watchers.clear()
+					: function* () {
+							for (const [key, signal] of signals)
+								yield [key, signal]
 						}
-					}
-				case 'addEventListener':
-					return eventTarget.addEventListener.bind(eventTarget)
-				case 'removeEventListener':
-					return eventTarget.removeEventListener.bind(eventTarget)
-				case 'dispatchEvent':
-					return eventTarget.dispatchEvent.bind(eventTarget)
-				case 'size':
-					return size
-			}
+			if (isSymbol(prop)) return undefined
 
-			// Handle symbol properties
-			if (prop === Symbol.toStringTag) return TYPE_STORE
-			if (prop === Symbol.iterator) {
-				return function* () {
-					for (const [key, signal] of signals) {
-						yield [key, signal]
-					}
-				}
+			// Methods and Properties
+			if (prop in store) return store[prop]
+			if (prop === 'length' && isArrayLike) {
+				subscribe(watchers)
+				return size.get()
 			}
 
-			// Handle data properties - return signals
-			return signals.get(String(prop))
+			// Signals
+			return signals.get(prop as Extract<keyof T, string>)
 		},
 		has(_target, prop) {
-			const key = String(prop)
+			const stringProp = String(prop)
 			return (
-				signals.has(key) ||
-				storeProps.includes(key) ||
+				(stringProp &&
+					signals.has(stringProp as Extract<keyof T, string>)) ||
+				Object.keys(store).includes(stringProp) ||
 				prop === Symbol.toStringTag ||
-				prop === Symbol.iterator
+				prop === Symbol.iterator ||
+				prop === Symbol.isConcatSpreadable ||
+				(prop === 'length' && isArrayLike)
 			)
 		},
 		ownKeys() {
-			return Array.from(signals.keys()).map(key => String(key))
+			return isArrayLike
+				? getSortedIndexes()
+						.map(key => String(key))
+						.concat(['length'])
+				: Array.from(signals.keys()).map(key => String(key))
 		},
 		getOwnPropertyDescriptor(_target, prop) {
-			const signal = signals.get(String(prop))
+			const nonEnumerable = <T>(value: T) => ({
+				enumerable: false,
+				configurable: true,
+				writable: false,
+				value,
+			})
+
+			if (prop === 'length' && isArrayLike)
+				return {
+					enumerable: true,
+					configurable: true,
+					writable: false,
+					value: size.get(),
+				}
+			if (prop === Symbol.isConcatSpreadable)
+				return nonEnumerable(isArrayLike)
+			if (prop === Symbol.toStringTag) return nonEnumerable(TYPE_STORE)
+			if (isSymbol(prop)) return undefined
+
+			if (Object.keys(store).includes(prop))
+				return nonEnumerable(store[prop])
+
+			const signal = signals.get(prop as Extract<keyof T, string>)
 			return signal
 				? {
 						enumerable: true,
@@ -312,13 +522,4 @@ const isStore = <T extends UnknownRecordOrArray>(
 
 /* === Exports === */
 
-export {
-	TYPE_STORE,
-	isStore,
-	store,
-	type Store,
-	type StoreAddEvent,
-	type StoreChangeEvent,
-	type StoreRemoveEvent,
-	type StoreEventMap,
-}
+export { TYPE_STORE, isStore, createStore, type Store, type StoreChanges }