@zeix/cause-effect 0.12.2 → 0.12.3

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.12.2
+Version 0.12.3
 
 **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.
 
@@ -54,7 +54,7 @@ npm install @zeix/cause-effect
 bun add @zeix/cause-effect
 ```
 
-## Basic Usage
+## Usage
 
 ### Single State Signal
 
@@ -214,3 +214,45 @@ This example showcases several powerful features of Cause & Effect:
 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.
+
+### Effects and DOM Updates
+
+The `enqueue()` function allows you to schedule DOM updates to be executed on the next animation frame. This function returns a `Promise`, which makes it easy to detect when updates are applied or if they fail.
+
+```js
+import { enqueue } from '@zeix/cause-effect'
+
+// Schedule a DOM update
+enqueue(() => {
+  document.getElementById('myElement').textContent = 'Updated content'
+})
+  .then(() => console.log('Update applied successfully'))
+  .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:
+
+```js
+import { 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 => {
+	state.set(e.target.value) // Triggers an update on every keystroke
+})
+
+// Define an effect to react to signal changes
+effect(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))
+}, name)
+```
+
+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).
+
+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.

package/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @name Cause & Effect
- * @version 0.12.2
+ * @version 0.12.3
  * @author Esther Brunner
  */
 export { type Signal, type MaybeSignal, type InferMaybeSignalType, type ComputedCallbacks, type EffectCallbacks, UNSET, isSignal, toSignal } from './lib/signal';

package/index.js

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

package/index.ts

@@ -1,6 +1,6 @@
 /**
  * @name Cause & Effect
- * @version 0.12.2
+ * @version 0.12.3
  * @author Esther Brunner
  */
 export {

package/lib/scheduler.d.ts

@@ -1,6 +1,6 @@
 export type EnqueueDedupe = [Element, string];
 export type Watcher = () => void;
-export type Updater = <T>() => T;
+export type Updater = <T>() => T | boolean | void;
 /**
  * Add active watcher to the array of watchers
  *
@@ -27,14 +27,13 @@ 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
+ * @param {Watcher} mark - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
  */
-export declare const watch: (run: () => void, mark: Watcher) => void;
+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
+ * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
+ * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
  */
-export declare const enqueue: <T>(update: Updater, dedupe?: EnqueueDedupe) => Promise<T>;
+export declare const enqueue: <T>(fn: Updater, dedupe?: EnqueueDedupe) => Promise<boolean | void | T>;

package/lib/scheduler.ts

@@ -3,7 +3,7 @@
 export type EnqueueDedupe = [Element, string]
 
 export type Watcher = () => void
-export type Updater = <T>() => T
+export type Updater = <T>() => T | boolean | void
 
 /* === Internal === */
 
@@ -15,16 +15,15 @@ const pending = new Set<Watcher>()
 let batchDepth = 0
 
 // Map of DOM elements to update functions
-const updateMap = new Map<Element, Map<string, () => void>>()
+const updateMap = new Map<EnqueueDedupe, () => void>()
 let requestId: number | undefined
 
 const updateDOM = () => {
 	requestId = undefined
-	for (const elementMap of updateMap.values()) {
-		for (const fn of elementMap.values()) {
-			fn()
-		}
-		elementMap.clear()
+	const updates = Array.from(updateMap.values())
+	updateMap.clear()
+	for (const fn of updates) {
+		fn()
 	}
 }
 
@@ -81,47 +80,49 @@ export const flush = () => {
  */
 export const batch = (fn: () => void) => {
 	batchDepth++
-    fn()
-	flush()
-	batchDepth--
+	try {
+		fn()
+	} finally {
+		flush()
+        batchDepth--
+    }
 }
 
 /**
  * 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
+ * @param {Watcher} mark - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
  */
-export const watch = (run: () => void, mark: Watcher): void => {
+export const watch = (run: () => void, mark?: Watcher): void => {
 	const prev = active
 	active = mark
-	run()
-	active = prev
+	try {
+		run()
+	} finally {
+		active = prev
+	}
 }
 
 /**
  * Enqueue a function to be executed on the next animation frame
  * 
- * @param callback 
- * @param dedupe 
- * @returns 
+ * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
+ * @param {EnqueueDedupe} dedupe - [element, operation] pair for deduplication
  */
 export const enqueue = <T>(
-    update: Updater,
+    fn: Updater,
     dedupe?: EnqueueDedupe
-) => new Promise<T>((resolve, reject) => {
+) => new Promise<T | boolean | void>((resolve, reject) => {
     const wrappedCallback = () => {
         try {
-            resolve(update())
+            resolve(fn())
         } catch (error) {
             reject(error)
         }
     }
     if (dedupe) {
-        const [el, op] = dedupe
-        if (!updateMap.has(el)) updateMap.set(el, new Map())
-        const elementMap = updateMap.get(el)!
-        elementMap.set(op, wrappedCallback)
+        updateMap.set(dedupe, wrappedCallback)
     }
     requestTick()
 })

package/package.json

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