@zeix/cause-effect 0.14.1 → 0.15.0

package/src/signal.ts

@@ -1,10 +1,13 @@
-import { isState, state } from './state'
 import {
+	type Computed,
 	type ComputedCallback,
+	computed,
 	isComputed,
 	isComputedCallback,
-	computed,
 } from './computed'
+import { isState, type State, state } from './state'
+import { isStore, type Store, store } from './store'
+import { arrayToRecord, isRecord } from './util'
 
 /* === Types === */
 
@@ -13,12 +16,13 @@ type Signal<T extends {}> = {
 }
 type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
 
-type SignalValues<S extends Signal<{}>[]> = {
+type SignalValues<S extends Record<string, Signal<unknown & {}>>> = {
 	[K in keyof S]: S[K] extends Signal<infer T> ? T : never
 }
 
 /* === Constants === */
 
+// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
 const UNSET: any = Symbol()
 
 /* === Functions === */
@@ -32,23 +36,52 @@ const UNSET: any = Symbol()
  */
 const isSignal = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
-): value is Signal<T> => isState(value) || isComputed(value)
+): value is Signal<T> => isState(value) || isComputed(value) || isStore(value)
 
 /**
  * Convert a value to a Signal if it's not already a Signal
  *
  * @since 0.9.6
- * @param {MaybeSignal<T>} value - value to convert to a Signal
- * @returns {Signal<T>} - converted Signal
  */
-const toSignal = /*#__PURE__*/ <T extends {}>(
-	value: MaybeSignal<T>,
-): Signal<T> =>
-	isSignal<T>(value)
-		? value
-		: isComputedCallback<T>(value)
-			? computed(value)
-			: state(value as T)
+function toSignal<T extends Array<unknown & {}>>(
+	value: T[],
+): Store<Record<string, T>>
+function toSignal<T extends Record<keyof T, T[keyof T]>>(value: T): Store<T>
+function toSignal<T extends {}>(value: ComputedCallback<T>): Computed<T>
+function toSignal<T extends {}>(value: Signal<T>): Signal<T>
+function toSignal<T extends {}>(value: T): State<T>
+function toSignal<T extends {}>(
+	value: MaybeSignal<T> | T[],
+): Signal<T> | Store<Record<string, T>> {
+	if (isSignal<T>(value)) return value
+	if (isComputedCallback<T>(value)) return computed(value)
+	if (Array.isArray(value)) return store(arrayToRecord(value))
+	if (isRecord(value)) return store(value as T)
+	return state(value as T)
+}
+
+/**
+ * Convert a value to a mutable Signal if it's not already a Signal
+ *
+ * @since 0.9.6
+ */
+function toMutableSignal<T extends Array<unknown & {}>>(
+	value: T[],
+): Store<Record<string, T>>
+function toMutableSignal<T extends Record<keyof T, T[keyof T]>>(
+	value: T,
+): Store<T>
+function toMutableSignal<T extends State<T>>(value: State<T>): State<T>
+function toMutableSignal<T extends Store<T>>(value: Store<T>): Store<T>
+function toMutableSignal<T extends {}>(value: T): State<T>
+function toMutableSignal<T extends {}>(
+	value: T | State<T> | Store<T> | T[],
+): Signal<T> | Store<Record<string, T>> {
+	if (isState<T>(value) || isStore<T>(value)) return value
+	if (Array.isArray(value)) return store(arrayToRecord(value))
+	if (isRecord(value)) return store(value as T)
+	return state(value as T)
+}
 
 /* === Exports === */
 
@@ -58,6 +91,6 @@ export {
 	type SignalValues,
 	UNSET,
 	isSignal,
-	isComputedCallback,
 	toSignal,
+	toMutableSignal,
 }

package/src/state.ts

@@ -1,6 +1,7 @@
+import { isEqual } from './diff'
+import { notify, subscribe, type Watcher } from './scheduler'
 import { UNSET } from './signal'
 import { isObjectOfType } from './util'
-import { type Watcher, notify, subscribe } from './scheduler'
 
 /* === Types === */
 
