@zeix/cause-effect 0.16.1 → 0.17.0

package/src/signal.ts

@@ -1,13 +1,17 @@
 import {
 	type Computed,
-	type ComputedCallback,
-	createComputed,
 	isComputed,
-	isComputedCallback,
-} from './computed'
-import { createState, isState, type State } from './state'
-import { createStore, isStore, type Store } from './store'
-import { isRecord } from './util'
+	isMemoCallback,
+	isTaskCallback,
+	Memo,
+	Task,
+} from './classes/computed'
+import { isList, List } from './classes/list'
+import { isState, State } from './classes/state'
+import { createStore, isStore, type Store } from './classes/store'
+import type { UnknownRecord } from './diff'
+// import type { Collection } from './signals/collection'
+import { isRecord, isUniformArray } from './util'
 
 /* === Types === */
 
@@ -15,6 +19,13 @@ type Signal<T extends {}> = {
 	get(): T
 }
 
+type MutableSignal<T extends {}> = T extends readonly (infer U extends {})[]
+	? List<U>
+	: T extends UnknownRecord
+		? Store<T>
+		: State<T>
+type ReadonlySignal<T extends {}> = Computed<T> // | Collection<T>
+
 type UnknownSignalRecord = Record<string, Signal<unknown & {}>>
 
 type SignalValues<S extends UnknownSignalRecord> = {
@@ -35,54 +46,60 @@ const isSignal = /*#__PURE__*/ <T extends {}>(
 ): value is Signal<T> => isState(value) || isComputed(value) || isStore(value)
 
 /**
- * Check whether a value is a State or Store
+ * Check whether a value is a State, Store, or List
  *
  * @since 0.15.2
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a State or Store, false otherwise
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if value is a State, Store, or List, false otherwise
  */
-const isMutableSignal = /*#__PURE__*/ <T extends {}>(
+const isMutableSignal = /*#__PURE__*/ (
 	value: unknown,
-): value is State<T> | Store<T> => isState(value) || isStore(value)
+): value is MutableSignal<unknown & {}> =>
+	isState(value) || isStore(value) || isList(value)
 
 /**
- * Convert a value to a Signal if it's not already a Signal
+ * Convert a value to a Signal.
  *
  * @since 0.9.6
- * @param {T} value - value to convert
- * @returns {Signal<T>} - Signal instance
  */
-function toSignal<T extends {}>(
-	value: T,
-): T extends Store<infer U>
-	? Store<U>
-	: T extends State<infer U>
-		? State<U>
-		: T extends Computed<infer U>
-			? Computed<U>
-			: T extends Signal<infer U>
-				? Signal<U>
-				: T extends ReadonlyArray<infer U extends {}>
-					? Store<U[]>
-					: T extends Record<string, unknown & {}>
-						? Store<{ [K in keyof T]: T[K] }>
-						: T extends ComputedCallback<infer U extends {}>
-							? Computed<U>
-							: State<T>
-function toSignal<T extends {}>(value: T) {
-	if (isSignal<T>(value)) return value
-	if (isComputedCallback(value)) return createComputed(value)
-	if (Array.isArray(value) || isRecord(value)) return createStore(value)
-	return createState(value)
+function createSignal<T extends {}>(value: readonly T[]): List<T>
+function createSignal<T extends {}>(value: T[]): List<T>
+function createSignal<T extends UnknownRecord>(value: T): Store<T>
+function createSignal<T extends {}>(value: () => T): Computed<T>
+function createSignal<T extends {}>(value: T): State<T>
+function createSignal(value: unknown): unknown {
+	if (isMemoCallback(value)) return new Memo(value)
+	if (isTaskCallback(value)) return new Task(value)
+	if (isUniformArray<unknown & {}>(value)) return new List(value)
+	if (isRecord(value)) return createStore(value as UnknownRecord)
+	return new State(value as unknown & {})
+}
+
+/**
+ * Convert a value to a MutableSignal.
+ *
+ * @since 0.17.0
+ */
+function createMutableSignal<T extends {}>(value: readonly T[]): List<T>
+function createMutableSignal<T extends {}>(value: T[]): List<T>
+function createMutableSignal<T extends UnknownRecord>(value: T): Store<T>
+function createMutableSignal<T extends {}>(value: T): State<T>
+function createMutableSignal(value: unknown): unknown {
+	if (isUniformArray<unknown & {}>(value)) return new List(value)
+	if (isRecord(value)) return createStore(value as UnknownRecord)
+	return new State(value as unknown & {})
 }
 
 /* === Exports === */
 
 export {
+	createMutableSignal,
+	createSignal,
+	isMutableSignal,
+	isSignal,
+	type MutableSignal,
+	type ReadonlySignal,
 	type Signal,
-	type UnknownSignalRecord,
 	type SignalValues,
-	isSignal,
-	isMutableSignal,
-	toSignal,
+	type UnknownSignalRecord,
 }

package/src/system.ts

@@ -4,8 +4,23 @@ type Cleanup = () => void
 
 type Watcher = {
 	(): void
-	unwatch(cleanup: Cleanup): void
-	cleanup(): void
+	onCleanup(cleanup: Cleanup): void
+	stop(): void
+}
+
+type Notifications = {
+	add: readonly string[]
+	change: readonly string[]
+	remove: readonly string[]
+	sort: readonly string[]
+}
+
+type Listener<K extends keyof Notifications> = (
+	payload: Notifications[K],
+) => void
+
+type Listeners = {
+	[K in keyof Notifications]: Set<Listener<K>>
 }
 
 /* === Internal === */
@@ -13,8 +28,8 @@ type Watcher = {
 // Currently active watcher
 let activeWatcher: Watcher | undefined
 
-// Pending queue for batched change notifications
-const pendingWatchers = new Set<Watcher>()
+// Queue of pending watcher reactions for batched change notifications
+const pendingReactions = new Set<() => void>()
 let batchDepth = 0
 
 /* === Functions === */
@@ -22,85 +37,87 @@ let batchDepth = 0
 /**
  * Create a watcher that can be used to observe changes to a signal
  *
+ * A watcher is a reaction function with onCleanup and stop methods
+ *
  * @since 0.14.1
- * @param {() => void} watch - Function to be called when the state changes
+ * @param {() => void} react - Function to be called when the state changes
  * @returns {Watcher} - Watcher object with off and cleanup methods
  */
-const createWatcher = (watch: () => void): Watcher => {
+const createWatcher = (react: () => void): Watcher => {
 	const cleanups = new Set<Cleanup>()
-	const w = watch as Partial<Watcher>
-	w.unwatch = (cleanup: Cleanup) => {
+	const watcher = react as Partial<Watcher>
+	watcher.onCleanup = (cleanup: Cleanup) => {
 		cleanups.add(cleanup)
 	}
-	w.cleanup = () => {
+	watcher.stop = () => {
 		for (const cleanup of cleanups) cleanup()
 		cleanups.clear()
 	}
-	return w as Watcher
+	return watcher as Watcher
 }
 
 /**
- * Add active watcher to the Set of watchers
+ * Subscribe by adding active watcher to the Set of watchers of a signal
  *
- * @param {Set<Watcher>} watchers - watchers of the signal
+ * @param {Set<Watcher>} watchers - Watchers of the signal
  */
-const subscribe = (watchers: Set<Watcher>) => {
+const subscribeActiveWatcher = (watchers: Set<Watcher>) => {
 	if (activeWatcher && !watchers.has(activeWatcher)) {
 		const watcher = activeWatcher
-		watcher.unwatch(() => {
-			watchers.delete(watcher)
-		})
+		watcher.onCleanup(() => watchers.delete(watcher))
 		watchers.add(watcher)
 	}
 }
 
 /**
- * Add watchers to the pending set of change notifications
+ * Notify watchers of a signal change
  *
- * @param {Set<Watcher>} watchers - watchers of the signal
+ * @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()
+const notifyWatchers = (watchers: Set<Watcher>) => {
+	for (const react of watchers) {
+		if (batchDepth) pendingReactions.add(react)
+		else react()
 	}
 }
 
 /**
- * Flush all pending changes to notify watchers
+ * Flush all pending reactions of enqueued watchers
  */
-const flush = () => {
-	while (pendingWatchers.size) {
-		const watchers = Array.from(pendingWatchers)
-		pendingWatchers.clear()
+const flushPendingReactions = () => {
+	while (pendingReactions.size) {
+		const watchers = Array.from(pendingReactions)
+		pendingReactions.clear()
 		for (const watcher of watchers) watcher()
 	}
 }
 
 /**
- * Batch multiple changes in a single signal graph and DOM update cycle
+ * Batch multiple signal writes
  *
- * @param {() => void} fn - function with multiple signal writes to be batched
+ * @param {() => void} callback - Function with multiple signal writes to be batched
  */
-const batch = (fn: () => void) => {
+const batchSignalWrites = (callback: () => void) => {
 	batchDepth++
 	try {
-		fn()
+		callback()
 	} finally {
-		flush()
+		flushPendingReactions()
 		batchDepth--
 	}
 }
 
 /**
- * Run a function in a reactive context
+ * Run a function with signal reads in a tracking context (or temporarily untrack)
  *
- * @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)
+ * @param {Watcher | false} watcher - Watcher to be called when the signal changes
+ *                                    or false for temporary untracking while inserting auto-hydrating DOM nodes
+ *                                    that might read signals (e.g., Web Components)
+ * @param {() => void} run - Function to run the computation or effect
  */
-const observe = (run: () => void, watcher?: Watcher): void => {
+const trackSignalReads = (watcher: Watcher | false, run: () => void): void => {
 	const prev = activeWatcher
-	activeWatcher = watcher
+	activeWatcher = watcher || undefined
 	try {
 		run()
 	} finally {
@@ -108,15 +125,35 @@ const observe = (run: () => void, watcher?: Watcher): void => {
 	}
 }
 
+/**
+ * Emit a notification to listeners
+ *
+ * @param {Set<Listener>} listeners - Listeners to be notified
+ * @param {Notifications[K]} payload - Payload to be sent to listeners
+ */
+const emitNotification = <T extends keyof Notifications>(
+	listeners: Set<Listener<T>>,
+	payload: Notifications[T],
+) => {
+	for (const listener of listeners) {
+		if (batchDepth) pendingReactions.add(() => listener(payload))
+		else listener(payload)
+	}
+}
+
 /* === Exports === */
 
 export {
 	type Cleanup,
 	type Watcher,
-	subscribe,
-	notify,
-	flush,
-	batch,
+	type Notifications,
+	type Listener,
+	type Listeners,
 	createWatcher,
-	observe,
+	subscribeActiveWatcher,
+	notifyWatchers,
+	flushPendingReactions,
+	batchSignalWrites,
+	trackSignalReads,
+	emitNotification,
 }

package/src/util.ts

@@ -23,6 +23,15 @@ const isAsyncFunction = /*#__PURE__*/ <T>(
 ): fn is (...args: unknown[]) => Promise<T> =>
 	isFunction(fn) && fn.constructor.name === 'AsyncFunction'
 
+const isSyncFunction = /*#__PURE__*/ <T extends unknown & { then?: undefined }>(
+	fn: unknown,
+): fn is (...args: unknown[]) => T =>
+	isFunction(fn) && fn.constructor.name !== 'AsyncFunction'
+
+const isNonNullObject = /*#__PURE__*/ (
+	value: unknown,
+): value is NonNullable<object> => value != null && typeof value === 'object'
+
 const isObjectOfType = /*#__PURE__*/ <T>(
 	value: unknown,
 	type: string,
@@ -38,17 +47,10 @@ const isRecordOrArray = /*#__PURE__*/ <
 	value: unknown,
 ): value is T => isRecord(value) || Array.isArray(value)
 
-const validArrayIndexes = /*#__PURE__*/ (
-	keys: Array<PropertyKey>,
-): number[] | null => {
-	if (!keys.length) return null
-	const indexes = keys.map(k =>
-		isString(k) ? parseInt(k, 10) : isNumber(k) ? k : NaN,
-	)
-	return indexes.every(index => Number.isFinite(index) && index >= 0)
-		? indexes.sort((a, b) => a - b)
-		: null
-}
+const isUniformArray = <T>(
+	value: unknown,
+	guard = (item: T): item is T & {} => item != null,
+): value is T[] => Array.isArray(value) && value.every(guard)
 
 const hasMethod = /*#__PURE__*/ <
 	T extends object & Record<string, (...args: unknown[]) => unknown>,
@@ -64,23 +66,6 @@ const isAbortError = /*#__PURE__*/ (error: unknown): boolean =>
 const toError = /*#__PURE__*/ (reason: unknown): Error =>
 	reason instanceof Error ? reason : Error(String(reason))
 
-const arrayToRecord = /*#__PURE__*/ <T>(array: T[]): Record<string, T> => {
-	const record: Record<string, T> = {}
-	for (let i = 0; i < array.length; i++) record[String(i)] = array[i]
-	return record
-}
-
-const recordToArray = /*#__PURE__*/ <T>(
-	record: Record<string | number, T>,
-): Record<string, T> | T[] => {
-	const indexes = validArrayIndexes(Object.keys(record))
-	if (indexes === null) return record
-
-	const array: T[] = []
-	for (const index of indexes) array.push(record[String(index)])
-	return array
-}
-
 const valueString = /*#__PURE__*/ (value: unknown): string =>
 	isString(value)
 		? `"${value}"`
@@ -97,13 +82,14 @@ export {
 	isSymbol,
 	isFunction,
 	isAsyncFunction,
+	isSyncFunction,
+	isNonNullObject,
 	isObjectOfType,
 	isRecord,
 	isRecordOrArray,
+	isUniformArray,
 	hasMethod,
 	isAbortError,
 	toError,
-	arrayToRecord,
-	recordToArray,
 	valueString,
 }

package/test/batch.test.ts

@@ -1,38 +1,36 @@
 import { describe, expect, test } from 'bun:test'
 import {
-	batch,
-	createComputed,
+	batchSignalWrites,
 	createEffect,
-	createState,
+	Memo,
 	match,
 	resolve,
-} from '..'
+	State,
+} from '../index.ts'
 
 /* === Tests === */
 
 describe('Batch', () => {
 	test('should be triggered only once after repeated state change', () => {
-		const cause = createState(0)
+		const cause = new State(0)
 		let result = 0
 		let count = 0
 		createEffect((): undefined => {
 			result = cause.get()
 			count++
 		})
-		batch(() => {
-			for (let i = 1; i <= 10; i++) {
-				cause.set(i)
-			}
+		batchSignalWrites(() => {
+			for (let i = 1; i <= 10; i++) cause.set(i)
 		})
 		expect(result).toBe(10)
 		expect(count).toBe(2) // + 1 for effect initialization
 	})
 
 	test('should be triggered only once when multiple signals are set', () => {
-		const a = createState(3)
-		const b = createState(4)
-		const c = createState(5)
-		const sum = createComputed(() => a.get() + b.get() + c.get())
+		const a = new State(3)
+		const b = new State(4)
+		const c = new State(5)
+		const sum = new Memo(() => a.get() + b.get() + c.get())
 		let result = 0
 		let count = 0
 		createEffect(() => {
@@ -45,7 +43,7 @@ describe('Batch', () => {
 				err: () => {},
 			})
 		})
-		batch(() => {
+		batchSignalWrites(() => {
 			a.set(6)
 			b.set(8)
 			c.set(10)
@@ -56,10 +54,10 @@ describe('Batch', () => {
 
 	test('should prove example from README works', () => {
 		// State: define an array of Signal<number>
-		const signals = [createState(2), createState(3), createState(5)]
+		const signals = [new State(2), new State(3), new State(5)]
 
 		// Computed: derive a calculation ...
-		const sum = createComputed(() => {
+		const sum = new Memo(() => {
 			const v = signals.reduce((total, v) => total + v.get(), 0)
 			if (!Number.isFinite(v)) throw new Error('Invalid value')
 			return v
@@ -89,7 +87,7 @@ describe('Batch', () => {
 		expect(result).toBe(10)
 
 		// Batch: apply changes to all signals in a single transaction
-		batch(() => {
+		batchSignalWrites(() => {
 			signals.forEach(signal => signal.update(v => v * 2))
 		})
 

package/test/benchmark.test.ts

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