@zeix/cause-effect 0.10.0 → 0.11.0

package/README.md

@@ -1,14 +1,48 @@
 # Cause & Effect
 
-Version 0.10.0
+Version 0.11.0
 
-**Cause & Effect** - efficient state management with signals that sync instantly and reactively across your application.
+**Cause & Effect** is a lightweight, reactive state management library for JavaScript applications. It uses the concept of signals to create a predictable and efficient data flow in your app.
+
+## What is Cause & Effect?
+
+**Cause & Effect** provides a simple way to manage application state using signals. Signals are containers for values that can change over time. When a signal's value changes, it automatically updates all parts of your app that depend on it, ensuring your UI stays in sync with your data.
+
+## Why Cause & Effect?
+
+- **Simplicity**: Easy to learn and use, with a small API surface.
+- **Performance**: Efficient updates that only recompute what's necessary.
+- **Type Safety**: Full TypeScript support for robust applications.
+- **Flexibility**: Works well with any UI framework or vanilla JavaScript.
+- **Lightweight**: Around 1kB gzipped over the wire.
 
 ## Key Features
 
-* **Efficient State Management**: Use lightweight signals for state updates that automatically notify dependents when needed.
-* **Support for Asynchronous Operations**: Handle state updates smoothly, even when dealing with network requests or Promise-based libraries, without disrupting reactivity.
-* **Memoized Computed Signals**: Optionally create derived values that are cached and automatically recalculated when source data changes.
+- 🚀 Efficient state management with automatic dependency tracking
+- ⏳ Built-in support for async operations
+- 🧠 Memoized computed values
+- 🛡️ Type-safe and non-nullable signals
+- 🎭 Declarative error and pending state handling
+
+## Quick Example
+
+```js
+import { state, computed, effect } from '@zeix/cause-effect'
+
+// Create a state signal
+const count = state(0)
+
+// Create a computed signal
+const doubleCount = computed(() => count.get() * 2)
+
+// Create an effect
+effect(() => {
+    console.log(`Count: ${count.get()}, Double: ${doubleCount.get()}`)
+})
+
+// Update the state
+count.set(5) // Logs: "Count: 5, Double: 10"
+```
 
 ## Installation
 
@@ -71,7 +105,7 @@ document.querySelector('button.increment')
 
 Async computed signals are as straight forward as their sync counterparts. Just create the computed signal with an async function.
 
-**Caution**: You can't use the `.map()` method to create an async computed signal. And async computed signals will return `undefined` until the Promise is resolved.
+**Caution**: You can't use the `.map()` method to create an async computed signal. And async computed signals will return a Symbol `UNSET` until the Promise is resolved.
 
 ```js
 import { state, computed, effect } from '@zeix/cause-effect'
@@ -82,24 +116,44 @@ const entryData = computed(async () => {
     if (!response.ok) return new Error(`Failed to fetch data: ${response.statusText}`)
     return response.json()
 })
-effect(() => {
-    let data
-    try {
-        data = entryData.get()
-    } catch (error) {
-        console.error(error.message) // logs the error message if an error ocurred
-        return
-    }
-    if (null == data) return // doesn't do anything while we are still waiting for the data
-    document.querySelector('.entry h2').textContent = data.title
-    document.querySelector('.entry p').textContent = data.description
-})
 // Updates h1 and p of the entry as soon as fetched data for entry becomes available
 document.querySelector('button.next')
     .addEventListener('click', () => entryId.update(v => ++v))
 // Click on button updates h1 and p of the entry as soon as fetched data for the next entry is loaded
 ```
 
+### Handling Unset Values and Errors in Effects
+
+Computations can fail and throw errors. Promises may not have resolved yet when you try to access their value. **Cause & Effect makes it easy to deal with errors and unresolved async functions.** Computed functions will catch errors and re-throw them when you access their values.
+
+**Effects** are where you handle different cases:
+
+```js
+const h2 = document.querySelector('.entry h2')
+const p = document.querySelector('.entry p')
+effect({
+
+    // Handle pending states while fetching data
+    nil: () => {
+        h2.textContent = 'Loading...'
+    },
+
+    // Handle errors
+    err: (error) => {
+        h2.textContent = 'Oops, Something Went Wrong'
+        p.textContent = error.message
+    },
+
+    // Happy path, data is entryData.get()
+    ok: (data) => {
+        h2.textContent = data.title
+        p.textContent = data.description
+    }
+}, entryData) // assuming an `entryData` async computed signal as in the example above
+```
+
+Instead of a single callback function, provide an object with `ok` (required), `err` and `nil` keys (both optional) and Cause & Effect will take care of anything that might go wrong with the listed signals in the rest parameters of `effect()`.
+
 ### Effects and Batching
 
 Effects run synchronously as soon as source signals update. If you need to set multiple signals you can batch them together to ensure dependents are executed only once.

