@zeix/cause-effect 0.13.1 → 0.14.0

package/package.json

@@ -1,31 +1,34 @@
 {
-  "name": "@zeix/cause-effect",
-  "version": "0.13.1",
-  "author": "Esther Brunner",
-  "main": "index.js",
-  "module": "index.ts",
-  "devDependencies": {
-    "@types/bun": "latest",
-    "random": "^5.3.0"
-  },
-  "peerDependencies": {
-    "typescript": "^5.6.3"
-  },
-  "description": "Cause & Effect - reactive state management with signals.",
-  "license": "MIT",
-  "keywords": [
-    "Cause & Effect",
-    "Reactivity",
-    "Signals",
-    "Effects"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "bun build index.ts --outdir ./ --minify && bunx tsc",
-    "test": "bun test"
-  },
-  "type": "module",
-  "types": "index.d.ts"
+	"name": "@zeix/cause-effect",
+	"version": "0.14.0",
+	"author": "Esther Brunner",
+	"main": "index.js",
+	"module": "index.ts",
+	"devDependencies": {
+		"@types/bun": "latest",
+		"eslint": "^9.27.0",
+		"random": "^5.4.0",
+		"typescript-eslint": "^8.32.1"
+	},
+	"peerDependencies": {
+		"typescript": "^5.6.3"
+	},
+	"description": "Cause & Effect - reactive state management with signals.",
+	"license": "MIT",
+	"keywords": [
+		"Cause & Effect",
+		"Reactivity",
+		"Signals",
+		"Effects"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun build index.ts --outdir ./ --minify && bunx tsc",
+		"test": "bun test",
+		"lint": "bunx eslint src/"
+	},
+	"type": "module",
+	"types": "index.d.ts"
 }

package/src/computed.d.ts

@@ -0,0 +1,31 @@
+import { type MemoCallback } from './memo';
+import { type TaskCallback } from './task';
+type Computed<T extends {}> = {
+    [Symbol.toStringTag]: 'Computed';
+    get(): T;
+};
+type ComputedCallback<T extends {} & {
+    then?: void;
+}> = TaskCallback<T> | MemoCallback<T>;
+declare const TYPE_COMPUTED = "Computed";
+/**
+ * Create a derived signal from existing signals
+ *
+ * This function delegates to either memo() for synchronous computations
+ * or task() for asynchronous computations, providing better performance
+ * for each case.
+ *
+ * @since 0.9.0
+ * @param {ComputedCallback<T>} fn - computation callback function
+ * @returns {Computed<T>} - Computed signal
+ */
+declare const computed: <T extends {}>(fn: ComputedCallback<T>) => Computed<T>;
+/**
+ * Check if a value is a computed state
+ *
+ * @since 0.9.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a computed state, false otherwise
+ */
+declare const isComputed: <T extends {}>(value: unknown) => value is Computed<T>;
+export { type Computed, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, };

package/src/computed.ts

@@ -0,0 +1,54 @@
+import { isAsyncFunction, isObjectOfType } from './util'
+import { type MemoCallback, memo } from './memo'
+import { type TaskCallback, task } from './task'
+
+/* === Types === */
+
+type Computed<T extends {}> = {
+	[Symbol.toStringTag]: 'Computed'
+	get(): T
+}
+type ComputedCallback<T extends {} & { then?: void }> =
+	| TaskCallback<T>
+	| MemoCallback<T>
+
+/* === Constants === */
+
+const TYPE_COMPUTED = 'Computed'
+
+/* === Functions === */
+
+/**
+ * Create a derived signal from existing signals
+ *
+ * This function delegates to either memo() for synchronous computations
+ * or task() for asynchronous computations, providing better performance
+ * for each case.
+ *
+ * @since 0.9.0
+ * @param {ComputedCallback<T>} fn - computation callback function
+ * @returns {Computed<T>} - Computed signal
+ */
+const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> =>
+	isAsyncFunction<T>(fn) ? task<T>(fn) : memo<T>(fn as MemoCallback<T>)
+
+/**
+ * Check if a value is a computed state
+ *
+ * @since 0.9.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a computed state, false otherwise
+ */
+const isComputed = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is Computed<T> => isObjectOfType(value, TYPE_COMPUTED)
+
+/* === Exports === */
+
+export {
+	type Computed,
+	type ComputedCallback,
+	TYPE_COMPUTED,
+	computed,
+	isComputed,
+}

package/src/effect.d.ts

