@zeix/cause-effect 0.14.0 → 0.14.2

package/package.json

@@ -1,14 +1,13 @@
 {
 	"name": "@zeix/cause-effect",
-	"version": "0.14.0",
+	"version": "0.14.2",
 	"author": "Esther Brunner",
 	"main": "index.js",
 	"module": "index.ts",
 	"devDependencies": {
+		"@biomejs/biome": "2.1.4",
 		"@types/bun": "latest",
-		"eslint": "^9.27.0",
-		"random": "^5.4.0",
-		"typescript-eslint": "^8.32.1"
+		"random": "^5.4.1"
 	},
 	"peerDependencies": {
 		"typescript": "^5.6.3"
@@ -25,9 +24,9 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "bun build index.ts --outdir ./ --minify && bunx tsc",
+		"build": "bunx tsc && bun build index.ts --outdir ./ --minify && bun build index.ts --outfile index.dev.js",
 		"test": "bun test",
-		"lint": "bunx eslint src/"
+		"lint": "bunx biome lint --write"
 	},
 	"type": "module",
 	"types": "index.d.ts"

package/src/computed.d.ts

@@ -1,20 +1,14 @@
-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>;
+    then?: undefined;
+}> = ((abort: AbortSignal) => Promise<T>) | (() => 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
@@ -28,4 +22,12 @@ declare const computed: <T extends {}>(fn: ComputedCallback<T>) => Computed<T>;
  * @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, };
+/**
+ * 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>;
+export { TYPE_COMPUTED, computed, isComputed, isComputedCallback, type Computed, type ComputedCallback, };

package/src/computed.ts

@@ -1,6 +1,18 @@
-import { isAsyncFunction, isObjectOfType } from './util'
-import { type MemoCallback, memo } from './memo'
-import { type TaskCallback, task } from './task'
+import {
+	flush,
+	notify,
+	observe,
+	subscribe,
+	type Watcher,
+	watch,
+} from './scheduler'
+import { UNSET } from './signal'
+import {
+	CircularDependencyError,
+	isFunction,
+	isObjectOfType,
+	toError,
+} from './util'
 
 /* === Types === */
 
@@ -8,9 +20,9 @@ type Computed<T extends {}> = {
 	[Symbol.toStringTag]: 'Computed'
 	get(): T
 }
-type ComputedCallback<T extends {} & { then?: void }> =
-	| TaskCallback<T>
-	| MemoCallback<T>
+type ComputedCallback<T extends {} & { then?: undefined }> =
+	| ((abort: AbortSignal) => Promise<T>)
+	| (() => T)
 
 /* === Constants === */
 
@@ -21,16 +33,116 @@ 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
  */
-const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> =>
-	isAsyncFunction<T>(fn) ? task<T>(fn) : memo<T>(fn as MemoCallback<T>)
+const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
+	const watchers: Set<Watcher> = new Set()
+
+	// Internal state
+	let value: T = UNSET
+	let error: Error | undefined
+	let controller: AbortController | undefined
+	let dirty = true
+	let changed = false
+	let computing = false
+
+	// Functions to update internal state
+	const ok = (v: T): undefined => {
+		if (!Object.is(v, value)) {
+			value = v
+			changed = true
+		}
+		error = undefined
+		dirty = false
+	}
+	const nil = (): undefined => {
+		changed = UNSET !== value
+		value = UNSET
+		error = undefined
+	}
+	const err = (e: unknown): undefined => {
+		const newError = toError(e)
+		changed =
+			!error ||
+			newError.name !== error.name ||
+			newError.message !== error.message
+		value = UNSET
+		error = newError
+	}
+	const settle =
+		<T>(settleFn: (arg: T) => void) =>
+		(arg: T) => {
+			computing = false
+			controller = undefined
+			settleFn(arg)
+			if (changed) notify(watchers)
+		}
+
+	// Own watcher: called when notified from sources (push)
+	const mark = watch(() => {
+		dirty = true
+		controller?.abort('Aborted because source signal changed')
+		if (watchers.size) notify(watchers)
+		else mark.cleanup()
+	})
+
+	// Called when requested by dependencies (pull)
+	const compute = () =>
+		observe(() => {
+			if (computing) throw new CircularDependencyError('computed')
+			changed = false
+			if (isFunction(fn) && fn.constructor.name === 'AsyncFunction') {
+				if (controller) return value // return current value until promise resolves
+				controller = new AbortController()
+				controller.signal.addEventListener(
+					'abort',
+					() => {
+						computing = false
+						controller = undefined
+						compute() // retry
+					},
+					{
+						once: true,
+					},
+				)
+			}
+			let result: T | Promise<T>
+			computing = true
+			try {
+				result = controller ? fn(controller.signal) : (fn as () => T)()
+			} catch (e) {
+				if (e instanceof DOMException && e.name === 'AbortError') nil()
+				else err(e)
+				computing = false
+				return
+			}
+			if (result instanceof Promise) result.then(settle(ok), settle(err))
+			else if (null == result || UNSET === result) nil()
+			else ok(result)
+			computing = false
+		}, mark)
+
+	const c: Computed<T> = {
+		[Symbol.toStringTag]: TYPE_COMPUTED,
+
+		/**
+		 * Get the current value of the computed
+		 *
+		 * @since 0.9.0
+		 * @returns {T} - current value of the computed
+		 */
+		get: (): T => {
+			subscribe(watchers)
+			flush()
+			if (dirty) compute()
+			if (error) throw error
+			return value
+		},
+	}
+	return c
+}
 
 /**
  * Check if a value is a computed state
@@ -43,12 +155,24 @@ const isComputed = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
 ): value is Computed<T> => isObjectOfType(value, TYPE_COMPUTED)
 
+/**
+ * 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
+ */
+const isComputedCallback = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is ComputedCallback<T> => isFunction(value) && value.length < 2
+
 /* === Exports === */
 
 export {
-	type Computed,
-	type ComputedCallback,
 	TYPE_COMPUTED,
 	computed,
 	isComputed,
+	isComputedCallback,
+	type Computed,
+	type ComputedCallback,
 }