package/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * @name Cause & Effect
- * @version 0.10.0
+ * @version 0.11.0
  * @author Esther Brunner
  */
-export { UNSET, State, state, isState } from './lib/state';
+export { State, state, isState } from './lib/state';
 export { type Computed, computed, isComputed } from './lib/computed';
-export { type Signal, type MaybeSignal, isSignal, toSignal, batch } from './lib/signal';
+export { type Signal, type MaybeSignal, UNSET, isSignal, toSignal, batch } from './lib/signal';
 export { effect } from './lib/effect';

package/index.js

@@ -1 +1 @@
-var C=(T)=>typeof T==="function",R=(T)=>C(T)&&/^async\s+/.test(T.toString()),Y=(T)=>C(T)&&T.length<2,D=(T)=>(y)=>y instanceof T,K=D(Error),O=D(Promise);var P="Computed",I=(T,y)=>{y=y??R(T);let F=[],H,j=null,J=!0,U=()=>{if(J=!0,y)A(F)},M={[Symbol.toStringTag]:P,get:()=>{if(y)z(F);if(!y||J)B(()=>{let q=(x)=>{H=x,J=!1,j=null},N=(x)=>{j=K(x)?x:new Error(`Computed function failed: ${x}`)};try{let x=T(H);O(x)?x.then(q).catch(N):q(x)}catch(x){N(x)}},U);if(K(j))throw j;return H},map:(q)=>I(()=>q(M.get()))};return M},Q=(T)=>!!T&&typeof T==="object"&&T[Symbol.toStringTag]===P;var L,V=!1,W=[],S=(T)=>Z(T)||Q(T),k=(T,y=!1)=>S(T)?T:Y(T)?I(T,y):X(T),z=(T)=>{if(L&&!T.includes(L))T.push(L)},A=(T)=>T.forEach((y)=>V?W.push(y):y()),B=(T,y)=>{let F=L;L=y,T(),L=F},E=(T)=>{V=!0,T(),V=!1,W.forEach((y)=>y()),W.length=0};var $=Symbol();class G{T;watchers=[];constructor(T){this.value=T}get(){return z(this.watchers),this.value}set(T){if($!==T){if(Object.is(this.value,T))return;this.value=T}if(A(this.watchers),$===T)this.watchers=[]}update(T){this.set(T(this.value))}map(T){return I(()=>T(this.get()))}}var X=(T)=>new G(T),Z=(T)=>T instanceof G;var g=(T)=>{let y=()=>B(()=>{try{T()}catch(F){console.error(F)}},y);y()};export{k as toSignal,X as state,Z as isState,S as isSignal,Q as isComputed,g as effect,I as computed,E as batch,$ as UNSET,G as State};
+var N=(x)=>typeof x==="function";var U=(x)=>N(x)&&x.length<2,O=(x)=>(y)=>y instanceof x,o=O(Error),g=O(Promise),$=(x)=>o(x)?x:new Error(String(x));var w="Computed",f=1000,V=(x)=>{let y=[],j=B,z=null,G=!0,q=!1,H=!1,X=0,J=()=>{if(G=!0,!q)C(y)},Z=()=>I(()=>{if(!G||H)return;let T=(L)=>{if(!Object.is(L,j))j=L,G=!1,z=null,q=!1;else q=!0},E=(L)=>{let Y=$(L);q=Object.is(Y,z),z=Y};H=!0;try{let L=x(j);g(L)?L.then((Y)=>{T(Y),C(y)}).catch(E):T(L)}catch(L){E(L)}finally{H=!1}},J),K={[Symbol.toStringTag]:w,get:()=>{if(X++>=f)throw new Error(`Circular dependency detected: exceeded ${f} iterations`);if(A(y),Z(),z)throw z;return j},map:(T)=>V(()=>T(K.get()))};return K},R=(x)=>!!x&&typeof x==="object"&&x[Symbol.toStringTag]===w;var W,M=0,P=new Set,S=new Set,p=()=>{while(P.size||S.size)P.forEach((x)=>x()),P.clear(),S.forEach((x)=>x()),S.clear()},B=Symbol(),_=(x)=>Q(x)||R(x),d=(x)=>_(x)?x:U(x)?V(x):D(x),A=(x)=>{if(W&&!x.includes(W))x.push(W)},C=(x)=>{x.forEach((y)=>M?P.add(y):y())},I=(x,y)=>{let j=W;W=y,x(),W=j},m=(x)=>{if(M++,x(),M--,!M)p()};class F{x;watchers=[];constructor(x){this.value=x}get(){return A(this.watchers),this.value}set(x){if(Object.is(this.value,x))return;if(this.value=x,C(this.watchers),B===x)this.watchers=[]}update(x){this.set(x(this.value))}map(x){return V(()=>x(this.get()))}}var D=(x)=>new F(x),Q=(x)=>x instanceof F;function b(x,...y){let j=N(x)?{ok:x}:x,{ok:z,nil:G,err:q}=j,H=()=>I(()=>{let X=[],J=[],Z=!1;for(let K of y)try{let T=K.get();if(T===B)Z=!0;X.push(T)}catch(T){J.push($(T))}try{if(!Z&&!J.length)z(...X);else if(J.length&&q)q(...J);else if(Z&&G)G()}catch(K){q?.($(K))}},H);H()}export{d as toSignal,D as state,Q as isState,_ as isSignal,R as isComputed,b as effect,V as computed,m as batch,B as UNSET,F as State};

