@zeix/cause-effect 0.13.2 → 0.14.0

package/README.md

@@ -1,39 +1,45 @@
 # Cause & Effect
 
-Version 0.13.2
+Version 0.14.0
 
-**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.
+**Cause & Effect** is a lightweight, reactive state management library for JavaScript applications. It uses fine-grained reactivity with signals to create 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.
+**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 dependent computations and effects, ensuring your UI stays in sync with your data without manual intervention.
+
+### Core Concepts
+
+- **State signals**: Hold values that can be directly modified
+- **Computed signals**: Derive values from other signals (either `memo()` for sync or `task()` for async)
+- **Effects**: Run side effects when signals change
 
 ## Key Features
 
 - ⚡ **Reactive States**: Automatic updates when dependencies change
-- 🧩 **Composable**: Chain signals with `.map()` and `.tap()`
+- 🧩 **Composable**: Create a complex signal graph with a minimal API
 - ⏱️ **Async Ready**: Built-in `Promise` and `AbortController` support
 - 🛡️ **Error Handling**: Declare handlers for errors and unset states in effects
 - 🚀 **Performance**: Batching and efficient dependency tracking
-- 📦 **Tiny**: ~1kB gzipped, zero dependencies
+- 📦 **Tiny**: Around 1kB gzipped, zero dependencies
 
 ## Quick Start
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { state, memo, effect } from '@zeix/cause-effect'
 
 // 1. Create state
 const user = state({ name: 'Alice', age: 30 })
 
 // 2. Create computed values
-const greeting = computed(() => `Hello ${user.get().name}!`)
+const greeting = memo(() => `Hello ${user.get().name}!`)
 
 // 3. React to changes
 effect({
-    signals: [user, greeting],
-    ok: ({ age }, greet) => {
-        console.log(`${greet} You are ${age} years old`)
-    }
+  signals: [user, greeting],
+  ok: ({ age }, greet) => {
+    console.log(`${greet} You are ${age} years old`)
+  }
 })
 
 // 4. Update state
@@ -52,113 +58,97 @@ bun add @zeix/cause-effect
 
 ## Usage of Signals
 
-### Single State Signal
-
-`state()` creates a new state signal. To access the current value of the signal use the `.get()` method. To update the value of the signal use the `.set()` method with a new value or `.update()` with an updater function of the form `(v: T) => T`.
+### State Signals
 
-The `.tap()` method on either `State` or `Computed` is a shorthand for creating an effect on the signal.
+`state()` creates a mutable signal. Every signal has a `.get()` method to access its current value. State signals also provide `.set()` to directly assign a new value and `.update()` to modify the value with a function.
 
 ```js
-import { state } from '@zeix/cause-effect'
+import { state, effect } from '@zeix/cause-effect'
 
 const count = state(42)
-count.tap(v => {
-	console.log(v) // logs '42'
+effect(() => {
+  console.log(count.get()) // logs '42'
 })
 count.set(24) // logs '24'
 document.querySelector('.increment').addEventListener('click', () => {
-	count.update(v => ++v)
+  count.update(v => ++v)
 })
 // Click on button logs '25', '26', and so on
 ```
 
-### Sync Computed Signal
+### Computed Signals: memo() and task()
 
-`computed()` creates a new computed signal. Computed signals are read-only and you can access the current resulting value using the `.get()` method.
+#### Synchronous Computations with memo()
+
+`memo()` creates a read-only computed signal for synchronous calculations. It automatically tracks dependencies and updates when they change.
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { state, memo, effect } from '@zeix/cause-effect'
 
 const count = state(42)
-const isOdd = computed(() => count.get() % 2)
+const isOdd = memo(() => 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)
+  count.update(v => ++v)
 })
 // Click on button logs 'true', 'false', and so on
 ```
 
-If you want to derive a computed signal from a single other signal you can use the `.map()` method on either `State` or `Computed`. This does the same as the snippet above:
+#### Asynchronous Computations with task()
 
-```js
-import { state } from '@zeix/cause-effect'
+`task()` creates computed signals for asynchronous operations. It automatically manages promises, tracks dependencies, and handles cancellation through `AbortController`.
 
