@zeix/cause-effect 0.10.1 → 0.12.0

package/README.md

@@ -1,14 +1,48 @@
 # Cause & Effect
 
-Version 0.10.1
+Version 0.12.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**: Dependency-free, only 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, effect } from '@zeix/cause-effect'
+
+// Create a state signal
+const count = state(0)
+
+// Create a computed signal
+const doubleCount = count.map(v => v * 2)
+
+// Create an effect
+effect((c, d) => {
+    console.log(`Count: ${c}, Double: ${d}`)
+}, count, doubleCount)
+
+// Update the state
+count.set(5) // Logs: "Count: 5, Double: 10"
+```
 
 ## Installation
 
@@ -32,8 +66,9 @@ import { state, effect } from '@zeix/cause-effect'
 const count = state(42)
 effect(() => console.log(count.get())) // logs '42'
 count.set(24) // logs '24'
-document.querySelector('button.increment')
-    .addEventListener('click', () => count.update(v => ++v))
+document.querySelector('.increment').addEventListener('click', () => {
+	count.update(v => ++v)
+})
 // Click on button logs '25', '26', and so on
 ```
 
@@ -48,8 +83,9 @@ const count = state(42)
 const isOdd = computed(() => count.get() % 2)
 effect(() => console.log(isOdd.get())) // logs 'false'
 count.set(24) // logs nothing because 24 is also an even number
-document.querySelector('button.increment')
-    .addEventListener('click', () => count.update(v => ++v))
+document.querySelector('button.increment').addEventListener('click', () => {
+	count.update(v => ++v)
+})
 // Click on button logs 'true', 'false', and so on
 ```
 
@@ -62,8 +98,9 @@ const count = state(42)
 const isOdd = count.map(v => v % 2)
 effect(() => console.log(isOdd.get())) // logs 'false'
 count.set(24) // logs nothing because 24 is also an even number
-document.querySelector('button.increment')
-    .addEventListener('click', () => count.set(v => ++v))
+document.querySelector('.increment').addEventListener('click', () => {
+	count.update(v => ++v)
+})
 // Click on button logs 'true', 'false', and so on
 ```
 
@@ -71,7 +108,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,41 +119,98 @@ 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()`.
+
+If you want an effect based on a single signal, there's a shorthand too: The `.match()` method on either `State` or `Computed`. You can use it for easy debugging, for example:
+
+```js
+signal.match({
+	ok: v => console.log('Value:', v),
+	nil: () => console.warn('Not ready'),
+	err: e => console.error('Error:', e)
+})
+```
+
 ### 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.
 
 ```js
-import { state, computed, effect, batch } from '@zeix/cause-effect'
-
-const a = state(3)
-const b = state(4)
-const sum = computed(() => a.get() + b.get())
-effect(() => console.log(sum.get())) // logs '7'
-document.querySelector('button.double-all')
-    .addEventListener('click', () =>
-        batch(() => {
-            a.update(v => v * 2)
-            b.update(v => v * 2)
-        }
-    ))
-// Click on button logs '14' only once (instead of first '10' and then '14' without batch)
-```
+import { state, computed, batch } from '@zeix/cause-effect'
+
+// State: define an array of State<number>
+const signals = [state(2), state(3), state(5)]
+
+// Computed: derive a calculation ...
+const sum = computed(
+	(...values) => values.reduce((total, v) => total + v, 0),
+	...signals
+).map(v => { // ... perform validation and handle errors
+	if (!Number.isFinite(v)) throw new Error('Invalid value')
+	return v
+})
+
+// Effect: switch cases for the result
+sum.match({
+	ok: v => console.log('Sum:', v),
+	err: error => console.error('Error:', error)
+})
+
+// Batch: apply changes to all signals in a single transaction
+document.querySelector('.double-all').addEventListener('click', () => {
+	batch(() => {
+		signals.forEach(signal => signal.update(v => v * 2))
+	})
+})
+// Click on button logs '20' only once
+// (instead of first '12', then '15' and then '20' without batch)
+
+// Provoke an error - but no worries: it will be handled fine
+signals[0].set(NaN)
+```
+
+This example showcases several powerful features of Cause & Effect:
+
+1. **Composability and Declarative Computations**: Easily compose multiple signals into a single computed value, declaring how values should be calculated based on other signals.
+2. **Automatic Dependency Tracking and Efficient Updates**: The library tracks dependencies between signals and computed values, ensuring efficient propagation of changes.
+3. **Robust Error Handling**: Built-in error handling at computation level and reactive error management allow for graceful handling of unexpected situations.
+4. **Performance Optimization through Batching**: Group multiple state changes to ensure dependent computations and effects run only once after all changes are applied.
+5. **Flexibility and Integration**: Seamlessly integrates with DOM manipulation and event listeners, fitting into any JavaScript application or framework.
+
+These principles enable developers to create complex, reactive applications with clear data flow, efficient updates, and robust error handling, while promoting code reuse and modularity.

