@zeix/cause-effect 0.13.2 → 0.14.1

package/README.md

@@ -1,21 +1,27 @@
 # Cause & Effect
 
-Version 0.13.2
+Version 0.14.1
 
-**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: `state()`
+- **Computed signals**: Derive memoized values from other signals: `computed()`
+- **Effects**: Run side effects when signals change: `effect()`
 
 ## 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
 
@@ -29,11 +35,8 @@ const user = state({ name: 'Alice', age: 30 })
 const greeting = computed(() => `Hello ${user.get().name}!`)
 
 // 3. React to changes
-effect({
-    signals: [user, greeting],
-    ok: ({ age }, greet) => {
-        console.log(`${greet} You are ${age} years old`)
-    }
+effect(() => {
+  console.log(`${greeting.get()} You are ${user.get().age} years old`)
 })
 
 // 4. Update state
@@ -52,113 +55,121 @@ 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 vs. Functions
 
-`computed()` creates a new computed signal. Computed signals are read-only and you can access the current resulting value using the `.get()` method.
+#### When to Use Computed Signals
+
+`computed()` creates a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
 
 ```js
 import { state, computed, effect } from '@zeix/cause-effect'
 
 const count = state(42)
-const isOdd = computed(() => count.get() % 2)
-effect(() => console.log(isOdd.get())) // logs 'false'
+const isEven = computed(() => !(count.get() % 2))
+effect(() => console.log(isEven.get())) // logs 'true'
 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
+// Click on button logs 'false', 'true', 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:
+#### When to Use Functions
 
-```js
-import { state } from '@zeix/cause-effect'
+**Performance tip**: For simple derivations, plain functions often outperform computed signals:
 
-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
+```js
+// More performant for simple calculations
+const isEven = () => !(count.get() % 2)
 ```
 
-### Async Computed Signal
+**When to use which approach:**
 
-Async computed signals are as straight forward as their sync counterparts. Just create the computed signal with an async function.
+- **Use functions when**: The calculation is simple, inexpensive, or called infrequently
+- **Use computed() when**:
+  - The calculation is expensive
+  - You need to share the result between multiple consumers
+  - You're working with asynchronous operations
+  - You need to track specific error states
 
-**Caution**: Async computed signals will return a Symbol `UNSET` until the Promise is resolved.
+#### Asynchronous Computations with Automatic Cancellation
+
+`computed()` seamlessly handles asynchronous operations with built-in cancellation support. When used with an async function, it:
+
+1. Provides an `abort` signal parameter you can pass to fetch or other cancelable APIs
+2. Automatically cancels pending operations when dependencies change
+3. Returns `UNSET` while the Promise is pending
+4. Properly handles errors from failed requests
 
 ```js
-import { state } from '@zeix/cause-effect'
+import { state, computed, 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 id = state(42)
+const data = computed(async abort => {
+  // The abort signal is automatically managed by the computed signal
+  const response = await fetch(`/api/entries/${id.get()}`, { signal: abort })
+  if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
+  return response.json()
 })
-// Updates h1 and p of the entry as soon as fetched data for entry becomes available
+
+// Handle all possible states
+effect({
+  signals: [data],
+  ok: json => console.log('Data loaded:', json),
+  nil: () => console.log('Loading...'),
+  err: error => console.error('Error:', error)
+})
+
+// When id changes, the previous request is automatically canceled
 document.querySelector('button.next').addEventListener('click', () => {
-	entryId.update(v => ++v)
+  id.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
+**Note**: Always use `computed()` (not plain functions) for async operations to benefit from automatic cancellation, memoization, and state management.
+
+## 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 (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 when data is available */,
+  nil: () => /* show loading state while pending */,
+  err: (error) => /* show error message when computation fails */
 })
 ```
 
-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. If not provided, Cause & Effect will assume `console.error` for `err` and a no-op for `nil`.
 
 ## 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 +182,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 +194,97 @@ 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.
 
-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.
+### 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:
+
+- 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, computed, 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 = computed(() => {
+  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,17 +293,15 @@ 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
+- **Performance-Focused**: Choose the right tool (functions vs computed) for optimal speed
+- **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.
 
@@ -256,49 +309,22 @@ Effects return a cleanup function. When executed, it will unsubscribe from signa
 import { state, computed, effect } from '@zeix/cause-effect'
 
 const user = state({ name: 'Alice', age: 30 })
-const greeting = computed(() => `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
-    }
+const greeting = () => `Hello ${user.get().name}!`
+const cleanup = effect(() => {
+	console.log(`${greeting()} You are ${user.get().age} years old`)
+	return () => console.log('Cleanup') // Cleanup function
 })
 
 // When you no longer need the effect, execute the cleanup function
-cleanup() // Logs: 'Cleanup' and unsubscribes from signals `user` and `greeting`
+cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
-### Abort Controller
-
-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()`:
-
-```js
-import { state, computed } 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()
-})
-data.tap({
-	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
-```
-
 ## 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,11 @@
 /**
  * @name Cause & Effect
- * @version 0.13.2
+ * @version 0.14.1
  * @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, computed, isComputed, } from './src/computed';
-export { type EffectMatcher, type TapMatcher, effect } from './src/effect';
-export { type EnqueueDedupe, batch, watch, enqueue } from './src/scheduler';
+export { isFunction, CircularDependencyError } from './src/util';
+export { type Signal, type MaybeSignal, type SignalValues, UNSET, isSignal, isComputedCallback, toSignal, } from './src/signal';
+export { type State, TYPE_STATE, state, isState } from './src/state';
+export { type Computed, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, } from './src/computed';
+export { type EffectMatcher, effect } from './src/effect';
+export { type Watcher, type Cleanup, type Updater, watch, subscribe, notify, flush, batch, observe, 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 j=($)=>typeof $==="function",M=($,B)=>Object.prototype.toString.call($)===`[object ${B}]`,Y=($)=>$ instanceof Error?$:Error(String($));class F extends Error{constructor($){super(`Circular dependency in ${$} detected`);return this}}var y,N=new Set,U=0,k=new Map,D,f=()=>{D=void 0;let $=Array.from(k.values());k.clear();for(let B of $)B()},d=()=>{if(D)cancelAnimationFrame(D);D=requestAnimationFrame(f)};queueMicrotask(f);var I=($)=>{let B=new Set,W=$;return W.off=(z)=>{B.add(z)},W.cleanup=()=>{for(let z of B)z();B.clear()},W},O=($)=>{if(y&&!$.has(y)){let B=y;$.add(B),y.off(()=>{$.delete(B)})}},R=($)=>{for(let B of $)if(U)N.add(B);else B()},P=()=>{while(N.size){let $=Array.from(N);N.clear();for(let B of $)B()}},h=($)=>{U++;try{$()}finally{P(),U--}},q=($,B)=>{let W=y;y=B;try{$()}finally{y=W}},v=($,B)=>new Promise((W,z)=>{k.set(B||Symbol(),()=>{try{W($())}catch(G){z(G)}}),d()});var _="State",S=($)=>{let B=new Set,W=$,z={[Symbol.toStringTag]:_,get:()=>{return O(B),W},set:(G)=>{if(Object.is(W,G))return;if(W=G,R(B),J===W)B.clear()},update:(G)=>{z.set(G(W))}};return z},T=($)=>M($,_);var b="Computed",E=($)=>{let B=new Set,W=J,z,G,X=!0,K=!1,L=!1,x=(H)=>{if(!Object.is(H,W))W=H,K=!0;z=void 0,X=!1},C=()=>{K=J!==W,W=J,z=void 0},Z=(H)=>{let Q=Y(H);K=!z||Q.name!==z.name||Q.message!==z.message,W=J,z=Q},A=(H)=>(Q)=>{if(L=!1,G=void 0,H(Q),K)R(B)},V=I(()=>{if(X=!0,G?.abort("Aborted because source signal changed"),B.size)R(B);else V.cleanup()}),w=()=>q(()=>{if(L)throw new F("computed");if(K=!1,j($)&&$.constructor.name==="AsyncFunction"){if(G)return W;G=new AbortController,G.signal.addEventListener("abort",()=>{L=!1,G=void 0,w()},{once:!0})}let H;L=!0;try{H=G?$(G.signal):$()}catch(Q){if(Q instanceof DOMException&&Q.name==="AbortError")C();else Z(Q);L=!1;return}if(H instanceof Promise)H.then(A(x),A(Z));else if(H==null||J===H)C();else x(H);L=!1},V);return{[Symbol.toStringTag]:b,get:()=>{if(O(B),P(),X)w();if(z)throw z;return W}}},g=($)=>M($,b),m=($)=>j($)&&$.length<2;var J=Symbol(),p=($)=>T($)||g($),o=($)=>p($)?$:m($)?E($):S($);function s($){let{signals:B,ok:W,err:z=console.error,nil:G=()=>{}}=j($)?{signals:[],ok:$}:$,X=!1,K=I(()=>q(()=>{if(X)throw new F("effect");X=!0;let L=[],x=!1,C=B.map((A)=>{try{let V=A.get();if(V===J)x=!0;return V}catch(V){return L.push(Y(V)),J}}),Z=void 0;try{Z=x?G():L.length?z(...L):W(...C)}catch(A){Z=z(Y(A))}finally{if(j(Z))K.off(Z)}X=!1},K));return K(),()=>K.cleanup()}export{I as watch,o as toSignal,O as subscribe,S as state,q as observe,R as notify,T as isState,p as isSignal,j as isFunction,m as isComputedCallback,g as isComputed,P as flush,v as enqueue,s as effect,E as computed,h as batch,J as UNSET,_ as TYPE_STATE,b as TYPE_COMPUTED,F as CircularDependencyError};

package/index.ts

@@ -1,25 +1,36 @@
 /**
  * @name Cause & Effect
- * @version 0.13.2
+ * @version 0.14.1
  * @author Esther Brunner
  */
-export { CircularDependencyError } from './src/util'
+export { isFunction, CircularDependencyError } from './src/util'
 export {
 	type Signal,
 	type MaybeSignal,
-	type ComputedCallback,
+	type SignalValues,
 	UNSET,
 	isSignal,
 	isComputedCallback,
 	toSignal,
 } from './src/signal'
-
-export { type State, state, isState } from './src/state'
+export { type State, TYPE_STATE, state, isState } from './src/state'
 export {
 	type Computed,
-	type ComputedMatcher,
+	type ComputedCallback,
+	TYPE_COMPUTED,
 	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 EffectMatcher, effect } from './src/effect'
+export {
+	type Watcher,
+	type Cleanup,
+	type Updater,
+	watch,
+	subscribe,
+	notify,
+	flush,
+	batch,
+	observe,
+	enqueue,
+} from './src/scheduler'

package/package.json

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

package/src/computed.d.ts

@@ -1,28 +1,19 @@
-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 {}> = {
+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;
+}> = ((abort: AbortSignal) => Promise<T>) | (() => T);
+declare const TYPE_COMPUTED = "Computed";
 /**
  * Create a derived signal from existing signals
  *
  * @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 +21,13 @@ 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>;
+/**
+ * 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, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, isComputedCallback, };