@zeix/cause-effect 0.15.2 → 0.16.1

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,
@@ -70,9 +66,7 @@ const toError = /*#__PURE__*/ (reason: unknown): Error =>
 
 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]
-	}
+	for (let i = 0; i < array.length; i++) record[String(i)] = array[i]
 	return record
 }
 
@@ -83,16 +77,14 @@ const recordToArray = /*#__PURE__*/ <T>(
 	if (indexes === null) return record
 
 	const array: T[] = []
-	for (const index of indexes) {
-		array.push(record[String(index)])
-	}
+	for (const index of indexes) array.push(record[String(index)])
 	return array
 }
 
 const valueString = /*#__PURE__*/ (value: unknown): string =>
 	isString(value)
 		? `"${value}"`
-		: isDefinedObject(value)
+		: !!value && typeof value === 'object'
 			? JSON.stringify(value)
 			: String(value)
 
@@ -105,7 +97,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(),
 }