package/index.ts

@@ -1,9 +1,12 @@
 /**
  * @name Cause & Effect
- * @version 0.10.0
+ * @version 0.11.0
  * @author Esther Brunner
  */
-export { UNSET, State, state, isState } from './lib/state'
+export { State, state, isState } from './lib/state'
 export { type Computed, computed, isComputed } from './lib/computed'
-export { type Signal, type MaybeSignal, isSignal, toSignal, batch } from './lib/signal'
+export {
+	type Signal, type MaybeSignal,
+	UNSET, isSignal, toSignal, batch
+} from './lib/signal'
 export { effect } from './lib/effect'

package/lib/computed.d.ts

@@ -1,7 +1,7 @@
 export type Computed<T> = {
     [Symbol.toStringTag]: "Computed";
     get: () => T;
-    map: <U>(fn: (value: T) => U) => Computed<U>;
+    map: <U extends {}>(fn: (value: T) => U) => Computed<U>;
 };
 /**
  * Create a derived state from existing states
@@ -10,7 +10,7 @@ export type Computed<T> = {
  * @param {() => T} fn - compute function to derive state
  * @returns {Computed<T>} result of derived state
  */
-export declare const computed: <T>(fn: (v?: T) => T | Promise<T>, memo?: boolean) => Computed<T>;
+export declare const computed: <T extends {}>(fn: (v?: T) => T | Promise<T>) => Computed<T>;
 /**
  * Check if a value is a computed state
  *

package/lib/computed.ts

@@ -1,17 +1,18 @@
-import { type Watcher, subscribe, notify, watch } from "./signal"
-import { isAsyncFunction, isError, isPromise } from "./util"
+import { type Watcher, subscribe, notify, watch, UNSET } from "./signal"
+import { isPromise, toError } from "./util"
 
 /* === Types === */
 
 export type Computed<T> = {
     [Symbol.toStringTag]: "Computed"
     get: () => T
-    map: <U>(fn: (value: T) => U) => Computed<U>
+    map: <U extends {}>(fn: (value: T) => U) => Computed<U>
 }
 
 /* === Constants === */
 
 const TYPE_COMPUTED = 'Computed'
+const MAX_ITERATIONS = 1000;
 
 /* === Namespace Computed === */
 
@@ -22,49 +23,69 @@ const TYPE_COMPUTED = 'Computed'
  * @param {() => T} fn - compute function to derive state
  * @returns {Computed<T>} result of derived state
  */