@@ -50,7 +51,7 @@ const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		 * @returns {void}
 		 */
 		set: (v: T): void => {
-			if (Object.is(value, v)) return
+			if (isEqual(value, v)) return
 			value = v
 			notify(watchers)
 
@@ -86,4 +87,4 @@ const isState = /*#__PURE__*/ <T extends {}>(
 
 /* === Exports === */
 
-export { type State, TYPE_STATE, state, isState }
+export { TYPE_STATE, isState, state, type State }

package/src/store.ts

@@ -0,0 +1,325 @@
+import { diff, type UnknownRecord } from './diff'
+import { effect } from './effect'
+import {
+	batch,
+	type Cleanup,
+	notify,
+	subscribe,
+	type Watcher,
+} from './scheduler'
+import { type Signal, toMutableSignal, UNSET } from './signal'
+import { type State, state } from './state'
+import { hasMethod, isObjectOfType } from './util'
+
+/* === Constants === */
+
+const TYPE_STORE = 'Store'
+
+/* === Types === */
+
+interface StoreAddEvent<T extends UnknownRecord> extends CustomEvent {
+	type: 'store-add'
+	detail: Partial<T>
+}
+
+interface StoreChangeEvent<T extends UnknownRecord> extends CustomEvent {
+	type: 'store-change'
+	detail: Partial<T>
+}
+
+interface StoreRemoveEvent<T extends UnknownRecord> extends CustomEvent {
+	type: 'store-remove'
+	detail: Partial<T>
+}
+
+type StoreEventMap<T extends UnknownRecord> = {
+	'store-add': StoreAddEvent<T>
+	'store-change': StoreChangeEvent<T>
+	'store-remove': StoreRemoveEvent<T>
+}
+
+interface StoreEventTarget<T extends UnknownRecord> extends EventTarget {
+	addEventListener<K extends keyof StoreEventMap<T>>(
+		type: K,
+		listener: (event: StoreEventMap<T>[K]) => void,
+		options?: boolean | AddEventListenerOptions,
+	): void
+	addEventListener(
+		type: string,
+		listener: EventListenerOrEventListenerObject,
+		options?: boolean | AddEventListenerOptions,
+	): void
+
+	removeEventListener<K extends keyof StoreEventMap<T>>(
+		type: K,
+		listener: (event: StoreEventMap<T>[K]) => void,
+		options?: boolean | EventListenerOptions,
+	): void
+	removeEventListener(
+		type: string,
+		listener: EventListenerOrEventListenerObject,
+		options?: boolean | EventListenerOptions,
+	): void
+
+	dispatchEvent(event: Event): boolean
+}
+
+type Store<T extends UnknownRecord = UnknownRecord> = {
+	[K in keyof T & string]: T[K] extends UnknownRecord
+		? Store<T[K]>
+		: State<T[K]>
+} & StoreEventTarget<T> & {
+		[Symbol.toStringTag]: 'Store'
+		[Symbol.iterator](): IterableIterator<[string, Signal<T[keyof T]>]>
+
+		// Signal methods
+		add<K extends keyof T & string>(key: K, value: T[K]): void
+		get(): T
+		remove<K extends keyof T & string>(key: K): void
+		set(value: T): void
+		update(updater: (value: T) => T): void
+
+		// Interals signals
+		size: State<number>
+	}
+
+/* === Functions === */
+
+/**
+ * Create a new store with deeply nested reactive properties
+ *
+ * @since 0.15.0
+ * @param {T} initialValue - initial object value of the store
+ * @returns {Store<T>} - new store with reactive properties
+ */
+const store = <T extends UnknownRecord>(initialValue: T): Store<T> => {
+	const watchers: Set<Watcher> = new Set()
+	const eventTarget = new EventTarget()
+	const signals: Map<
+		keyof T & string,
+		Store<T[keyof T & string]> | State<T[keyof T & string]>
+	> = new Map()
+	const cleanups = new Map<keyof T & string, Cleanup>()
+
+	// Internal state
+	const size = state(0)
+
+	// Get current record
+	const current = () => {
+		const record: Partial<T> = {}
+		for (const [key, value] of signals) {
+			record[key] = value.get()
+		}
+		return record as T
+	}
+
+	// Emit event
+	const emit = (type: keyof StoreEventMap<T>, detail: Partial<T>) =>
+		eventTarget.dispatchEvent(new CustomEvent(type, { detail }))
+
+	// Add nested signal and effect
+	const addSignalAndEffect = <K extends keyof T & string>(
+		key: K,
+		value: T[K],
+	) => {
+		const signal = toMutableSignal<T[keyof T & string]>(value)
+		signals.set(key, signal)
+		const cleanup = effect(() => {
+			const value = signal.get()
+			if (value != null)
+				emit('store-change', { [key]: value } as unknown as Partial<T>)
+		})
+		cleanups.set(key, cleanup)
+	}
+
+	// Remove nested signal and effect
+	const removeSignalAndEffect = <K extends keyof T & string>(key: K) => {
+		signals.delete(key)
+		const cleanup = cleanups.get(key)
+		if (cleanup) cleanup()
+		cleanups.delete(key)
+	}
+
+	// Reconcile data and dispatch events
+	const reconcile = (oldValue: T, newValue: T): boolean => {
+		const changes = diff(oldValue, newValue)
+
+		batch(() => {
+			if (Object.keys(changes.add).length) {
+				for (const key in changes.add) {
+					const value = changes.add[key]
+					if (value != null) addSignalAndEffect(key, value)
+				}
+				emit('store-add', changes.add)
+			}
+			if (Object.keys(changes.change).length) {
+				for (const key in changes.change) {
+					const signal = signals.get(key as keyof T & string)
+					const value = changes.change[key]
+					if (
+						signal &&
+						value != null &&
+						hasMethod<Signal<T[keyof T & string]>>(signal, 'set')
+					)
+						signal.set(value)
+				}
+				emit('store-change', changes.change)
+			}
+			if (Object.keys(changes.remove).length) {
+				for (const key in changes.remove) {
+					removeSignalAndEffect(key)
+				}
+				emit('store-remove', changes.remove)
+			}
+
+			size.set(signals.size)
+		})
+
+		return changes.changed
+	}
+
+	// Initialize data
+	reconcile({} as T, initialValue)
+
+	// Queue initial additions event to allow listeners to be added first
+	setTimeout(() => {
+		const initialAdditionsEvent = new CustomEvent('store-add', {
+			detail: initialValue as Partial<T>,
+		}) as StoreAddEvent<T>
+		eventTarget.dispatchEvent(initialAdditionsEvent)
+	}, 0)
+
+	const storeProps = [
+		'add',
+		'get',
+		'remove',
+		'set',
+		'update',
+		'addEventListener',
+		'removeEventListener',
+		'dispatchEvent',
+		'size',
+	]
+
+	// Return proxy directly with integrated signal methods
+	return new Proxy({} as Store<T>, {
+		get(_target, prop) {
+			const key = String(prop)
+
+			// Handle signal methods and size property
+			switch (prop) {
+				case 'add':
+					return <K extends keyof T & string>(
+						k: K,
+						v: T[K],
+					): void => {
+						if (!signals.has(k)) {
+							addSignalAndEffect(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 & string>(k: K): void => {
+						if (signals.has(k)) {
+							removeSignalAndEffect(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()
+						}
+					}
+				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()
+						}
+					}
+				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
+			}
+
+			// 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 as Signal<T[keyof T]>]
+					}
+				}
+			}
+
+			// Handle data properties - return signals
+			return signals.get(key)
+		},
+		has(_target, prop) {
+			const key = String(prop)
+			return (
+				signals.has(key) ||
+				storeProps.includes(key) ||
+				prop === Symbol.toStringTag ||
+				prop === Symbol.iterator
+			)
+		},
+		ownKeys() {
+			return Array.from(signals.keys())
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const signal = signals.get(String(prop))
+			return signal
+				? {
+						enumerable: true,
+						configurable: true,
+						writable: true,
+						value: signal,
+					}
+				: undefined
+		},
+	})
+}
+
+/**
+ * Check if the provided value is a Store instance
+ *
+ * @since 0.15.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if the value is a Store instance, false otherwise
+ */
+const isStore = <T extends UnknownRecord>(value: unknown): value is Store<T> =>
+	isObjectOfType(value, TYPE_STORE)
+
+/* === Exports === */
+
+export {
+	TYPE_STORE,
+	isStore,
+	store,
+	type Store,
+	type StoreAddEvent,
+	type StoreChangeEvent,
+	type StoreRemoveEvent,
+	type StoreEventMap,
+}

package/src/util.ts

@@ -1,24 +1,76 @@
 /* === Utility Functions === */
 
+const isNumber = /*#__PURE__*/ (value: unknown): value is number =>
+	typeof value === 'number'
+
+const isString = /*#__PURE__*/ (value: unknown): value is string =>
+	typeof value === 'string'
+
 const isFunction = /*#__PURE__*/ <T>(
-	value: unknown,
-): value is (...args: unknown[]) => T => typeof value === 'function'
+	fn: unknown,
+): fn is (...args: unknown[]) => T => typeof fn === 'function'
+
+const isAsyncFunction = /*#__PURE__*/ <T>(
+	fn: unknown,
+): fn is (...args: unknown[]) => Promise<T> =>
+	isFunction(fn) && fn.constructor.name === 'AsyncFunction'
 
 const isObjectOfType = /*#__PURE__*/ <T>(
 	value: unknown,
 	type: string,
 ): value is T => Object.prototype.toString.call(value) === `[object ${type}]`
 