-const count = state(42)
-count.map(v => v % 2).tap(v => console.log(v)) // logs 'false'
-count.set(24) // logs nothing because 24 is also an even number
-document.querySelector('.increment').addEventListener('click', () => {
-	count.update(v => ++v)
-})
-// Click on button logs 'true', 'false', and so on
-```
-
-### Async Computed Signal
-
-Async computed signals are as straight forward as their sync counterparts. Just create the computed signal with an async function.
-
-**Caution**: Async computed signals will return a Symbol `UNSET` until the Promise is resolved.
+**Note**: Task signals return `UNSET` while pending, which you can handle with the `nil` case in effects.
 
 ```js
-import { state } from '@zeix/cause-effect'
+import { state, task, effect } from '@zeix/cause-effect'
 
 const entryId = state(42)
-const entryData = entryId.map(async id => {
-    const response = await fetch(`/api/entry/${id}`)
-    if (!response.ok) return new Error(`Failed to fetch data: ${response.statusText}`)
-    return response.json()
+const entryData = task(async abort => {
+  const response = await fetch(`/api/entry/${entryId.get()}`, { signal: abort })
+  if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
+  return response.json()
+})
+
+// Display data when available
+effect({
+  signals: [entryData],
+  ok: data => console.log('Data loaded:', data),
+  nil: () => console.log('Loading...'),
+  err: error => console.error('Error:', error)
 })
-// Updates h1 and p of the entry as soon as fetched data for entry becomes available
+
+// Move to next entry, automatically triggers a new fetch
 document.querySelector('button.next').addEventListener('click', () => {
-	entryId.update(v => ++v)
+  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
 ```
 
-## Error Handling
+## Effects and Error Handling
 
-Cause & Effect provides three paths for robust error handling:
+Cause & Effect provides a robust way to handle side effects and errors through the `effect()` function, with three distinct paths:
 
-1. **Ok**: Value is available
-2. **Nil**: Loading/Unset state (especially for async)
-3. **Err**: Error occurred
+1. **Ok**: When values are available
+2. **Nil**: For loading/unset states (primarily with async tasks)
+3. **Err**: When errors occur during computation
 
-Handle all cases declaratively:
+This allows for declarative handling of all possible states:
 
 ```js
 effect({
-    signals: [data],
-    ok: (value) => /* update UI */,
-    nil: () => /* show loading */,
-    err: (error) => /* show error */
+  signals: [data],
+  ok: (value) => /* update UI */,
+  nil: () => /* show loading */,
+  err: (error) => /* show error */
 })
 ```
 
-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 `.tap()` method on either `State` or `Computed`. You can use it for easy debugging, for example:
-
-```js
-signal.tap({
-	ok: v => console.log('Value:', v),
-	nil: () => console.warn('Not ready'),
-	err: e => console.error('Error:', e)
-})
-```
+Instead of using a single callback function, you can provide an object with an `ok` handler (required), plus optional `err` and `nil` handlers. Cause & Effect will automatically route to the appropriate handler based on the state of the signals.
 
 ## DOM Updates
 
-The `enqueue()` function allows you to schedule DOM updates to be executed on the next animation frame. It returns a `Promise`, which makes it easy to detect when updates are applied or if they fail.
+The `enqueue()` function allows you to schedule DOM updates to be executed on the next animation frame. It returns a `Promise`, which makes it easy to track when updates are applied or handle errors.
 
 ```js
 import { enqueue } from '@zeix/cause-effect'
@@ -171,7 +161,11 @@ enqueue(() => {
   .catch(error => console.error('Update failed:', error))
 ```
 
-You can also use the deduplication feature to ensure that only the latest update for a specific element and operation is applied:
+### Deduplication with Symbols
+
+A powerful feature of `enqueue()` is deduplication, which ensures that only the most recent update for a specific operation is applied when multiple updates occur within a single animation frame. This is particularly useful for high-frequency events like typing, dragging, or scrolling.
+
+Deduplication is controlled using JavaScript Symbols:
 
 ```js
 import { state, effect, enqueue } from '@zeix/cause-effect'
@@ -179,57 +173,95 @@ import { state, effect, enqueue } from '@zeix/cause-effect'
 // Define a signal and update it in an event handler
 const name = state('')
 document.querySelector('input[name="name"]').addEventListener('input', e => {
-	name.set(e.target.value) // Triggers an update on every keystroke
+  name.set(e.target.value) // Triggers an update on every keystroke
 })
 
 // Define an effect to react to signal changes
-name.tap(text => {
-	const nameSpan = document.querySelector('.greeting .name')
-	enqueue(() => {
-		nameSpan.textContent = text
-		return text
-	}, [nameSpan, 'setName']) // For deduplication
-		.then(result => console.log(`Name was updated to ${result}`))
-		.catch(error => console.error('Failed to update name:', error))
+effect(text => {
+  // Create a Symbol for a specific update operation
+  const NAME_UPDATE = Symbol('name-update')
+  const text = name.get()
+  const nameSpan = document.querySelector('.greeting .name')
+  enqueue(() => {
+    nameSpan.textContent = text
+    return text
+  }, NAME_UPDATE) // Using the Symbol for deduplication
+    .then(result => console.log(`Name was updated to ${result}`))
+    .catch(error => console.error('Failed to update name:', error))
 })
 ```
 
-In this example, as the user types in the input field only 'Jane' will be applied to the DOM. 'J', 'Ja', 'Jan' were superseded by more recent updates and deduplicated (if typing was fast enough).
+In this example, as the user types "Jane" quickly, the intermediate values ('J', 'Ja', 'Jan') are deduplicated, and only the final value 'Jane' is applied to the DOM. Only the Promise for the final update is resolved.
+
+### How Deduplication Works
+
+When multiple `enqueue` calls use the same Symbol before the next animation frame:
+
+1. Only the last call will be executed
+2. Previous calls are superseded
+3. Only the Promise of the last call will be resolved
+
+This "last-write-wins" behavior optimizes DOM updates and prevents unnecessary work when many updates happen rapidly.
+
+### Optional Deduplication
+
+The deduplication Symbol is optional. When not provided, a unique Symbol is created automatically, ensuring the update is always executed:
+
+```js
+// No deduplication - always executed
+enqueue(() => document.title = 'New Page Title')
+
+// Create symbols for different types of updates
+const COLOR_UPDATE = Symbol('color-update')
+const SIZE_UPDATE = Symbol('size-update')
+
+// These won't interfere with each other (different symbols)
+enqueue(() => element.style.color = 'red', COLOR_UPDATE)
+enqueue(() => element.style.fontSize = '16px', SIZE_UPDATE)
+
+// This will replace the previous color update (same symbol)
+enqueue(() => element.style.color = 'blue', COLOR_UPDATE)
+```
+
+Using Symbols for deduplication provides:
 
-When multiple `enqueue` calls are made with the same deduplication key before the next animation frame, only the last call will be executed. Previous calls are superseded and their Promises will not be resolved or rejected. This "last-write-wins" behavior ensures that only the most recent update is applied, which is typically desirable for UI updates and state changes.
+- Clear semantic meaning for update operations
+- Type safety in TypeScript
+- Simple mechanism to control which updates should overwrite each other
+- Flexibility to run every update when needed
 
 ## Advanced Usage
 
-### Batching
+### Batching Updates
 
-Effects run synchronously as soon as source signals update. If you need to set multiple signals you can batch them together to ensure dependent effects are executed simultanously and only once.
+Use `batch()` to group multiple signal updates, ensuring effects run only once after all changes are applied:
 
 ```js
-import { state, computed, batch } from '@zeix/cause-effect'
+import { state, memo, effect, 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({
-	signals,
-	ok: (...values) => values.reduce((total, v) => total + v, 0),
-}).map(v => { // ... perform validation and handle errors
-	if (!Number.isFinite(v)) throw new Error('Invalid value')
-	return v
+// Compute the sum of all signals
+const sum = memo(() => {
+  const v = signals.reduce((total, signal) => total + signal.get(), 0)
+  // Validate the result
+  if (!Number.isFinite(v)) throw new Error('Invalid value')
+  return v
 })
 
-// Effect: switch cases for the result
-sum.tap({
-	ok: v => console.log('Sum:', v),
-	err: error => console.error('Error:', error)
+// Effect: handle the result
+effect({
+  signals: [sum],
+  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))
-	})
+  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)
@@ -238,31 +270,28 @@ document.querySelector('.double-all').addEventListener('click', () => {
 signals[0].set(NaN)
 ```
 
-This example showcases several powerful features of Cause & Effect:
+The Cause & Effect library is designed around these principles:
 
-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.
+- **Minimal API**: Core primitives with a small but powerful interface
+- **Automatic Dependency Tracking**: Fine-grained reactivity with minimal boilerplate
+- **Tree-Shakable**: Import only what you need for optimal bundle size
+- **Flexible Integration**: Works with 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.
-
-### Cleanup
+### Cleanup Functions
 
 Effects return a cleanup function. When executed, it will unsubscribe from signals and run cleanup functions returned by effect callbacks, for example to remove event listeners.
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { state, memo, effect } from '@zeix/cause-effect'
 
 const user = state({ name: 'Alice', age: 30 })
-const greeting = computed(() => `Hello ${user.get().name}!`)
+const greeting = memo(() => `Hello ${user.get().name}!`)
 const cleanup = effect({
-    signals: [user, greeting],
-    ok: ({ age }, greet) => {
-        console.log(`${greet} You are ${age} years old`)
-        return () => console.log('Cleanup') // Cleanup function
-    }
+  signals: [user, greeting],
+  ok: ({ age }, greet) => {
+    console.log(`${greet} You are ${age} years old`)
+    return () => console.log('Cleanup') // Cleanup function
+  }
 })
 
 // When you no longer need the effect, execute the cleanup function
@@ -271,34 +300,35 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signals `user` and `greeting`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
-### Abort Controller
+### Automatic Abort Control
 
-For asynchronous computed signals, Cause & Effect uses an `AbortController` to cancel pending promises when source signals update. You can use the `abort` parameter in `computed()` callbacks and pass it on to other AbortController aware APIs like `fetch()`:
+For asynchronous operations, `task()` automatically manages cancellation when dependencies change, providing an `abort` signal parameter:
 
 ```js
-import { state, computed } from '@zeix/cause-effect'
+import { state, task, effect } from '@zeix/cause-effect'
 
 const id = state(42)
-const url = id.map(v => `https://example.com/api/entries/${v}`)
-const data = computed(async abort => {
-	const response = await fetch(url.get(), { signal: abort })
-	if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
-	return response.json()
+const url = memo(v => `https://example.com/api/entries/${id.get()}`)
+const data = task(async abort => {
+  const response = await fetch(url.get(), { signal: abort })
+  if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
+  return response.json()
 })
-data.tap({
-	ok: v => console.log('Value:', v),
-	nil: () => console.warn('Not ready'),
-	err: e => console.error('Error:', e)
+effect({
+  signals: [data],
+  ok: v => console.log('Value:', v),
+  nil: () => console.warn('Not ready'),
+  err: e => console.error('Error:', e)
 })
 
 // User switches to another entry
-id.set(24) // Cancels or ignores the previous fetch request and starts a new one
+id.set(24) // Cancels the previous fetch request and starts a new one
 ```
 
 ## Contributing & License
 
 Feel free to contribute, report issues, or suggest improvements.
 
-Licence: [MIT](LICENCE.md)
+License: [MIT](LICENSE)
 
 (c) 2025 [Zeix AG](https://zeix.com)

package/index.d.ts

@@ -1,11 +1,13 @@
 /**
  * @name Cause & Effect
- * @version 0.13.2
+ * @version 0.14.0
  * @author Esther Brunner
  */
 export { CircularDependencyError } from './src/util';
-export { type Signal, type MaybeSignal, type ComputedCallback, UNSET, isSignal, isComputedCallback, toSignal, } from './src/signal';
+export { type Signal, type MaybeSignal, UNSET, isSignal, isComputedCallback, toSignal, } from './src/signal';
 export { type State, state, isState } from './src/state';
-export { type Computed, type ComputedMatcher, computed, isComputed, } from './src/computed';
-export { type EffectMatcher, type TapMatcher, effect } from './src/effect';
-export { type EnqueueDedupe, batch, watch, enqueue } from './src/scheduler';
+export { type Computed, type ComputedCallback, computed, isComputed, } from './src/computed';
+export { type MemoCallback, memo } from './src/memo';
+export { type TaskCallback, task } from './src/task';
+export { type EffectMatcher, effect } from './src/effect';
+export { batch, watch, enqueue } from './src/scheduler';

package/index.js

@@ -1 +1 @@
-var X=(x)=>typeof x==="function",d=(x)=>X(x)&&x.constructor.name==="AsyncFunction",P=(x,y)=>Object.prototype.toString.call(x)===`[object ${y}]`,c=(x)=>x instanceof Error,I=(x)=>x instanceof DOMException&&x.name==="AbortError",m=(x)=>x instanceof Promise,C=(x)=>c(x)?x:Error(String(x));class A extends Error{constructor(x){super(`Circular dependency in ${x} detected`);return this}}var j,R=new Set,U=0,_=new Map,D,v=()=>{D=void 0;let x=Array.from(_.values());_.clear();for(let y of x)y()},t=()=>{if(D)cancelAnimationFrame(D);D=requestAnimationFrame(v)};queueMicrotask(v);var N=(x)=>{if(j&&!x.has(j)){let y=j;x.add(y),j.cleanups.add(()=>{x.delete(y)})}},V=(x)=>{for(let y of x)if(U)R.add(y);else y()},k=()=>{while(R.size){let x=Array.from(R);R.clear();for(let y of x)y()}},a=(x)=>{U++;try{x()}finally{k(),U--}},M=(x,y)=>{let z=j;j=y;try{x()}finally{j=z}},r=(x,y)=>new Promise((z,J)=>{_.set(y,()=>{try{z(x())}catch(B){J(B)}}),t()});function Y(x){let{signals:y,ok:z,err:J=console.error,nil:B=()=>{}}=X(x)?{signals:[],ok:x}:x,L=!1,K=()=>M(()=>{if(L)throw new A("effect");L=!0;let H=void 0;try{H=S({signals:y,ok:z,err:J,nil:B})}catch(Q){J(C(Q))}if(X(H))K.cleanups.add(H);L=!1},K);return K.cleanups=new Set,K(),()=>{K.cleanups.forEach((H)=>H()),K.cleanups.clear()}}var o="Computed",e=(x,y)=>{if(!y)return!1;return x.name===y.name&&x.message===y.message},F=(x)=>{let y=new Set,z=X(x)?void 0:{nil:()=>Z,err:(...$)=>{if($.length>1)throw new AggregateError($);else throw $[0]},...x},J=z?z.ok:x,B=Z,L,K=!0,H=!1,Q=!1,G,W=($)=>{if(!Object.is($,B))B=$,K=!1,L=void 0,H=!0},g=()=>{H=Z!==B,B=Z,L=void 0},p=($)=>{let O=C($);H=!e(O,L),B=Z,L=O},n=($)=>{if(Q=!1,G=void 0,W($),H)V(y)},u=($)=>{if(Q=!1,G=void 0,p($),H)V(y)},l=()=>{Q=!1,G=void 0,f()},q=()=>{if(K=!0,G?.abort("Aborted because source signal changed"),y.size)V(y);else q.cleanups.forEach(($)=>$()),q.cleanups.clear()};q.cleanups=new Set;let f=()=>M(()=>{if(Q)throw new A("computed");if(H=!1,d(J)){if(G)return B;if(G=new AbortController,z)z.abort=z.abort instanceof AbortSignal?AbortSignal.any([z.abort,G.signal]):G.signal;G.signal.addEventListener("abort",l,{once:!0})}let $;Q=!0;try{$=z&&z.signals.length?S(z):J(G?.signal)}catch(O){if(I(O))g();else p(O);Q=!1;return}if(m($))$.then(n,u);else if($==null||Z===$)g();else W($);Q=!1},q),T={[Symbol.toStringTag]:o,get:()=>{if(N(y),k(),K)f();if(L)throw L;return B},map:($)=>F({signals:[T],ok:$}),tap:($)=>Y({signals:[T],...X($)?{ok:$}:$})};return T},b=(x)=>P(x,o);var i="State",E=(x)=>{let y=new Set,z=x,J={[Symbol.toStringTag]:i,get:()=>{return N(y),z},set:(B)=>{if(Object.is(z,B))return;if(z=B,V(y),Z===z)y.clear()},update:(B)=>{J.set(B(z))},map:(B)=>F({signals:[J],ok:B}),tap:(B)=>Y({signals:[J],...X(B)?{ok:B}:B})};return J},w=(x)=>P(x,i);var Z=Symbol(),h=(x)=>w(x)||b(x),s=(x)=>X(x)&&x.length<2,xx=(x)=>h(x)?x:s(x)?F(x):E(x),S=(x)=>{let{signals:y,abort:z,ok:J,err:B,nil:L}=x,K=[],H=!1,Q=y.map((G)=>{try{let W=G.get();if(W===Z)H=!0;return W}catch(W){if(I(W))throw W;K.push(C(W))}});try{return H?L(z):K.length?B(...K):J(...Q)}catch(G){if(I(G))throw G;let W=C(G);return B(W)}};export{M as watch,xx as toSignal,E as state,w as isState,h as isSignal,s as isComputedCallback,b as isComputed,r as enqueue,Y as effect,F as computed,a as batch,Z as UNSET,A as CircularDependencyError};
+var O=($)=>typeof $==="function",p=($)=>O($)&&$.constructor.name==="AsyncFunction",N=($,B)=>Object.prototype.toString.call($)===`[object ${B}]`,c=($)=>$ instanceof Error,q=($)=>$ instanceof DOMException&&$.name==="AbortError",d=($)=>$ instanceof Promise,M=($)=>c($)?$:Error(String($));class x extends Error{constructor($){super(`Circular dependency in ${$} detected`);return this}}var V,k=new Set,U=0,b=new Map,_,h=()=>{_=void 0;let $=Array.from(b.values());b.clear();for(let B of $)B()},n=()=>{if(_)cancelAnimationFrame(_);_=requestAnimationFrame(h)};queueMicrotask(h);var Y=($)=>{if(V&&!$.has(V)){let B=V;$.add(B),V.cleanups.add(()=>{$.delete(B)})}},A=($)=>{for(let B of $)if(U)k.add(B);else B()},C=()=>{while(k.size){let $=Array.from(k);k.clear();for(let B of $)B()}},l=($)=>{U++;try{$()}finally{C(),U--}},R=($,B)=>{let z=V;V=B;try{$()}finally{V=z}},u=($,B)=>new Promise((z,F)=>{b.set(B||Symbol(),()=>{try{z($())}catch(L){F(L)}}),n()});var v="State",S=($)=>{let B=new Set,z=$,F={[Symbol.toStringTag]:v,get:()=>{return Y(B),z},set:(L)=>{if(Object.is(z,L))return;if(z=L,A(B),K===z)B.clear()},update:(L)=>{F.set(L(z))}};return F},T=($)=>N($,v);var w=($)=>{let B=new Set,z=K,F,L=!0,X=!1,H=()=>{if(L=!0,B.size)A(B);else H.cleanups.forEach((W)=>W()),H.cleanups.clear()};H.cleanups=new Set;let Q=()=>R(()=>{if(X)throw new x("memo");X=!0;try{let W=$();if(W==null||K===W)z=K,F=void 0;else z=W,L=!1,F=void 0}catch(W){z=K,F=W instanceof Error?W:new Error(String(W))}finally{X=!1}},H);return{[Symbol.toStringTag]:y,get:()=>{if(Y(B),C(),L)Q();if(F)throw F;return z}}};var g=($)=>{let B=new Set,z=K,F,L=!0,X=!1,H=!1,Q,j=(J)=>{if(!Object.is(J,z))z=J,L=!1,F=void 0,X=!0},W=()=>{X=K!==z,z=K,F=void 0},D=(J)=>{let I=M(J);X=!(F&&I.name===F.name&&I.message===F.message),z=K,F=I},G=(J)=>{if(H=!1,Q=void 0,j(J),X)A(B)},Z=(J)=>{if(H=!1,Q=void 0,D(J),X)A(B)},i=()=>{H=!1,Q=void 0,m()},P=()=>{if(L=!0,Q?.abort("Aborted because source signal changed"),B.size)A(B);else P.cleanups.forEach((J)=>J()),P.cleanups.clear()};P.cleanups=new Set;let m=()=>R(()=>{if(H)throw new x("task");X=!1,Q=new AbortController,Q.signal.addEventListener("abort",i,{once:!0});let J;H=!0;try{J=$(Q.signal)}catch(I){if(q(I))W();else D(I);H=!1;return}if(d(J))J.then(G,Z);else if(J==null||K===J)W();else j(J);H=!1},P);return{[Symbol.toStringTag]:y,get:()=>{if(Y(B),C(),L)m();if(F)throw F;return z}}};var y="Computed",E=($)=>p($)?g($):w($),f=($)=>N($,y);var K=Symbol(),o=($)=>T($)||f($),s=($)=>O($)&&$.length<2,t=($)=>o($)?$:s($)?E($):S($);function r($){let{signals:B,ok:z,err:F=console.error,nil:L=()=>{}}=O($)?{signals:[],ok:$}:$,X=!1,H=()=>R(()=>{if(X)throw new x("effect");X=!0;let Q=void 0;try{let j=[],W=!1,D=B.map((G)=>{try{let Z=G.get();if(Z===K)W=!0;return Z}catch(Z){if(q(Z))throw Z;return j.push(M(Z)),K}});try{Q=W?L():j.length?F(...j):z(...D)}catch(G){if(q(G))throw G;let Z=M(G);Q=F(Z)}}catch(j){F(M(j))}if(O(Q))H.cleanups.add(Q);X=!1},H);return H.cleanups=new Set,H(),()=>{H.cleanups.forEach((Q)=>Q()),H.cleanups.clear()}}export{R as watch,t as toSignal,g as task,S as state,w as memo,T as isState,o as isSignal,s as isComputedCallback,f as isComputed,u as enqueue,r as effect,E as computed,l as batch,K as UNSET,x as CircularDependencyError};

package/index.ts

@@ -1,25 +1,25 @@
 /**
  * @name Cause & Effect
- * @version 0.13.2
+ * @version 0.14.0
  * @author Esther Brunner
  */
 export { CircularDependencyError } from './src/util'
 export {
 	type Signal,
 	type MaybeSignal,
-	type ComputedCallback,
 	UNSET,
 	isSignal,
 	isComputedCallback,
 	toSignal,
 } from './src/signal'
-
 export { type State, state, isState } from './src/state'
 export {
 	type Computed,
-	type ComputedMatcher,
+	type ComputedCallback,
 	computed,
 	isComputed,
 } from './src/computed'
-export { type EffectMatcher, type TapMatcher, effect } from './src/effect'
-export { type EnqueueDedupe, batch, watch, enqueue } from './src/scheduler'
+export { type MemoCallback, memo } from './src/memo'
+export { type TaskCallback, task } from './src/task'
+export { type EffectMatcher, effect } from './src/effect'
+export { batch, watch, enqueue } from './src/scheduler'

package/package.json

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

package/src/computed.d.ts

@@ -1,28 +1,25 @@
-import { type Signal, type ComputedCallback } from './signal';
-import { type TapMatcher } from './effect';
-export type ComputedMatcher<S extends Signal<{}>[], R extends {}> = {
-    signals: S;
-    abort?: AbortSignal;
-    ok: (...values: {
-        [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
-    }) => R | Promise<R>;
-    err?: (...errors: Error[]) => R | Promise<R>;
-    nil?: () => R | Promise<R>;
-};
-export type Computed<T extends {}> = {
+import { type MemoCallback } from './memo';
+import { type TaskCallback } from './task';
+type Computed<T extends {}> = {
     [Symbol.toStringTag]: 'Computed';
     get(): T;
-    map<U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U>;
-    tap(matcher: TapMatcher<T> | ((v: T) => void | (() => void))): () => void;
 };
+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 {ComputedMatcher<S, T> | ComputedCallback<T>} matcher - computed matcher or callback
+ * @param {ComputedCallback<T>} fn - computation callback function
  * @returns {Computed<T>} - Computed signal
  */
-export declare const computed: <T extends {}, S extends Signal<{}>[] = []>(matcher: ComputedMatcher<S, T> | ComputedCallback<T>) => Computed<T>;
+declare const computed: <T extends {}>(fn: ComputedCallback<T>) => Computed<T>;
 /**
  * Check if a value is a computed state
  *
@@ -30,4 +27,5 @@ export declare const computed: <T extends {}, S extends Signal<{}>[] = []>(match
  * @param {unknown} value - value to check
  * @returns {boolean} - true if value is a computed state, false otherwise
  */
-export declare const isComputed: <T extends {}>(value: unknown) => value is Computed<T>;
+declare const isComputed: <T extends {}>(value: unknown) => value is Computed<T>;
+export { type Computed, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, };