@@ -0,0 +1,19 @@
+import { type Signal } from './signal';
+import { type Cleanup } from './scheduler';
+type EffectMatcher<S extends Signal<{}>[]> = {
+    signals: S;
+    ok: (...values: {
+        [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
+    }) => void | Cleanup;
+    err?: (...errors: Error[]) => void | Cleanup;
+    nil?: () => void | Cleanup;
+};
+/**
+ * Define what happens when a reactive state changes
+ *
+ * @since 0.1.0
+ * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @returns {Cleanup} - cleanup function for the effect
+ */
+declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | Cleanup)): Cleanup;
+export { type EffectMatcher, effect };

package/src/effect.ts

@@ -0,0 +1,95 @@
+import { type Signal, UNSET } from './signal'
+import {
+	CircularDependencyError,
+	isFunction,
+	toError,
+	isAbortError,
+} from './util'
+import { watch, type Cleanup, type Watcher } from './scheduler'
+
+/* === Types === */
+
+type EffectMatcher<S extends Signal<{}>[]> = {
+	signals: S
+	ok: (
+		...values: {
+			[K in keyof S]: S[K] extends Signal<infer T> ? T : never
+		}
+	) => void | Cleanup
+	err?: (...errors: Error[]) => void | Cleanup
+	nil?: () => void | Cleanup
+}
+
+/* === Functions === */
+
+/**
+ * Define what happens when a reactive state changes
+ *
+ * @since 0.1.0
+ * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @returns {Cleanup} - cleanup function for the effect
+ */
+function effect<S extends Signal<{}>[]>(
+	matcher: EffectMatcher<S> | (() => void | Cleanup),
+): Cleanup {
+	const {
+		signals,
+		ok,
+		err = console.error,
+		nil = () => {},
+	} = isFunction(matcher)
+		? { signals: [] as unknown as S, ok: matcher }
+		: matcher
+	let running = false
+	const run = (() =>
+		watch(() => {
+			if (running) throw new CircularDependencyError('effect')
+			running = true
+			let cleanup: void | Cleanup = undefined
+			try {
+				const errors: Error[] = []
+				let suspense = false
+				const values = signals.map(signal => {
+					try {
+						const value = signal.get()
+						if (value === UNSET) suspense = true
+						return value
+					} catch (e) {
+						if (isAbortError(e)) throw e
+						errors.push(toError(e))
+						return UNSET
+					}
+				}) as {
+					[K in keyof S]: S[K] extends Signal<infer T extends {}>
+						? T
+						: never
+				}
+
+				try {
+					cleanup = suspense
+						? nil()
+						: errors.length
+							? err(...errors)
+							: ok(...values)
+				} catch (e) {
+					if (isAbortError(e)) throw e
+					const error = toError(e)
+					cleanup = err(error)
+				}
+			} catch (e) {
+				err(toError(e))
+			}
+			if (isFunction(cleanup)) run.cleanups.add(cleanup)
+			running = false
+		}, run)) as Watcher
+	run.cleanups = new Set<Cleanup>()
+	run()
+	return () => {
+		run.cleanups.forEach(fn => fn())
+		run.cleanups.clear()
+	}
+}
+
+/* === Exports === */
+
+export { type EffectMatcher, effect }

package/src/memo.d.ts

@@ -0,0 +1,13 @@
+import { type Computed } from './computed';
+type MemoCallback<T extends {} & {
+    then?: void;
+}> = () => T;
+/**
+ * Create a derived signal for synchronous computations
+ *
+ * @since 0.14.0
+ * @param {MemoCallback<T>} fn - synchronous computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+declare const memo: <T extends {}>(fn: MemoCallback<T>) => Computed<T>;
+export { type MemoCallback, memo };

package/src/memo.ts

@@ -0,0 +1,91 @@
+import { UNSET } from './signal'
+import { CircularDependencyError } from './util'
+import {
+	type Cleanup,
+	type Watcher,
+	flush,
+	notify,
+	subscribe,
+	watch,
+} from './scheduler'
+import { type Computed, TYPE_COMPUTED } from './computed'
+
+/* === Types === */
+
+type MemoCallback<T extends {} & { then?: void }> = () => T
+
+/* === Functions === */
+
+/**
+ * Create a derived signal for synchronous computations
+ *
+ * @since 0.14.0
+ * @param {MemoCallback<T>} fn - synchronous computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+const memo = <T extends {}>(fn: MemoCallback<T>): Computed<T> => {
+	const watchers: Set<Watcher> = new Set()
+
+	// Internal state - simplified for sync only
+	let value: T = UNSET
+	let error: Error | undefined
+	let dirty = true
+	let computing = false
+
+	// Called when notified from sources (push)
+	const mark = (() => {
+		dirty = true
+		if (watchers.size) {
+			notify(watchers)
+		} else {
+			mark.cleanups.forEach(fn => fn())
+			mark.cleanups.clear()
+		}
+	}) as Watcher
+	mark.cleanups = new Set<Cleanup>()
+
+	// Called when requested by dependencies (pull)
+	const compute = () =>
+		watch(() => {
+			if (computing) throw new CircularDependencyError('memo')
+			computing = true
+			try {
+				const result = fn()
+				if (null == result || UNSET === result) {
+					value = UNSET
+					error = undefined
+				} else {
+					value = result
+					dirty = false
+					error = undefined
+				}
+			} catch (e) {
+				value = UNSET
+				error = e instanceof Error ? e : new Error(String(e))
+			} finally {
+				computing = false
+			}
+		}, mark)
+
+	const c: Computed<T> = {
+		[Symbol.toStringTag]: TYPE_COMPUTED,
+
+		/**
+		 * Get the current value of the computed
+		 *
+		 * @returns {T} - current value of the computed
+		 */
+		get: (): T => {
+			subscribe(watchers)
+			flush()
+			if (dirty) compute()
+			if (error) throw error
+			return value
+		},
+	}
+	return c
+}
+
+/* === Exports === */
+
+export { type MemoCallback, memo }

