@zeix/cause-effect 0.15.2 → 0.16.0

package/src/store.ts

@@ -6,7 +6,7 @@ import {
 	type UnknownRecord,
 	type UnknownRecordOrArray,
 } from './diff'
-import { effect } from './effect'
+
 import {
 	InvalidSignalValueError,
 	NullishSignalValueError,
@@ -14,15 +14,17 @@ import {
 	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 { isMutableSignal, type Signal } from './signal'
-import { isState, type State, state } from './state'
+} from './system'
 import {
 	isFunction,
 	isObjectOfType,
@@ -37,51 +39,27 @@ import {
 
 type ArrayItem<T> = T extends readonly (infer U extends {})[] ? U : never
 
-type StoreEventMap<T extends UnknownRecord | UnknownArray> = {
-	'store-add': StoreAddEvent<T>
-	'store-change': StoreChangeEvent<T>
-	'store-remove': StoreRemoveEvent<T>
-	'store-sort': StoreSortEvent
+type StoreChanges<T> = {
+	add: Partial<T>
+	change: Partial<T>
+	remove: Partial<T>
+	sort: string[]
 }
 
-interface StoreEventTarget<T extends UnknownRecord | UnknownArray>
-	extends EventTarget {
-	addEventListener<K extends keyof StoreEventMap<T>>(
-		type: K,
-		listener: (event: StoreEventMap<T>[K]) => void,
-		options?: boolean | AddEventListenerOptions,
-	): void
-
-	removeEventListener<K extends keyof StoreEventMap<T>>(
-		type: K,
-		listener: (event: StoreEventMap<T>[K]) => void,
-		options?: boolean | EventListenerOptions,
-	): void
-
-	dispatchEvent(event: Event): boolean
+type StoreListeners<T> = {
+	[K in keyof StoreChanges<T>]: Set<(change: StoreChanges<T>[K]) => void>
 }
 
-interface BaseStore<T extends UnknownRecord | UnknownArray>
-	extends StoreEventTarget<T> {
+interface BaseStore {
 	readonly [Symbol.toStringTag]: 'Store'
-	get(): T
-	set(value: T): void
-	update(fn: (value: T) => T): void
-	sort<
-		U = T extends UnknownArray ? ArrayItem<T> : T[Extract<keyof T, string>],
-	>(
-		compareFn?: (a: U, b: U) => number,
-	): void
 	readonly size: State<number>
 }
 
-type RecordStore<T extends UnknownRecord> = BaseStore<T> & {
+type RecordStore<T extends UnknownRecord> = BaseStore & {
 	[K in keyof T]: T[K] extends readonly unknown[] | Record<string, unknown>
 		? Store<T[K]>
 		: State<T[K]>
 } & {
-	add<K extends Extract<keyof T, string>>(key: K, value: T[K]): void
-	remove<K extends Extract<keyof T, string>>(key: K): void
 	[Symbol.iterator](): IterableIterator<
 		[
 			Extract<keyof T, string>,
@@ -92,49 +70,46 @@ type RecordStore<T extends UnknownRecord> = BaseStore<T> & {
 				: 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
+	on<K extends keyof StoreChanges<T>>(
+		type: K,
+		listener: (change: StoreChanges<T>[K]) => void,
+	): Cleanup
+	remove<K extends Extract<keyof T, string>>(key: K): void
 }
 
-type ArrayStore<T extends UnknownArray> = BaseStore<T> & {
-	readonly length: number
+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
-	[Symbol.iterator](): IterableIterator<
-		ArrayItem<T> extends readonly unknown[] | Record<string, unknown>
-			? Store<ArrayItem<T>>
-			: State<ArrayItem<T>>
-	>
-	readonly [Symbol.isConcatSpreadable]: boolean
-}
-
-interface StoreAddEvent<T extends UnknownRecord | UnknownArray>
-	extends CustomEvent {
-	type: 'store-add'
-	detail: Partial<T>
-}
-
-interface StoreChangeEvent<T extends UnknownRecord | UnknownArray>
-	extends CustomEvent {
-	type: 'store-change'
-	detail: Partial<T>
-}
-
-interface StoreRemoveEvent<T extends UnknownRecord | UnknownArray>
-	extends CustomEvent {
-	type: 'store-remove'
-	detail: Partial<T>
-}
-
-interface StoreSortEvent extends CustomEvent {
-	type: 'store-sort'
-	detail: string[]
+	readonly length: number
 }
 
-type Store<T> = T extends UnknownRecord
+type Store<T extends UnknownRecord | UnknownArray> = T extends UnknownRecord
 	? RecordStore<T>
 	: T extends UnknownArray
 		? ArrayStore<T>
@@ -144,11 +119,6 @@ type Store<T> = T extends UnknownRecord
 
 const TYPE_STORE = 'Store'
 
-const STORE_EVENT_ADD = 'store-add'
-const STORE_EVENT_CHANGE = 'store-change'
-const STORE_EVENT_REMOVE = 'store-remove'
-const STORE_EVENT_SORT = 'store-sort'
-
 /* === Functions === */
 
 /**
@@ -163,19 +133,26 @@ const STORE_EVENT_SORT = 'store-sort'
  * @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 UnknownRecord | UnknownArray>(
+const createStore = <T extends UnknownRecord | UnknownArray>(
 	initialValue: T,
 ): Store<T> => {
+	if (initialValue == null) throw new NullishSignalValueError('store')
+
 	const watchers = new Set<Watcher>()
-	const eventTarget = new EventTarget()
+	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 cleanups = new Map<string, Cleanup>()
+	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)
+	const size = createState(0)
 
 	// Get current record
 	const current = () => {
@@ -186,9 +163,16 @@ const store = <T extends UnknownRecord | UnknownArray>(
 		return record
 	}
 
-	// Emit event
-	const emit = <R>(type: keyof StoreEventMap<T>, detail: R) =>
-		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 = () =>
@@ -223,26 +207,25 @@ const store = <T extends UnknownRecord | UnknownArray>(
 		const signal =
 			isState(value) || isStore(value)
 				? value
-				: isRecord(value)
-					? store(value)
-					: Array.isArray(value)
-						? store(value)
-						: state(value)
+				: isRecord(value) || Array.isArray(value)
+					? createStore(value)
+					: createState(value)
 		// @ts-expect-error non-matching signal types
 		signals.set(key, signal)
-		const cleanup = effect(() => {
-			const currentValue = signal.get()
-			if (currentValue != null)
-				emit(STORE_EVENT_CHANGE, {
-					[key]: currentValue,
+		const watcher = createWatcher(() =>
+			observe(() => {
+				emit('change', {
+					[key]: signal.get(),
 				} as unknown as Partial<T>)
-		})
-		cleanups.set(key, cleanup)
+			}, watcher),
+		)
+		watcher()
+		signalWatchers.set(key, watcher)
 
 		if (single) {
 			size.set(signals.size)
 			notify(watchers)
-			emit(STORE_EVENT_ADD, {
+			emit('add', {
 				[key]: value,
 			} as unknown as Partial<T>)
 		}
@@ -256,15 +239,15 @@ const store = <T extends UnknownRecord | UnknownArray>(
 	) => {
 		const ok = signals.delete(key)
 		if (ok) {
-			const cleanup = cleanups.get(key)
-			if (cleanup) cleanup()
-			cleanups.delete(key)
+			const watcher = signalWatchers.get(key)
+			if (watcher) watcher.cleanup()
+			signalWatchers.delete(key)
 		}
 
 		if (single) {
 			size.set(signals.size)
 			notify(watchers)
-			emit(STORE_EVENT_REMOVE, {
+			emit('remove', {
 				[key]: UNSET,
 			} as unknown as Partial<T>)
 		}
@@ -296,10 +279,10 @@ const store = <T extends UnknownRecord | UnknownArray>(
 				// Queue initial additions event to allow listeners to be added first
 				if (initialRun) {
 					setTimeout(() => {
-						emit(STORE_EVENT_ADD, changes.add as Partial<T>)
+						emit('add', changes.add as Partial<T>)
 					}, 0)
 				} else {
-					emit<Partial<T>>(STORE_EVENT_ADD, changes.add as Partial<T>)
+					emit('add', changes.add as Partial<T>)
 				}
 			}
 
@@ -314,14 +297,14 @@ const store = <T extends UnknownRecord | UnknownArray>(
 					else
 						throw new StoreKeyReadonlyError(key, valueString(value))
 				}
-				emit(STORE_EVENT_CHANGE, changes.change as Partial<T>)
+				emit('change', changes.change as Partial<T>)
 			}
 
 			// Removals
 			if (Object.keys(changes.remove).length) {
 				for (const key in changes.remove)
 					removeProperty(key as Extract<keyof T, string>)
-				emit(STORE_EVENT_REMOVE, changes.remove as Partial<T>)
+				emit('remove', changes.remove as Partial<T>)
 			}
 
 			size.set(signals.size)
@@ -334,7 +317,7 @@ const store = <T extends UnknownRecord | UnknownArray>(
 	reconcile({} as T, initialValue, true)
 
 	// Methods and Properties
-	const s: Record<string, unknown> = {
+	const store: Record<string, unknown> = {
 		add: isArrayLike
 			? (v: ArrayItem<T>): void => {
 					const nextIndex = signals.size
@@ -426,11 +409,15 @@ const store = <T extends UnknownRecord | UnknownArray>(
 			signals.clear()
 			newSignals.forEach((signal, key) => signals.set(key, signal))
 			notify(watchers)
-			emit(STORE_EVENT_SORT, newOrder)
+			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)
 		},
-		addEventListener: eventTarget.addEventListener.bind(eventTarget),
-		removeEventListener: eventTarget.removeEventListener.bind(eventTarget),
-		dispatchEvent: eventTarget.dispatchEvent.bind(eventTarget),
 		size,
 	}
 
@@ -458,7 +445,7 @@ const store = <T extends UnknownRecord | UnknownArray>(
 			if (isSymbol(prop)) return undefined
 
 			// Methods and Properties
-			if (prop in s) return s[prop]
+			if (prop in store) return store[prop]
 			if (prop === 'length' && isArrayLike) {
 				subscribe(watchers)
 				return size.get()
@@ -472,7 +459,7 @@ const store = <T extends UnknownRecord | UnknownArray>(
 			return (
 				(stringProp &&
 					signals.has(stringProp as Extract<keyof T, string>)) ||
-				Object.keys(s).includes(stringProp) ||
+				Object.keys(store).includes(stringProp) ||
 				prop === Symbol.toStringTag ||
 				prop === Symbol.iterator ||
 				prop === Symbol.isConcatSpreadable ||
@@ -506,7 +493,8 @@ const store = <T extends UnknownRecord | UnknownArray>(
 			if (prop === Symbol.toStringTag) return nonEnumerable(TYPE_STORE)
 			if (isSymbol(prop)) return undefined
 
-			if (Object.keys(s).includes(prop)) return nonEnumerable(s[prop])
+			if (Object.keys(store).includes(prop))
+				return nonEnumerable(store[prop])
 
 			const signal = signals.get(prop as Extract<keyof T, string>)
 			return signal
@@ -534,14 +522,4 @@ const isStore = <T extends UnknownRecordOrArray>(
 
 /* === Exports === */
 
-export {
-	TYPE_STORE,
-	isStore,
-	store,
-	type Store,
-	type StoreAddEvent,
-	type StoreChangeEvent,
-	type StoreRemoveEvent,
-	type StoreSortEvent,
-	type StoreEventMap,
-}
+export { TYPE_STORE, isStore, createStore, type Store, type StoreChanges }

package/src/system.ts

@@ -0,0 +1,122 @@
+/* === Types === */
+
+type Cleanup = () => void
+
+type Watcher = {
+	(): void
+	unwatch(cleanup: Cleanup): void
+	cleanup(): void
+}
+
+/* === Internal === */
+
+// Currently active watcher
+let activeWatcher: Watcher | undefined
+
+// Pending queue for batched change notifications
+const pendingWatchers = new Set<Watcher>()
+let batchDepth = 0
+
+/* === Functions === */
+
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} watch - Function to be called when the state changes
+ * @returns {Watcher} - Watcher object with off and cleanup methods
+ */
+const createWatcher = (watch: () => void): Watcher => {
+	const cleanups = new Set<Cleanup>()
+	const w = watch as Partial<Watcher>
+	w.unwatch = (cleanup: Cleanup) => {
+		cleanups.add(cleanup)
+	}
+	w.cleanup = () => {
+		for (const cleanup of cleanups) cleanup()
+		cleanups.clear()
+	}
+	return w as Watcher
+}
+
+/**
+ * Add active watcher to the Set of watchers
+ *
+ * @param {Set<Watcher>} watchers - watchers of the signal
+ */
+const subscribe = (watchers: Set<Watcher>) => {
+	if (activeWatcher && !watchers.has(activeWatcher)) {
+		const watcher = activeWatcher
+		watcher.unwatch(() => {
+			watchers.delete(watcher)
+		})
+		watchers.add(watcher)
+	}
+}
+
+/**
+ * Add watchers to the pending set of change notifications
+ *
+ * @param {Set<Watcher>} watchers - watchers of the signal
+ */
+const notify = (watchers: Set<Watcher>) => {
+	for (const watcher of watchers) {
+		if (batchDepth) pendingWatchers.add(watcher)
+		else watcher()
+	}
+}
+
+/**
+ * Flush all pending changes to notify watchers
+ */
+const flush = () => {
+	while (pendingWatchers.size) {
+		const watchers = Array.from(pendingWatchers)
+		pendingWatchers.clear()
+		for (const watcher of watchers) watcher()
+	}
+}
+
+/**
+ * Batch multiple changes in a single signal graph and DOM update cycle
+ *
+ * @param {() => void} fn - function with multiple signal writes to be batched
+ */
+const batch = (fn: () => void) => {
+	batchDepth++
+	try {
+		fn()
+	} finally {
+		flush()
+		batchDepth--
+	}
+}
+
+/**
+ * Run a function in a reactive context
+ *
+ * @param {() => void} run - function to run the computation or effect
+ * @param {Watcher} watcher - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
+ */
+const observe = (run: () => void, watcher?: Watcher): void => {
+	const prev = activeWatcher
+	activeWatcher = watcher
+	try {
+		run()
+	} finally {
+		activeWatcher = prev
+	}
+}
+
+/* === Exports === */
+
+export {
+	type Cleanup,
+	type Watcher,
+	subscribe,
+	notify,
+	flush,
+	batch,
+	createWatcher,
+	observe,
+}

package/src/util.ts

@@ -23,10 +23,6 @@ const isAsyncFunction = /*#__PURE__*/ <T>(
 ): fn is (...args: unknown[]) => Promise<T> =>
 	isFunction(fn) && fn.constructor.name === 'AsyncFunction'
 
-const isDefinedObject = /*#__PURE__*/ (
-	value: unknown,
-): value is Record<string, unknown> => !!value && typeof value === 'object'
-
 const isObjectOfType = /*#__PURE__*/ <T>(
 	value: unknown,
 	type: string,
@@ -92,7 +88,7 @@ const recordToArray = /*#__PURE__*/ <T>(
 const valueString = /*#__PURE__*/ (value: unknown): string =>
 	isString(value)
 		? `"${value}"`
-		: isDefinedObject(value)
+		: !!value && typeof value === 'object'
 			? JSON.stringify(value)
 			: String(value)
 
@@ -105,7 +101,6 @@ export {
 	isSymbol,
 	isFunction,
 	isAsyncFunction,
-	isDefinedObject,
 	isObjectOfType,
 	isRecord,
 	isRecordOrArray,

package/test/batch.test.ts

@@ -1,14 +1,21 @@
 import { describe, expect, test } from 'bun:test'
-import { batch, computed, effect, match, resolve, state } from '../'
+import {
+	batch,
+	createComputed,
+	createEffect,
+	createState,
+	match,
+	resolve,
+} from '../'
 
 /* === Tests === */
 
 describe('Batch', () => {
 	test('should be triggered only once after repeated state change', () => {
-		const cause = state(0)
+		const cause = createState(0)
 		let result = 0
 		let count = 0
-		effect((): undefined => {
+		createEffect((): undefined => {
 			result = cause.get()
 			count++
 		})
@@ -22,13 +29,13 @@ describe('Batch', () => {
 	})
 
 	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())
+		const a = createState(3)
+		const b = createState(4)
+		const c = createState(5)
+		const sum = createComputed(() => a.get() + b.get() + c.get())
 		let result = 0
 		let count = 0
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ sum })
 			match(resolved, {
 				ok: ({ sum: res }) => {
@@ -49,10 +56,10 @@ describe('Batch', () => {
 
 	test('should prove example from README works', () => {
 		// State: define an array of Signal<number>
-		const signals = [state(2), state(3), state(5)]
+		const signals = [createState(2), createState(3), createState(5)]
 
 		// Computed: derive a calculation ...
-		const sum = computed(() => {
+		const sum = createComputed(() => {
 			const v = signals.reduce((total, v) => total + v.get(), 0)
 			if (!Number.isFinite(v)) throw new Error('Invalid value')
 			return v
@@ -63,7 +70,7 @@ describe('Batch', () => {
 		let errCount = 0
 
 		// Effect: switch cases for the result
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ sum })
 			match(resolved, {
 				ok: ({ sum: v }) => {

package/test/benchmark.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, mock, test } from 'bun:test'
-import { batch, computed, effect, state } from '../'
+import { batch, createComputed, createEffect, createState } from '../'
 import { Counter, makeGraph, runGraph } from './util/dependency-graph'
 import type { Computed, ReactiveFramework } from './util/reactive-framework'
 
@@ -15,19 +15,19 @@ const busy = () => {
 const framework = {
 	name: 'Cause & Effect',
 	signal: <T extends {}>(initialValue: T) => {
-		const s = state<T>(initialValue)
+		const s = createState<T>(initialValue)
 		return {
 			write: (v: T) => s.set(v),
 			read: () => s.get(),
 		}
 	},
 	computed: <T extends {}>(fn: () => T) => {
-		const c = computed(fn)
+		const c = createComputed(fn)
 		return {
 			read: () => c.get(),
 		}
 	},
-	effect: (fn: () => undefined) => effect(fn),
+	effect: (fn: () => undefined) => createEffect(fn),
 	withBatch: (fn: () => undefined) => batch(fn),
 	withBuild: <T>(fn: () => T) => fn(),
 }