package/src/effect.d.ts

@@ -1,19 +1,17 @@
-import { type Signal } from './signal';
 import { type Cleanup } from './scheduler';
-type EffectMatcher<S extends Signal<{}>[]> = {
+import { type Signal, type SignalValues } from './signal';
+type EffectMatcher<S extends Signal<unknown & {}>[]> = {
     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;
+    ok: (...values: SignalValues<S>) => Cleanup | undefined;
+    err?: (...errors: Error[]) => Cleanup | undefined;
+    nil?: () => Cleanup | undefined;
 };
 /**
  * Define what happens when a reactive state changes
  *
  * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @param {EffectMatcher<S> | (() => Cleanup | undefined)} matcher - effect matcher or callback
  * @returns {Cleanup} - cleanup function for the effect
  */
-declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | Cleanup)): Cleanup;
+declare function effect<S extends Signal<unknown & {}>[]>(matcher: EffectMatcher<S> | (() => Cleanup | undefined)): Cleanup;
 export { type EffectMatcher, effect };

package/src/effect.ts

@@ -1,23 +1,14 @@
-import { type Signal, UNSET } from './signal'
-import {
-	CircularDependencyError,
-	isFunction,
-	toError,
-	isAbortError,
-} from './util'
-import { watch, type Cleanup, type Watcher } from './scheduler'
+import { type Cleanup, observe, watch } from './scheduler'
+import { type Signal, type SignalValues, UNSET } from './signal'
+import { CircularDependencyError, isFunction, toError } from './util'
 
 /* === Types === */
 