-const toError = (reason: unknown): Error =>
+const isRecord = /*#__PURE__*/ <T extends Record<string, unknown>>(
+	value: unknown,
+): value is T => isObjectOfType(value, 'Object')
+
+const isPrimitive = /*#__PURE__*/ (value: unknown): boolean =>
+	typeof value !== 'object' && !isFunction(value)
+
+const arrayToRecord = /*#__PURE__*/ <T extends unknown & {}>(
+	array: T[],
+): Record<string, T> => {
+	const record: Record<string, T> = {}
+	for (let i = 0; i < array.length; i++) {
+		if (i in array) record[String(i)] = array[i]
+	}
+	return record
+}
+
+const hasMethod = /*#__PURE__*/ <
+	T extends object & Record<string, (...args: unknown[]) => unknown>,
+>(
+	obj: T,
+	methodName: string,
+): obj is T & Record<string, (...args: unknown[]) => unknown> =>
+	methodName in obj && isFunction(obj[methodName])
+
+const isAbortError = /*#__PURE__*/ (error: unknown): boolean =>
+	error instanceof DOMException && error.name === 'AbortError'
+
+const toError = /*#__PURE__*/ (reason: unknown): Error =>
 	reason instanceof Error ? reason : Error(String(reason))
 
 class CircularDependencyError extends Error {
 	constructor(where: string) {
 		super(`Circular dependency in ${where} detected`)
-		return this
+		this.name = 'CircularDependencyError'
 	}
 }
 
 /* === Exports === */
 