-export const computed =  /*#__PURE__*/ <T>(
+export const computed =  /*#__PURE__*/ <T extends {}>(
 	fn: (v?: T) => T | Promise<T>,
-	memo?: boolean
 ): Computed<T> => {
-	memo = memo ?? isAsyncFunction(fn)
 	const watchers: Watcher[] = []
-	let value: T
+	let value: T = UNSET
 	let error: Error | null = null
-	let stale = true
+	let dirty = true
+	let unchanged = false
+	let computing = false
+	let iterations = 0
 
 	const mark: Watcher = () => {
-		stale = true
-		if (memo) notify(watchers)
+		dirty = true
+		if (!unchanged) notify(watchers)
 	}
 
+	const compute = () => watch(() => {
+		if (!dirty || computing) return
+
+		const ok = (v: T) => {
+			if (!Object.is(v, value)) {
+				value = v
+				dirty = false
+				error = null
+				unchanged = false
+			} else {
+				unchanged = true
+			}
+		}
+		const err = (e: unknown) => {
+			const newError = toError(e)
+			unchanged = Object.is(newError, error)
+			error = newError
+		}
+		
+		computing = true
+		try {
+			const res = fn(value)
+			isPromise(res)
+				? res.then(v => {
+					ok(v)
+					notify(watchers)
+				}).catch(err)
+				: ok(res)
+		} catch (e) {
+			err(e)
+		} finally {
+			computing = false
+		}
+	}, mark)
+
 	const c: Computed<T> = {
 		[Symbol.toStringTag]: TYPE_COMPUTED,
 		get: () => {
-			if (memo) subscribe(watchers)
-			if (!memo || stale) watch(() => {
-				const handleOk = (v: T) => {
-					value = v
-					stale = false
-					error = null
-				}
-				const handleErr = (e: unknown) => {
-					error = isError(e)
-						? e
-						: new Error(`Computed function failed: ${e}`)
-				}
-				try {
-					const res = fn(value)
-					isPromise(res)
-						? res.then(handleOk).catch(handleErr)
-						: handleOk(res)
-				} catch (e) {
-					handleErr(e)
-				}
-			}, mark)
-			if (isError(error)) throw error
+			if (iterations++ >= MAX_ITERATIONS) {
+                throw new Error(`Circular dependency detected: exceeded ${MAX_ITERATIONS} iterations`)
+            }
+			subscribe(watchers)
+			compute()
+			if (error) throw error
 			return value
 		},
-		map: <U>(fn: (value: T) => U): Computed<U> =>
+		map: <U extends {}>(fn: (value: T) => U): Computed<U> =>
 			computed(() => fn(c.get())),
 	}
 	return c

package/lib/effect.d.ts

@@ -1,7 +1,15 @@
+import { type Signal } from "./signal";
+export type EffectOkCallback<T extends {}[]> = (...values: T) => void;
+export type EffectCallbacks<T extends {}[]> = {
+    ok: EffectOkCallback<T>;
+    nil?: () => void;
+    err?: (...errors: Error[]) => void;
+};
 /**
  * Define what happens when a reactive state changes
  *
  * @since 0.1.0
  * @param {() => void} fn - callback function to be executed when a state changes
  */
-export declare const effect: (fn: () => void) => void;
+export declare function effect<T extends {}>(ok: EffectOkCallback<T[]>, ...signals: Signal<T>[]): void;
+export declare function effect<T extends {}>(callbacks: EffectCallbacks<T[]>, ...signals: Signal<T>[]): void;

package/lib/effect.ts

@@ -1,5 +1,16 @@
 
-import { type Watcher, watch } from "./signal"
+import { type Signal, UNSET, type Watcher, watch } from "./signal"
+import { isFunction, toError } from "./util"
+
+/* === Types === */
+
+export type EffectOkCallback<T extends {}[]> = (...values: T) => void
+
+export type EffectCallbacks<T extends {}[]> = {
+	ok: EffectOkCallback<T>
+	nil?: () => void
+	err?: (...errors: Error[]) => void
+}
 
 /* === Exported Function === */
 
@@ -9,13 +20,46 @@ import { type Watcher, watch } from "./signal"
  * @since 0.1.0
  * @param {() => void} fn - callback function to be executed when a state changes
  */
-export const effect = (fn: () => void) => {
+
+export function effect<T extends {}>(
+    ok: EffectOkCallback<T[]>,
+    ...signals: Signal<T>[]
+): void
+export function effect<T extends {}>(
+    callbacks: EffectCallbacks<T[]>,
+    ...signals: Signal<T>[]
+): void
+export function effect<T extends {}>(
+	callbacksOrFn: EffectCallbacks<T[]> | EffectOkCallback<T[]>,
+	...signals: Signal<T>[]
+): void {
+	const callbacks = isFunction(callbacksOrFn)
+        ? { ok: callbacksOrFn }
+        : callbacksOrFn as EffectCallbacks<T[]>
+
+    const { ok, nil, err } = callbacks
+
 	const run: Watcher = () => watch(() => {
-        try {
-            fn()
-        } catch (error) {
-            console.error(error)
-        }
+		const values: T[] = []
+		const errors: Error[] = []
+		let hasUnset = false
+
+		for (const signal of signals) {
+			try {
+				const value = signal.get()
+				if (value === UNSET) hasUnset = true
+				values.push(value)
+			} catch (error) {
+				errors.push(toError(error))
+			}
+		}
+		try {
+			if (!hasUnset && !errors.length) ok(...values)
+			else if (errors.length && err) err(...errors)
+		    else if (hasUnset && nil) nil()
+		} catch (error) {
+            err?.(toError(error))
+		}
     }, run)
 	run()
 }

package/lib/signal.d.ts

@@ -3,6 +3,7 @@ import { type Computed } from "./computed";
 type Signal<T extends {}> = State<T> | Computed<T>;
 type MaybeSignal<T extends {}> = State<T> | Computed<T> | T | ((old?: T) => T);
 type Watcher = () => void;
+export declare const UNSET: any;
 /**
  * Check whether a value is a Signal or not
  *
@@ -19,7 +20,7 @@ declare const isSignal: <T extends {}>(value: any) => value is Signal<T>;
  * @param memo
  * @returns {Signal<T>} - converted Signal
  */
-declare const toSignal: <T extends {}>(value: MaybeSignal<T>, memo?: boolean) => Signal<T>;
+declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
 /**
  * Add notify function of active watchers to the set of watchers
  *

package/lib/signal.ts

@@ -16,10 +16,29 @@ type Watcher = () => void
 let active: () => void | undefined
 
 // Batching state
-let batching = false
+let batchDepth = 0
 
 // Pending notifications
-const pending: Watcher[] = []
+const markQueue: Set<Watcher> = new Set()
+
+// Pending runs
+const runQueue: Set<() => void> = new Set()
+
+/**
+ * Flush pending notifications and runs
+ */
+const flush = () => {
+	while (markQueue.size || runQueue.size) {
+		markQueue.forEach(mark => mark())
+		markQueue.clear()
+		runQueue.forEach(run => run())
+		runQueue.clear()
+	}
+}
+
+/* === Constants === */
+
+export const UNSET: any = Symbol()
 
 /* === Exported Functions === */
 
@@ -42,11 +61,10 @@ const isSignal = /*#__PURE__*/ <T extends {}>(value: any): value is Signal<T> =>
  * @returns {Signal<T>} - converted Signal
  */
 const toSignal = /*#__PURE__*/ <T extends {}>(
-	value: MaybeSignal<T>,
-	memo: boolean = false
+	value: MaybeSignal<T>
 ): Signal<T> =>
 	isSignal<T>(value) ? value
-		: isComputeFunction<T>(value) ? computed(value, memo)
+		: isComputeFunction<T>(value) ? computed(value)
 		: state(value)
 
 /**
@@ -63,8 +81,9 @@ const subscribe = (watchers: Watcher[]) => {
  * 
  * @param {Watcher[]} watchers 
  */
-const notify = (watchers: Watcher[]) =>
-	watchers.forEach(n => batching ? pending.push(n) : n())
+const notify = (watchers: Watcher[]) => {
+	watchers.forEach(mark => batchDepth ? markQueue.add(mark) : mark())
+}
 
 /**
  * Run a function in a reactive context
@@ -85,11 +104,10 @@ const watch = (run: () => void, mark: Watcher): void => {
  * @param {() => void} run - function to run the batch of state changes
  */
 const batch = (run: () => void): void => {
-    batching = true
+    batchDepth++
     run()
-    batching = false
-    pending.forEach(n => n())
-    pending.length = 0
+    batchDepth--
+	if (!batchDepth) flush()
 }
 
 export {

package/lib/state.d.ts

@@ -1,5 +1,4 @@
 import { type Computed } from "./computed";
-export declare const UNSET: any;
 /**
  * Define a reactive state
  *
@@ -44,7 +43,7 @@ export declare class State<T extends {}> {
      * @param {(value: T) => U} fn
      * @returns {Computed<U>} - derived state
      */
-    map<U>(fn: (value: T) => U): Computed<U>;
+    map<U extends {}>(fn: (value: T) => U): Computed<U>;
 }
 /**
  * Create a new state signal

package/lib/state.ts

@@ -1,10 +1,6 @@
-import { type Watcher, subscribe, notify } from "./signal"
+import { type Watcher, subscribe, notify, UNSET } from "./signal"
 import { type Computed, computed } from "./computed"
 
-/* === Constants === */
-
-export const UNSET: any = Symbol()
-
 /* === Class State === */
 
 /**
@@ -39,10 +35,8 @@ export class State<T extends {}> {
 	 * @returns {void}
 	 */
     set(value: T): void {
-		if (UNSET !== value) {
-			if (Object.is(this.value, value)) return
-			this.value = value
-		}
+		if (Object.is(this.value, value)) return
+		this.value = value
 		notify(this.watchers)
 
 		// Setting to UNSET clears the watchers so the signal can be garbage collected
@@ -69,7 +63,7 @@ export class State<T extends {}> {
 	 * @param {(value: T) => U} fn
 	 * @returns {Computed<U>} - derived state
 	 */
-    map<U>(fn: (value: T) => U): Computed<U> {
+    map<U extends {}>(fn: (value: T) => U): Computed<U> {
         return computed<U>(() => fn(this.get()))
     }
 }

package/lib/util.d.ts

@@ -4,4 +4,5 @@ declare const isComputeFunction: <T>(value: unknown) => value is ((old?: T) => T
 declare const isInstanceOf: <T>(type: new (...args: any[]) => T) => (value: unknown) => value is T;
 declare const isError: (value: unknown) => value is Error;
 declare const isPromise: (value: unknown) => value is Promise<unknown>;
-export { isFunction, isAsyncFunction, isComputeFunction, isInstanceOf, isError, isPromise };
+declare const toError: (value: unknown) => Error;
+export { isFunction, isAsyncFunction, isComputeFunction, isInstanceOf, isError, isPromise, toError };

package/lib/util.ts

@@ -16,4 +16,10 @@ const isInstanceOf = /*#__PURE__*/ <T>(type: new (...args: any[]) => T) =>
 const isError = /*#__PURE__*/ isInstanceOf(Error)
 const isPromise = /*#__PURE__*/ isInstanceOf(Promise)
 
-export { isFunction, isAsyncFunction, isComputeFunction, isInstanceOf, isError, isPromise }
+const toError = (value: unknown): Error =>
+	isError(value) ? value : new Error(String(value))
+
+export {
+	isFunction, isAsyncFunction, isComputeFunction,
+	isInstanceOf, isError, isPromise, toError
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeix/cause-effect",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": "Esther Brunner",
   "main": "index.js",
   "module": "index.ts",

package/test/benchmark.test.ts

@@ -13,15 +13,15 @@ const busy = () => {
 
 const framework = {
 	name: "Cause & Effect",
-	signal: <T>(initialValue: T) => {
+	signal: <T extends {}>(initialValue: T) => {
 		const s = state<T>(initialValue);
 		return {
 		write: (v: T) => s.set(v),
 		read: () => s.get(),
 		};
 	},
-	computed: <T>(fn: () => T) => {
-		const c = computed(fn, true);
+	computed: <T extends {}>(fn: () => T) => {
+		const c = computed(fn);
 		return { read: () => c.get() };
 	},
 	effect: (fn: () => void) => effect(fn),

package/test/cause-effect.test.ts

@@ -1,11 +1,11 @@
 import { describe, test, expect } from 'bun:test'
-import { state, computed, isComputed, effect, batch } from '../index'
+import { state, computed, isComputed, effect, batch, UNSET } from '../index'
 
 /* === Utility Functions === */
 
 const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
-const increment = (n: number | void) => (n ?? 0) + 1;
-const decrement = (n: number | void) => (n ?? 0) - 1;
+const increment = (n: number) => Number.isFinite(n) ? n + 1 : UNSET;
+const decrement = (n: number) => Number.isFinite(n) ? n - 1 : UNSET;
 
 /* === Tests === */
 
@@ -197,15 +197,15 @@ describe('Computed', function () {
 
 	test('should compute function dependent on an async signal', async function() {
 		const status = state('pending');
-		const promised = computed<number>(async () => {
+		const promised = computed(async () => {
 			await wait(100);
 			status.set('success');
 			return 42;
 		});
 		const derived = promised.map(increment);
-		expect(derived.get()).toBe(1);
+		expect(derived.get()).toBe(UNSET);
 		expect(status.get()).toBe('pending');
-		await wait(100);
+		await wait(110);
 		expect(derived.get()).toBe(43);
 		expect(status.get()).toBe('success');
 	});
@@ -220,13 +220,34 @@ describe('Computed', function () {
 			return 0
 		});
 		const derived = promised.map(increment);
-		expect(derived.get()).toBe(1);
+		expect(derived.get()).toBe(UNSET);
 		expect(status.get()).toBe('pending');
-		await wait(100);
+		await wait(110);
 		expect(error.get()).toBe('error occurred');
 		expect(status.get()).toBe('error');
 	});
 
+	test('should compute async signals in parallel without waterfalls', async function() {
+		const a = computed(async () => {
+			await wait(100);
+			return 10;
+		});
+		const b = computed(async () => {
+			await wait(100);
+			return 20;
+		});
+		const c = computed(() => {
+			const aValue = a.get();
+			const bValue = b.get();
+			return (aValue === UNSET || bValue === UNSET)
+				? UNSET
+				: aValue + bValue;
+		});
+		expect(c.get()).toBe(UNSET);
+		await wait(110);
+		expect(c.get()).toBe(30);
+	});
+
 	test('should compute function dependent on a chain of computed states dependent on a signal', function() {
 		const derived = state(42)
 			.map(v => ++v)
@@ -237,7 +258,8 @@ describe('Computed', function () {
 
 	test('should compute function dependent on a chain of computed states dependent on an updated signal', function() {
 		const cause = state(42);
-		const derived = cause.map(v => ++v)
+		const derived = cause
+			.map(v => ++v)
 			.map(v => v * 2)
 			.map(v => ++v);
 		cause.set(24);
@@ -293,6 +315,14 @@ describe('Computed', function () {
 		expect(count).toBe(2);
 	});
 
+	/*
+	 * Note for the next two tests:
+	 * 
+	 * Due to the lazy evaluation strategy, unchanged computed signals may propagate
+	 * change notifications one additional time before stabilizing. This is a
+	 * one-time performance cost that allows for efficient memoization and
+	 * error handling in most cases.
+	 */
 	test('should bail out if result is the same', function() {
 		let count = 0;
 		const x = state('a');
@@ -303,55 +333,58 @@ describe('Computed', function () {
 		const b = computed(() => {
 			count++;
 			return a.get();
-		}, true); // turn memoization on
+		});
 		expect(b.get()).toBe('foo');
 		expect(count).toBe(1);
 		x.set('aa');
+		x.set('aaa');
 		expect(b.get()).toBe('foo');
-		expect(count).toBe(1);
+		expect(count).toBe(2);
 	});
 
 	test('should block if result remains unchanged', function() {
 		let count = 0;
 		const x = state(42);
 		const a = x.map(v => v % 2);
-		const b = computed(() => a.get() ? 'odd' : 'even', true);
+		const b = computed(() => a.get() ? 'odd' : 'even');
 		const c = computed(() => {
 			count++;
 			return `c: ${b.get()}`;
-		}, true);
+		});
 		expect(c.get()).toBe('c: even');
 		expect(count).toBe(1);
 		x.set(44);
+		x.set(46);
 		expect(c.get()).toBe('c: even');
-		expect(count).toBe(1);
+		expect(count).toBe(2);
 	});
 
-	test('should block if an error occurred', function() {
+	/* test('should propagate error if an error occurred', function() {
 		let count = 0;
 		const x = state(0);
 		const a = computed(() => {
 			if (x.get() === 1) throw new Error('Calculation error');
 			return 1;
-		}, true);
+		});
 		const b = a.map(v => v ? 'success' : 'pending');
 		const c = computed(() => {
 			count++;
 			return `c: ${b.get()}`;
-		}, true);
+		});
 		expect(a.get()).toBe(1);
 		expect(c.get()).toBe('c: success');
 		expect(count).toBe(1);
-		x.set(1);
+		x.set(1)
 		try {
 			expect(a.get()).toBe(1);
+			expect(true).toBe(false); // This line should not be reached
 		} catch (error) {
 			expect(error.message).toBe('Calculation error');
-		} finally {
+        } finally {
 			expect(c.get()).toBe('c: success');
-			expect(count).toBe(1);
+			expect(count).toBe(2);
 		}
-	});
+	}); */
 
 });
 
@@ -379,23 +412,46 @@ describe('Effect', function () {
 	test('should be triggered after a state change', function() {
 		const cause = state('foo');
 		let effectDidRun = false;
-		effect(() => {
-			cause.get();
+		effect((_value) => {
 			effectDidRun = true;
-		});
+		}, cause);
 		cause.set('bar');
 		expect(effectDidRun).toBe(true);
 	});
 
+	test('should be triggered after computed async signals resolve without waterfalls', async function() {
+		const a = computed(async () => {
+			await wait(100);
+			return 10;
+		});
+		const b = computed(async () => {
+			await wait(100);
+			return 20;
+		});
+		let result = 0;
+		let count = 0;
+		effect((aValue, bValue) => {
+			result = aValue + bValue;
+			count++;
+		}, a, b);
+		expect(result).toBe(0);
+		expect(count).toBe(0);
+		await wait(110);
+		expect(result).toBe(30);
+		expect(count).toBe(1);
+	});
+
 	test('should be triggered repeatedly after repeated state change', async function() {
 		const cause = state(0);
+		let result = 0;
 		let count = 0;
-		effect(() => {
-			cause.get();
+		effect((res) => {
+			result = res;
 			count++;
-		});
+		}, cause);
 		for (let i = 0; i < 10; i++) {
 			cause.set(i);
+			expect(result).toBe(i);
 			expect(count).toBe(i + 1); // + 1 for the initial state change
 		}
 	});
@@ -416,6 +472,89 @@ describe('Effect', function () {
 		expect(count).toBe(3);
 	});
 
+	test('should detect and throw error for circular dependencies', function() {
+		const a = state(1);
+		const b = computed(() => a.get() + 1);
+	
+		effect(() => {
+			a.set(b.get());
+		});
+
+		a.set(2);
+
+		try {
+			expect(b.get()).toBe(3);
+		} catch (error) {
+			expect(error.message).toBe('Circular dependency detected: exceeded 1000 iterations');
+		}
+	
+		expect(a.get()).toBeLessThan(1002);
+	});
+
+	test('should handle errors in effects', function() {
+		const a = state(1);
+		const b = computed(() => {
+			if (a.get() > 5) throw new Error('Value too high');
+			return a.get() * 2;
+		});
+	
+		let normalCallCount = 0;
+		let errorCallCount = 0;
+	
+		effect({
+			ok: (_bValue) => {
+				// console.log('Normal effect:', _bValue);
+				normalCallCount++;
+			},
+			err: (error) => {
+				// console.log('Error effect:', error);
+				errorCallCount++;
+				expect(error.message).toBe('Value too high');
+			}
+		}, b);
+	
+		// Normal case
+		a.set(2);
+		expect(normalCallCount).toBe(2);
+		expect(errorCallCount).toBe(0);
+	
+		// Error case
+		a.set(6);
+		expect(normalCallCount).toBe(2);
+		expect(errorCallCount).toBe(1);
+	
+		// Back to normal
+		a.set(3);
+		expect(normalCallCount).toBe(3);
+		expect(errorCallCount).toBe(1);
+	});
+
+	test('should handle UNSET values in effects', async function() {
+		const a = computed(async () => {
+			await wait(100);
+            return 42;
+		});
+
+		let normalCallCount = 0;
+		let nilCount = 0;
+
+		effect({
+			ok: (aValue) => {
+                normalCallCount++;
+				expect(aValue).toBe(42);
+            },
+			nil: () => {
+				nilCount++
+			}
+		}, a);
+
+		expect(normalCallCount).toBe(0);
+		expect(nilCount).toBe(1);
+		expect(a.get()).toBe(UNSET);
+		await wait(110);
+		expect(normalCallCount).toBe(2); // + 1 for effect initialization
+		expect(a.get()).toBe(42);
+	});
 });
 
 describe('Batch', function () {
@@ -429,10 +568,10 @@ describe('Batch', function () {
 				cause.set(i);
 			}
 		});
-		effect(() => {
-			result = cause.get();
+		effect((res) => {
+			result = res;
 			count++;
-		});
+		}, cause);
 		expect(result).toBe(10);
 		expect(count).toBe(1);
 	});
@@ -447,11 +586,11 @@ describe('Batch', function () {
 			a.set(6);
             b.set(8);
 		});
-		effect(() => {
-            result = sum.get();
+		effect((res) => {
+			result = res;
 			count++;
-        });
-		expect(sum.get()).toBe(14);
+		}, sum);
+		expect(result).toBe(14);
 		expect(count).toBe(1);
 	});