-type EffectMatcher<S extends Signal<{}>[]> = {
+type EffectMatcher<S extends Signal<unknown & {}>[]> = {
 	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
+	ok: (...values: SignalValues<S>) => Cleanup | undefined
+	err?: (...errors: Error[]) => Cleanup | undefined
+	nil?: () => Cleanup | undefined
 }
 
 /* === Functions === */
@@ -26,68 +17,62 @@ type EffectMatcher<S extends Signal<{}>[]> = {
  * Define what happens when a reactive state changes
  *
  * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
+ * @param {EffectMatcher<S> | (() => Cleanup | undefined)} matcher - effect matcher or callback
  * @returns {Cleanup} - cleanup function for the effect
  */
-function effect<S extends Signal<{}>[]>(
-	matcher: EffectMatcher<S> | (() => void | Cleanup),
+function effect<S extends Signal<unknown & {}>[]>(
+	matcher: EffectMatcher<S> | (() => Cleanup | undefined),
 ): Cleanup {
 	const {
 		signals,
 		ok,
-		err = console.error,
-		nil = () => {},
+		err = (error: Error): undefined => {
+			console.error(error)
+		},
+		nil = (): undefined => {},
 	} = isFunction(matcher)
 		? { signals: [] as unknown as S, ok: matcher }
 		: matcher
+
 	let running = false
-	const run = (() =>
-		watch(() => {
+	const run = watch(() =>
+		observe(() => {
 			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
-				}
 
+			// Pure part
+			const errors: Error[] = []
+			let pending = false
+			const values = signals.map(signal => {
 				try {
-					cleanup = suspense
-						? nil()
-						: errors.length
-							? err(...errors)
-							: ok(...values)
+					const value = signal.get()
+					if (value === UNSET) pending = true
+					return value
 				} catch (e) {
-					if (isAbortError(e)) throw e
-					const error = toError(e)
-					cleanup = err(error)
+					errors.push(toError(e))
+					return UNSET
 				}
+			}) as SignalValues<S>
+
+			// Effectful part
+			let cleanup: Cleanup | undefined
+			try {
+				cleanup = pending
+					? nil()
+					: errors.length
+						? err(...errors)
+						: ok(...values)
 			} catch (e) {
-				err(toError(e))
+				cleanup = err(toError(e))
+			} finally {
+				if (isFunction(cleanup)) run.off(cleanup)
 			}
-			if (isFunction(cleanup)) run.cleanups.add(cleanup)
+
 			running = false
-		}, run)) as Watcher
-	run.cleanups = new Set<Cleanup>()
+		}, run),
+	)
 	run()
-	return () => {
-		run.cleanups.forEach(fn => fn())
-		run.cleanups.clear()
-	}
+	return () => run.cleanup()
 }
 
 /* === Exports === */

package/src/scheduler.d.ts

@@ -1,9 +1,18 @@
 type Cleanup = () => void;
 type Watcher = {
     (): void;
-    cleanups: Set<Cleanup>;
+    off(cleanup: Cleanup): void;
+    cleanup(): void;
 };
-type Updater = <T>() => T | boolean | void;
+type Updater = <T>() => T | boolean | undefined;
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} notice - function to be called when the state changes
+ * @returns {Watcher} - watcher object with off and cleanup methods
+ */
+declare const watch: (notice: () => void) => Watcher;
 /**
  * Add active watcher to the Set of watchers
  *
@@ -30,9 +39,9 @@ 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)
+ * @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)
  */
-declare const watch: (run: () => void, mark?: Watcher) => void;
+declare const observe: (run: () => void, watcher?: Watcher) => void;
 /**
  * Enqueue a function to be executed on the next animation frame
  *
@@ -42,5 +51,5 @@ declare const watch: (run: () => void, mark?: Watcher) => void;
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
  * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-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, };
+declare const enqueue: <T>(fn: Updater, dedupe?: symbol) => Promise<boolean | T | undefined>;
+export { type Cleanup, type Watcher, type Updater, subscribe, notify, flush, batch, watch, observe, enqueue, };

package/src/scheduler.ts

@@ -4,10 +4,11 @@ type Cleanup = () => void
 
 type Watcher = {
 	(): void
-	cleanups: Set<Cleanup>
+	off(cleanup: Cleanup): void
+	cleanup(): void
 }
 
-type Updater = <T>() => T | boolean | void
+type Updater = <T>() => T | boolean | undefined
 
 /* === Internal === */
 
@@ -26,8 +27,8 @@ const updateDOM = () => {
 	requestId = undefined
 	const updates = Array.from(updateMap.values())
 	updateMap.clear()
-	for (const fn of updates) {
-		fn()
+	for (const update of updates) {
+		update()
 	}
 }
 
@@ -41,17 +42,38 @@ queueMicrotask(updateDOM)
 
 /* === Functions === */
 
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} notice - function to be called when the state changes
+ * @returns {Watcher} - watcher object with off and cleanup methods
+ */
+const watch = (notice: () => void): Watcher => {
+	const cleanups = new Set<Cleanup>()
+	const w = notice as Partial<Watcher>
+	w.off = (on: Cleanup) => {
+		cleanups.add(on)
+	}
+	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 (!active) console.warn('Calling .get() outside of a reactive context')
 	if (active && !watchers.has(active)) {
 		const watcher = active
 		watchers.add(watcher)
-		active.cleanups.add(() => {
+		active.off(() => {
 			watchers.delete(watcher)
 		})
 	}
@@ -63,9 +85,9 @@ const subscribe = (watchers: Set<Watcher>) => {
  * @param {Set<Watcher>} watchers - watchers of the signal
  */
 const notify = (watchers: Set<Watcher>) => {
-	for (const mark of watchers) {
-		if (batchDepth) pending.add(mark)
-		else mark()
+	for (const watcher of watchers) {
+		if (batchDepth) pending.add(watcher)
+		else watcher()
 	}
 }
 
@@ -76,8 +98,8 @@ const flush = () => {
 	while (pending.size) {
 		const watchers = Array.from(pending)
 		pending.clear()
-		for (const mark of watchers) {
-			mark()
+		for (const watcher of watchers) {
+			watcher()
 		}
 	}
 }
@@ -101,11 +123,11 @@ const batch = (fn: () => 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)
+ * @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 watch = (run: () => void, mark?: Watcher): void => {
+const observe = (run: () => void, watcher?: Watcher): void => {
 	const prev = active
-	active = mark
+	active = watcher
 	try {
 		run()
 	} finally {
@@ -123,8 +145,8 @@ const watch = (run: () => void, mark?: Watcher): void => {
  * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
 const enqueue = <T>(fn: Updater, dedupe?: symbol) =>
-	new Promise<T | boolean | void>((resolve, reject) => {
-		updateMap.set(dedupe || Symbol(), () => {
+	new Promise<T | boolean | undefined>((resolve, reject) => {
+		updateMap.set(dedupe || Symbol(), (): undefined => {
 			try {
 				resolve(fn())
 			} catch (error) {
@@ -145,5 +167,6 @@ export {
 	flush,
 	batch,
 	watch,
+	observe,
 	enqueue,
 }

package/src/signal.d.ts

@@ -1,8 +1,11 @@
-import { type ComputedCallback } from './computed';
+import { type ComputedCallback, isComputedCallback } from './computed';
 type Signal<T extends {}> = {
     get(): T;
 };
 type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
+type SignalValues<S extends Signal<unknown & {}>[]> = {
+    [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
+};
 declare const UNSET: any;
 /**
  * Check whether a value is a Signal or not
@@ -12,14 +15,6 @@ declare const UNSET: any;
  * @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
  *
@@ -28,4 +23,4 @@ declare const isComputedCallback: <T extends {}>(value: unknown) => value is Com
  * @returns {Signal<T>} - converted Signal
  */
 declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
-export { type Signal, type MaybeSignal, UNSET, isSignal, isComputedCallback, toSignal, };
+export { type Signal, type MaybeSignal, type SignalValues, UNSET, isSignal, isComputedCallback, toSignal, };

package/src/signal.ts

@@ -1,10 +1,10 @@
-import { isState, state } from './state'
 import {
 	type ComputedCallback,
-	isComputed,
 	computed,
+	isComputed,
+	isComputedCallback,
 } from './computed'
-import { isFunction } from './util'
+import { isState, state } from './state'
 
 /* === Types === */
 
@@ -13,11 +13,16 @@ type Signal<T extends {}> = {
 }
 type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
 
+type SignalValues<S extends Signal<unknown & {}>[]> = {
+	[K in keyof S]: S[K] extends Signal<infer T> ? T : never
+}
+
 /* === Constants === */
 
+// biome-ignore lint/suspicious/noExplicitAny: Deliberately using any to be used as a placeholder value in any signal
 const UNSET: any = Symbol()
 
-/* === Exported Functions === */
+/* === Functions === */
 
 /**
  * Check whether a value is a Signal or not
@@ -30,17 +35,6 @@ const isSignal = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
 ): value is Signal<T> => isState(value) || isComputed(value)
 
-/**
- * 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
- */
-const isComputedCallback = /*#__PURE__*/ <T extends {}>(
-	value: unknown,
-): value is ComputedCallback<T> => isFunction(value) && value.length < 2
-
 /**
  * Convert a value to a Signal if it's not already a Signal
  *
@@ -62,6 +56,7 @@ const toSignal = /*#__PURE__*/ <T extends {}>(
 export {
 	type Signal,
 	type MaybeSignal,
+	type SignalValues,
 	UNSET,
 	isSignal,
 	isComputedCallback,

package/src/state.d.ts

@@ -4,6 +4,7 @@ type State<T extends {}> = {
     set(v: T): void;
     update(fn: (v: T) => T): void;
 };
+declare const TYPE_STATE = "State";
 /**
  * Create a new state signal
  *
@@ -20,4 +21,4 @@ declare const state: <T extends {}>(initialValue: T) => State<T>;
  * @returns {boolean} - true if the value is a State instance, false otherwise
  */
 declare const isState: <T extends {}>(value: unknown) => value is State<T>;
-export { type State, state, isState };
+export { type State, TYPE_STATE, state, isState };

package/src/state.ts

@@ -86,4 +86,4 @@ const isState = /*#__PURE__*/ <T extends {}>(
 
 /* === Exports === */
 
-export { type State, state, isState }
+export { type State, TYPE_STATE, state, isState }