-export { isFunction, isObjectOfType, toError, CircularDependencyError }
+export {
+	isNumber,
+	isString,
+	isFunction,
+	isAsyncFunction,
+	isObjectOfType,
+	isRecord,
+	isPrimitive,
+	arrayToRecord,
+	hasMethod,
+	isAbortError,
+	toError,
+	CircularDependencyError,
+}

package/test/batch.test.ts

@@ -1,14 +1,14 @@
-import { describe, test, expect } from 'bun:test'
-import { state, computed, batch, effect } from '../'
+import { describe, expect, test } from 'bun:test'
+import { batch, computed, effect, match, resolve, state } from '../'
 
 /* === Tests === */
 
-describe('Batch', function () {
-	test('should be triggered only once after repeated state change', function () {
+describe('Batch', () => {
+	test('should be triggered only once after repeated state change', () => {
 		const cause = state(0)
 		let result = 0
 		let count = 0
-		effect(() => {
+		effect((): undefined => {
 			result = cause.get()
 			count++
 		})
@@ -21,20 +21,22 @@ describe('Batch', function () {
 		expect(count).toBe(2) // + 1 for effect initialization
 	})
 
-	test('should be triggered only once when multiple signals are set', function () {
+	test('should be triggered only once when multiple signals are set', () => {
 		const a = state(3)
 		const b = state(4)
 		const c = state(5)
 		const sum = computed(() => a.get() + b.get() + c.get())
 		let result = 0
 		let count = 0
-		effect({
-			signals: [sum],
-			ok: res => {
-				result = res
-				count++
-			},
-			err: () => {},
+		effect(() => {
+			const resolved = resolve({ sum })
+			match(resolved, {
+				ok: ({ sum: res }) => {
+					result = res
+					count++
+				},
+				err: () => {},
+			})
 		})
 		batch(() => {
 			a.set(6)
@@ -45,7 +47,7 @@ describe('Batch', function () {
 		expect(count).toBe(2) // + 1 for effect initialization
 	})
 
-	test('should prove example from README works', function () {
+	test('should prove example from README works', () => {
 		// State: define an array of Signal<number>
 		const signals = [state(2), state(3), state(5)]
 
@@ -61,17 +63,19 @@ describe('Batch', function () {
 		let errCount = 0
 
 		// Effect: switch cases for the result
-		effect({
-			signals: [sum],
-			ok: v => {
-				result = v
-				okCount++
-				// console.log('Sum:', v)
-			},
-			err: _error => {
-				errCount++
-				// console.error('Error:', error)
-			},
+		effect(() => {
+			const resolved = resolve({ sum })
+			match(resolved, {
+				ok: ({ sum: v }) => {
+					result = v
+					okCount++
+					// console.log('Sum:', v)
+				},
+				err: () => {
+					errCount++
+					// console.error('Error:', error)
+				},
+			})
 		})
 
 		expect(okCount).toBe(1)