package/{lib → src}/scheduler.d.ts

@@ -1,42 +1,46 @@
-export type EnqueueDedupe = [Element, string];
-export type Watcher = {
+type Cleanup = () => void;
+type Watcher = {
     (): void;
-    cleanups: Set<() => void>;
+    cleanups: Set<Cleanup>;
 };
-export type Updater = <T>() => T | boolean | void;
+type Updater = <T>() => T | boolean | void;
 /**
  * Add active watcher to the Set of watchers
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export declare const subscribe: (watchers: Set<Watcher>) => void;
+declare const subscribe: (watchers: Set<Watcher>) => void;
 /**
  * Add watchers to the pending set of change notifications
  *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export declare const notify: (watchers: Set<Watcher>) => void;
+declare const notify: (watchers: Set<Watcher>) => void;
 /**
  * Flush all pending changes to notify watchers
  */
-export declare const flush: () => void;
+declare const flush: () => void;
 /**
  * Batch multiple changes in a single signal graph and DOM update cycle
  *
  * @param {() => void} fn - function with multiple signal writes to be batched
  */
-export declare const batch: (fn: () => void) => void;
+declare const batch: (fn: () => void) => void;
 /**
  * Run a function in a reactive context
  *
  * @param {() => void} run - function to run the computation or effect
  * @param {Watcher} mark - 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)
  */
-export declare const watch: (run: () => void, mark?: Watcher) => void;
+declare const watch: (run: () => void, mark?: Watcher) => void;
 /**
  * Enqueue a function to be executed on the next animation frame
  *
+ * If the same Symbol is provided for multiple calls before the next animation frame,
+ * only the latest call will be executed (deduplication).
+ *
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
- * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
+ * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-export declare const enqueue: <T>(fn: Updater, dedupe?: EnqueueDedupe) => Promise<boolean | void | T>;
+declare const enqueue: <T>(fn: Updater, dedupe?: symbol) => Promise<boolean | void | T>;
+export { type Cleanup, type Watcher, type Updater, subscribe, notify, flush, batch, watch, enqueue, };

package/{lib → src}/scheduler.ts

@@ -1,13 +1,13 @@
 /* === Types === */
 
-export type EnqueueDedupe = [Element, string]
+type Cleanup = () => void
 
-export type Watcher = {
-	(): void,
-	cleanups: Set<() => void>
+type Watcher = {
+	(): void
+	cleanups: Set<Cleanup>
 }
 
-export type Updater = <T>() => T | boolean | void
+type Updater = <T>() => T | boolean | void
 
 /* === Internal === */
 
@@ -18,8 +18,8 @@ let active: Watcher | undefined
 const pending = new Set<Watcher>()
 let batchDepth = 0
 
-// Map of DOM elements to update functions
-const updateMap = new Map<EnqueueDedupe, () => void>()
+// Map of deduplication symbols to update functions (using Symbol keys prevents unintended overwrites)
+const updateMap = new Map<symbol, Updater>()
 let requestId: number | undefined
 
 const updateDOM = () => {
@@ -32,21 +32,21 @@ const updateDOM = () => {
 }
 
 const requestTick = () => {
-    if (requestId) cancelAnimationFrame(requestId)
-    requestId = requestAnimationFrame(updateDOM)
+	if (requestId) cancelAnimationFrame(requestId)
+	requestId = requestAnimationFrame(updateDOM)
 }
 
 // Initial render when the call stack is empty
 queueMicrotask(updateDOM)
 
-/* === Exported Functions === */
+/* === Functions === */
 
 /**
  * Add active watcher to the Set of watchers
- * 
+ *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const subscribe = (watchers: Set<Watcher>) => {
+const subscribe = (watchers: Set<Watcher>) => {
 	// if (!active) console.warn('Calling .get() outside of a reactive context')
 	if (active && !watchers.has(active)) {
 		const watcher = active
@@ -59,51 +59,51 @@ export const subscribe = (watchers: Set<Watcher>) => {
 
 /**
  * Add watchers to the pending set of change notifications
- * 
+ *
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
-export const notify = (watchers: Set<Watcher>) => {
+const notify = (watchers: Set<Watcher>) => {
 	for (const mark of watchers) {
-        if (batchDepth) pending.add(mark)
+		if (batchDepth) pending.add(mark)
 		else mark()
-    }
+	}
 }
 
 /**
  * Flush all pending changes to notify watchers
  */
-export const flush = () => {
-    while (pending.size) {
-        const watchers = Array.from(pending)
-        pending.clear()
-        for (const mark of watchers) {
-            mark()
-        }
-    }
+const flush = () => {
+	while (pending.size) {
+		const watchers = Array.from(pending)
+		pending.clear()
+		for (const mark of watchers) {
+			mark()
+		}
+	}
 }
 
 /**
  * Batch multiple changes in a single signal graph and DOM update cycle
- * 
+ *
  * @param {() => void} fn - function with multiple signal writes to be batched
  */
-export const batch = (fn: () => void) => {
+const batch = (fn: () => void) => {
 	batchDepth++
 	try {
 		fn()
 	} finally {
 		flush()
-        batchDepth--
-    }
+		batchDepth--
+	}
 }
 
 /**
  * Run a function in a reactive context
- * 
+ *
  * @param {() => void} run - function to run the computation or effect
  * @param {Watcher} mark - 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)
  */
-export const watch = (run: () => void, mark?: Watcher): void => {
+const watch = (run: () => void, mark?: Watcher): void => {
 	const prev = active
 	active = mark
 	try {
@@ -115,23 +115,35 @@ export const watch = (run: () => void, mark?: Watcher): void => {
 
 /**
  * Enqueue a function to be executed on the next animation frame
- * 
+ *
+ * If the same Symbol is provided for multiple calls before the next animation frame,
+ * only the latest call will be executed (deduplication).
+ *
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
- * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
+ * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-export const enqueue = <T>(
-    fn: Updater,
-    dedupe?: EnqueueDedupe
-) => new Promise<T | boolean | void>((resolve, reject) => {
-    const wrappedCallback = () => {
-        try {
-            resolve(fn())
-        } catch (error) {
-            reject(error)
-        }
-    }
-    if (dedupe) {
-        updateMap.set(dedupe, wrappedCallback)
-    }
-    requestTick()
-})
+const enqueue = <T>(fn: Updater, dedupe?: symbol) =>
+	new Promise<T | boolean | void>((resolve, reject) => {
+		updateMap.set(dedupe || Symbol(), () => {
+			try {
+				resolve(fn())
+			} catch (error) {
+				reject(error)
+			}
+		})
+		requestTick()
+	})
+
+/* === Exports === */
+
+export {
+	type Cleanup,
+	type Watcher,
+	type Updater,
+	subscribe,
+	notify,
+	flush,
+	batch,
+	watch,
+	enqueue,
+}

package/src/signal.d.ts

@@ -0,0 +1,31 @@
+import { type ComputedCallback } from './computed';
+type Signal<T extends {}> = {
+    get(): T;
+};
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
+declare const UNSET: any;
+/**
+ * Check whether a value is a Signal or not
+ *
+ * @since 0.9.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a Signal, false otherwise
+ */
+declare const isSignal: <T extends {}>(value: unknown) => value is Signal<T>;
+/**
+ * Check if the provided value is a callback that may be used as input for toSignal() to derive a computed state
+ *
+ * @since 0.12.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
+ */
+declare const isComputedCallback: <T extends {}>(value: unknown) => value is ComputedCallback<T>;
+/**
+ * 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
+ */
+declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
+export { type Signal, type MaybeSignal, UNSET, isSignal, isComputedCallback, toSignal, };