package/index.d.ts

@@ -1,9 +1,10 @@
 /**
  * @name Cause & Effect
- * @version 0.10.1
+ * @version 0.12.0
  * @author Esther Brunner
  */
-export { UNSET, State, state, isState } from './lib/state';
+export { type Signal, type MaybeSignal, UNSET, isSignal, toSignal } from './lib/signal';
+export { type 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 { effect } from './lib/effect';
+export { type EffectOkCallback, type EffectCallbacks, effect } from './lib/effect';
+export { type EnqueueDedupe, batch, watch, enqueue } from './lib/scheduler';

package/index.js

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

package/index.ts

@@ -1,9 +1,10 @@
 /**
  * @name Cause & Effect
- * @version 0.10.1
+ * @version 0.12.0
  * @author Esther Brunner
  */
-export { UNSET, State, state, isState } from './lib/state'
+export { type Signal, type MaybeSignal, UNSET, isSignal, toSignal } from './lib/signal'
+export { type 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 { effect } from './lib/effect'
+export { type EffectOkCallback, type EffectCallbacks, effect } from './lib/effect'
+export { type EnqueueDedupe, batch, watch, enqueue } from './lib/scheduler'

package/lib/computed.d.ts

@@ -1,16 +1,29 @@
-export type Computed<T> = {
-    [Symbol.toStringTag]: "Computed";
+import { type SignalValue, type UnknownSignal } from './signal';
+import { type EffectCallbacks } from './effect';
+export type ComputedOkCallback<T extends {}, U extends UnknownSignal[]> = (...values: {
+    [K in keyof U]: SignalValue<U[K]>;
+}) => T | Promise<T>;
+export type ComputedCallbacks<T extends {}, U extends UnknownSignal[]> = {
+    ok: (...values: {
+        [K in keyof U]: SignalValue<U[K]>;
+    }) => T | Promise<T>;
+    nil?: () => T | Promise<T>;
+    err?: (...errors: Error[]) => T | Promise<T>;
+};
+export type Computed<T extends {}> = {
+    [Symbol.toStringTag]: 'Computed';
     get: () => T;
     map: <U extends {}>(fn: (value: T) => U) => Computed<U>;
+    match: (callbacks: EffectCallbacks<[Computed<T>]>) => void;
 };
 /**
  * Create a derived state from existing states
  *
  * @since 0.9.0
- * @param {() => T} fn - compute function to derive state
+ * @param {() => T} callbacksOrFn - compute function to derive state
  * @returns {Computed<T>} result of derived state
  */
-export declare const computed: <T extends {}>(fn: (v?: T) => T | Promise<T>, memo?: boolean) => Computed<T>;
+export declare const computed: <T extends {}, U extends UnknownSignal[]>(callbacksOrFn: ComputedCallbacks<T, U> | ComputedOkCallback<T, U>, ...signals: U) => Computed<T>;
 /**
  * Check if a value is a computed state
  *
@@ -18,4 +31,4 @@ export declare const computed: <T extends {}>(fn: (v?: T) => T | Promise<T>, mem
  * @param {unknown} value - value to check
  * @returns {boolean} - true if value is a computed state, false otherwise
  */
-export declare const isComputed: <T>(value: unknown) => value is Computed<T>;
+export declare const isComputed: <T extends {}>(value: unknown) => value is Computed<T>;

package/lib/computed.ts

@@ -1,71 +1,140 @@
-import { type Watcher, subscribe, notify, watch } from "./signal"
-import { isAsyncFunction, isError, isPromise } from "./util"
+import { resolveSignals, UNSET, type SignalValue, type UnknownSignal } from './signal'
+import { isEquivalentError, isError, isFunction, isObjectOfType, isPromise, toError } from './util'
+import { type Watcher, flush, notify, subscribe, watch } from './scheduler'
+import { type EffectCallbacks, effect } from './effect'
 
 /* === Types === */
 
-export type Computed<T> = {
-    [Symbol.toStringTag]: "Computed"
+export type ComputedOkCallback<T extends {}, U extends UnknownSignal[]> = (
+	...values: { [K in keyof U]: SignalValue<U[K]> }
+) => T | Promise<T>
+
+export type ComputedCallbacks<T extends {}, U extends UnknownSignal[]> = {
+	ok: (...values: { [K in keyof U]: SignalValue<U[K]> }) => T | Promise<T>
+	nil?: () => T | Promise<T>
+	err?: (...errors: Error[]) => T | Promise<T>
+}
+
+export type Computed<T extends {}> = {
+    [Symbol.toStringTag]: 'Computed'
     get: () => T
     map: <U extends {}>(fn: (value: T) => U) => Computed<U>
+	match: (callbacks: EffectCallbacks<[Computed<T>]>) => void
 }
 
 /* === Constants === */
 
 const TYPE_COMPUTED = 'Computed'
 
-/* === Namespace Computed === */
+/* === Computed Factory === */
 
 /**
  * Create a derived state from existing states
  * 
  * @since 0.9.0
- * @param {() => T} fn - compute function to derive state
+ * @param {() => T} callbacksOrFn - compute function to derive state
  * @returns {Computed<T>} result of derived state
  */
-export const computed =  /*#__PURE__*/ <T extends {}>(
-	fn: (v?: T) => T | Promise<T>,
-	memo?: boolean
+export const computed = <T extends {}, U extends UnknownSignal[]>(
+	callbacksOrFn: ComputedCallbacks<T, U> | ComputedOkCallback<T, U>,
+	...signals: U
 ): Computed<T> => {
-	memo = memo ?? isAsyncFunction(fn)
+	const callbacks = isFunction(callbacksOrFn)
+		? { ok: callbacksOrFn }
+		: callbacksOrFn
 	const watchers: Watcher[] = []
-	let value: T
-	let error: Error | null = null
-	let stale = true
+	let value: T = UNSET
+	let error: Error | undefined
+	let dirty = true
+	let unchanged = false
+	let computing = false
 
-	const mark: Watcher = () => {
-		stale = true
-		if (memo) notify(watchers)
+	// Functions to update internal state
+	const ok = (v: T) => {
+		if (!Object.is(v, value)) {
+			value = v
+			dirty = false
+			error = undefined
+			unchanged = false
+		}
+	}
+	const nil = () => {
+		unchanged = (UNSET === value)
+		value = UNSET
+		error = undefined
+	}
+	const err = (e: unknown) => {
+		const newError = toError(e)
+		unchanged = isEquivalentError(newError, error)
+		value = UNSET
+		error = newError
 	}
 
+	// Called when notified from sources (push)
+	const mark = () => {
+		dirty = true
+		if (!unchanged) notify(watchers)
+	}
+
+	// Called when requested by dependencies (pull)
+	const compute = () => watch(() => {
+		if (computing) throw new Error('Circular dependency detected')
+		unchanged = true
+		computing = true
+		const result = resolveSignals(signals, callbacks as ComputedCallbacks<T, U>)
+		if (isPromise(result)) {
+			nil() // sync
+			result.then(v => {
+				ok(v) // async
+                notify(watchers)
+			}).catch(err)
+		} else if (null == result || UNSET === result) nil()
+		else if (isError(result)) err(result)
+		else ok(result)
+		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
+
+		/**
+		 * Get the current value of the computed
+		 * 
+		 * @since 0.9.0
+		 * @method of Computed<T>
+		 * @returns {T} - current value of the computed
+		 */
+		get: (): T => {
+			subscribe(watchers)
+			flush()
+			if (dirty) compute()
+			if (error) throw error
 			return value
 		},
-		map: <U extends {}>(fn: (value: T) => U): Computed<U> =>
+
+		/**
+		 * Create a computed signal from the current computed signal
+		 * 
+		 * @since 0.9.0
+		 * @method of Computed<T>
+		 * @param {(value: T) => R} fn
+		 * @returns {Computed<R>} - computed signal
+		 */
+		map: <R extends {}>(fn: (value: T) => R): Computed<R> =>
 			computed(() => fn(c.get())),
+
+		/**
+		 * Case matching for the computed signal with effect callbacks
+		 * 
+		 * @since 0.12.0
+		 * @method of Computed<T>
+		 * @param {EffectCallbacks[<T>]} callbacks 
+		 * @returns {Computed<T>} - self, for chaining effect callbacks
+		 */
+		match: (callbacks: EffectCallbacks<[Computed<T>]>): Computed<T> => {
+			effect(callbacks, c)
+			return c
+		}
 	}
 	return c
 }
@@ -79,6 +148,5 @@ export const computed =  /*#__PURE__*/ <T extends {}>(
  * @param {unknown} value - value to check
  * @returns {boolean} - true if value is a computed state, false otherwise
  */
-export const isComputed = /*#__PURE__*/ <T>(value: unknown): value is Computed<T> =>
-	!!value && typeof value === 'object'
-		&& (value as { [key in typeof Symbol.toStringTag]: string })[Symbol.toStringTag] === TYPE_COMPUTED
+export const isComputed = /*#__PURE__*/ <T extends {}>(value: unknown): value is Computed<T> =>
+	isObjectOfType(value, TYPE_COMPUTED)

package/lib/effect.d.ts

@@ -1,7 +1,18 @@
+import { type SignalValue, type UnknownSignal } from './signal';
+export type EffectOkCallback<T extends UnknownSignal[]> = (...values: {
+    [K in keyof T]: SignalValue<T[K]>;
+}) => void;
+export type EffectCallbacks<T extends UnknownSignal[]> = {
+    ok: (...values: {
+        [K in keyof T]: SignalValue<T[K]>;
+    }) => void;
+    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
+ * @param {() => void} callbacksOrFn - callback function to be executed when a state changes
  */
-export declare const effect: (fn: () => void) => void;
+export declare function effect<T extends UnknownSignal[]>(callbacksOrFn: EffectCallbacks<T> | EffectOkCallback<T>, ...signals: T): void;

package/lib/effect.ts

@@ -1,5 +1,19 @@
 
-import { type Watcher, watch } from "./signal"
+import { resolveSignals, type SignalValue, type UnknownSignal } from './signal'
+import { isError, isFunction } from './util'
+import { watch } from './scheduler'
+
+/* === Types === */
+
+export type EffectOkCallback<T extends UnknownSignal[]> = (
+	...values: { [K in keyof T]: SignalValue<T[K]> }
+) => void
+
+export type EffectCallbacks<T extends UnknownSignal[]> = {
+	ok: (...values: { [K in keyof T]: SignalValue<T[K]> }) => void
+	nil?: () => void
+	err?: (...errors: Error[]) => void
+}
 
 /* === Exported Function === */
 
@@ -7,15 +21,20 @@ import { type Watcher, watch } from "./signal"
  * Define what happens when a reactive state changes
  * 
  * @since 0.1.0
- * @param {() => void} fn - callback function to be executed when a state changes
+ * @param {() => void} callbacksOrFn - callback function to be executed when a state changes
  */
-export const effect = (fn: () => void) => {
-	const run: Watcher = () => watch(() => {
-        try {
-            fn()
-        } catch (error) {
-            console.error(error)
-        }
+export function effect<T extends UnknownSignal[]>(
+	callbacksOrFn: EffectCallbacks<T> | EffectOkCallback<T>,
+	...signals: T
+): void {
+	const callbacks = isFunction(callbacksOrFn)
+        ? { ok: callbacksOrFn }
+        : callbacksOrFn
+
+	const run = () => watch(() => {
+		const result = resolveSignals(signals, callbacks as EffectCallbacks<T>)
+		if (isError(result))
+			console.error('Unhandled error in effect:', result)
     }, run)
 	run()
 }

package/lib/scheduler.d.ts

@@ -0,0 +1,40 @@
+export type EnqueueDedupe = [Element, string];
+export type Watcher = () => void;
+export type Updater = <T>() => T;
+/**
+ * Add active watcher to the array of watchers
+ *
+ * @param {Watcher[]} watchers - watchers of the signal
+ */
+export declare const subscribe: (watchers: Watcher[]) => void;
+/**
+ * Add watchers to the pending set of change notifications
+ *
+ * @param {Watcher[]} watchers - watchers of the signal
+ */
+export declare const notify: (watchers: Watcher[]) => void;
+/**
+ * Flush all pending changes to notify watchers
+ */
+export 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;
+/**
+ * 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
+ */
+export declare const watch: (run: () => void, mark: Watcher) => void;
+/**
+ * Enqueue a function to be executed on the next animation frame
+ *
+ * @param callback
+ * @param dedupe
+ * @returns
+ */
+export declare const enqueue: <T>(update: Updater, dedupe?: EnqueueDedupe) => Promise<T>;