@zeix/cause-effect 0.15.1 → 0.16.0

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

@@ -1,3 +1,8 @@
+/* === Constants === */
+
+// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
+const UNSET: any = Symbol()
+
 /* === Utility Functions === */
 
 const isString = /*#__PURE__*/ (value: unknown): value is string =>
@@ -6,6 +11,9 @@ const isString = /*#__PURE__*/ (value: unknown): value is string =>
 const isNumber = /*#__PURE__*/ (value: unknown): value is number =>
 	typeof value === 'number'
 
+const isSymbol = /*#__PURE__*/ (value: unknown): value is symbol =>
+	typeof value === 'symbol'
+
 const isFunction = /*#__PURE__*/ <T>(
 	fn: unknown,
 ): fn is (...args: unknown[]) => T => typeof fn === 'function'
@@ -24,6 +32,12 @@ const isRecord = /*#__PURE__*/ <T extends Record<string, unknown>>(
 	value: unknown,
 ): value is T => isObjectOfType(value, 'Object')
 
+const isRecordOrArray = /*#__PURE__*/ <
+	T extends Record<string | number, unknown> | ReadonlyArray<unknown>,
+>(
+	value: unknown,
+): value is T => isRecord(value) || Array.isArray(value)
+
 const validArrayIndexes = /*#__PURE__*/ (
 	keys: Array<PropertyKey>,
 ): number[] | null => {
@@ -50,25 +64,50 @@ const isAbortError = /*#__PURE__*/ (error: unknown): boolean =>
 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`)
-		this.name = 'CircularDependencyError'
+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}"`
+		: !!value && typeof value === 'object'
+			? JSON.stringify(value)
+			: String(value)
+
 /* === Exports === */
 
 export {
+	UNSET,
 	isString,
 	isNumber,
+	isSymbol,
 	isFunction,
 	isAsyncFunction,
 	isObjectOfType,
 	isRecord,
-	validArrayIndexes,
+	isRecordOrArray,
 	hasMethod,
 	isAbortError,
 	toError,
-	CircularDependencyError,
+	arrayToRecord,
+	recordToArray,
+	valueString,
 }

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(),
 }