balises 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
   <img alt="balises" src="./assets/logo.svg" width="280">
 </picture>
 
-### A minimal reactive HTML templating library. ~2.9KB gzipped.
+### A minimal reactive HTML templating library. ~3.0KB gzipped.
 
 **[📚️ Documentation & Examples](https://elbywan.github.io/balises/)**
 
@@ -28,7 +28,9 @@ import { html, signal } from "balises";
 const count = signal(0);
 
 const { fragment, dispose } = html`
-  <button @click=${() => count.value++}>Clicked ${count} times</button>
+  <button @click=${() => count.update((n) => n + 1)}>
+    Clicked ${count} times
+  </button>
 `.render();
 
 document.body.appendChild(fragment);
@@ -132,6 +134,20 @@ console.log(name.value); // "world"
 name.value = "everyone"; // Notifies subscribers
 ```
 
+**Updating based on current value:**
+
+```ts
+const count = signal(0);
+
+// Using update() for functional updates
+count.update((n) => n + 1);
+count.update((n) => n * 2);
+
+// Equivalent to:
+count.value = count.value + 1;
+count.value = count.value * 2;
+```
+
 ### `computed<T>(fn)` / `new Computed<T>(fn)`
 
 Creates a derived value that auto-tracks dependencies.
@@ -148,6 +164,47 @@ console.log(fullName.value); // "Jane Doe"
 
 Computeds are lazy - they only recompute when accessed and when their dependencies have changed.
 
+### `effect(fn)`
+
+Creates a side effect that automatically re-runs when its dependencies change. Unlike `computed()`, effects run immediately and are intended for side effects like DOM updates, logging, or persistence.
+
+```ts
+import { signal, effect } from "balises";
+
+const count = signal(0);
+
+// Runs immediately, then whenever count changes
+const dispose = effect(() => {
+  console.log("Count is now:", count.value);
+  document.title = `Count: ${count.value}`;
+});
+
+count.value = 1; // Logs "Count is now: 1" and updates title
+dispose(); // Stop the effect
+```
+
+**Use cases:**
+
+- Syncing state to localStorage
+- Updating document.title or other DOM properties
+- Logging and analytics
+- Network requests triggered by state changes
+
+Effects are automatically disposed when the component that created them is disposed (via the template's `dispose()` function).
+
+**Example: Auto-sync to localStorage**
+
+```ts
+const favorites = signal([]);
+
+effect(() => {
+  localStorage.setItem("favorites", JSON.stringify(favorites.value));
+});
+
+// localStorage automatically updates whenever favorites changes
+favorites.value = [...favorites.value, "new item"];
+```
+
 ### `store<T>(obj)`
 
 Proxy-based reactive wrapper. Nested plain objects are wrapped recursively.
@@ -158,6 +215,23 @@ state.count++; // Reactive
 state.user.name = "Bob"; // Also reactive (nested)
 ```
 
+**Note:** Array mutations like `push()`, `pop()`, `splice()` do **not** trigger reactivity. To update arrays reactively, reassign them:
+
+```ts
+const state = store({ items: [1, 2, 3] });
+
+// ❌ Does NOT trigger reactivity
+state.items.push(4);
+
+// ✅ Triggers reactivity
+state.items = [...state.items, 4];
+
+// Alternative: Use signal for arrays if you want .update() method
+const items = signal([1, 2, 3]);
+items.update((arr) => [...arr, 4]);
+items.update((arr) => arr.filter((n) => n !== 2));
+```
+
 ### `batch<T>(fn)`
 
 Batch multiple signal updates to defer subscriber notifications until the batch completes.
@@ -174,6 +248,28 @@ batch(() => {
 }); // Subscribers notified once after both updates
 ```
 
+### `scope(fn)`
+
+Create a disposal scope that automatically collects all computeds and effects created within, allowing cleanup with a single `dispose()` call.
+
+```ts
+import { scope, signal, computed, effect } from "balises";
+
+const [state, dispose] = scope(() => {
+  const count = signal(0);
+  const doubled = computed(() => count.value * 2);
+  effect(() => console.log(doubled.value));
+  return { count, doubled };
+});
+
+// Use state.count, state.doubled...
+
+// Later: clean up everything at once
+dispose();
+```
+
+Useful for components, temporary reactive contexts, or any scenario where you want automatic cleanup of multiple reactive primitives.
+
 ### `isSignal(value)`
 
 Type guard to check if a value is reactive (`Signal` or `Computed`).
@@ -212,17 +308,18 @@ doubled.dispose(); // Stops tracking, frees memory
 The library supports granular imports for optimal bundle size:
 
 ```ts
-// Full library (~2.9KB gzipped)
-import { html, signal, computed } from "balises";
+// Full library (~3.0KB gzipped)
+import { html, signal, computed, effect } from "balises";
 
 // Signals only
-import { signal, computed, store, batch } from "balises/signals";
+import { signal, computed, effect, store, batch, scope } from "balises/signals";
 
 // Individual modules
 import { signal } from "balises/signals/signal";
 import { computed } from "balises/signals/computed";
+import { effect } from "balises/signals/effect";
 import { store } from "balises/signals/store";
-import { batch } from "balises/signals/context";
+import { batch, scope } from "balises/signals/context";
 ```
 
 ## Full Example
@@ -257,6 +354,125 @@ class Counter extends HTMLElement {
 customElements.define("x-counter", Counter);
 ```
 
+**With `signal.update()` for functional updates:**
+
+```ts
+import { html, signal, effect } from "balises";
+
+class Counter extends HTMLElement {
+  #count = signal(0);
+  #dispose?: () => void;
+
+  connectedCallback() {
+    // Auto-sync to localStorage
+    const syncEffect = effect(() => {
+      localStorage.setItem("counter", String(this.#count.value));
+    });
+
+    const { fragment, dispose } = html`
+      <div>
+        <p>Count: ${this.#count}</p>
+        <button @click=${() => this.#count.update((n) => n - 1)}>-</button>
+        <button @click=${() => this.#count.update((n) => n + 1)}>+</button>
+      </div>
+    `.render();
+
+    this.appendChild(fragment);
+    this.#dispose = () => {
+      syncEffect();
+      dispose();
+    };
+  }
+
+  disconnectedCallback() {
+    this.#dispose?.();
+  }
+}
+```
+
+<!-- BENCHMARK_RESULTS_START -->
+
+## Benchmarks
+
+Performance comparison of Balises against other popular reactive libraries. Benchmarks run in isolated processes to prevent V8 JIT contamination.
+
+**Test Environment:**
+
+- Node.js with V8 engine
+- Each test runs in a separate process (isolated mode)
+- **10 warmup runs** to stabilize JIT
+- **100 iterations per test**, keeping middle 20 (discarding 40 best + 40 worst to reduce outliers)
+- Tests measure pure reactive propagation (not DOM rendering)
+
+**Scoring Methodology:**
+
+- Overall ranking uses a combined score (50% average rank + 50% normalized average time)
+- This ensures both consistency across scenarios (rank) and absolute performance (time) are valued equally
+- "vs Fastest" compares average time to the fastest library
+
+### Overall Performance
+
+```
+┌───────┬───────────────────┬──────────┬───────────────┬──────────────────┐
+│ Rank  │ Library           │ Avg Rank │ Avg Time (μs) │ vs Fastest       │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #1 🏆 │ balises@0.2.1     │ 1.5      │ 69.76         │ 1.00x (baseline) │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #2    │ preact@1.12.1     │ 1.7      │ 51.59         │ 0.74x            │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #3    │ vue@3.5.26        │ 3.0      │ 72.79         │ 1.04x            │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #4    │ maverick@6.0.0    │ 3.8      │ 91.40         │ 1.31x            │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #5    │ solid@1.9.10      │ 5.3      │ 225.26        │ 3.23x            │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #6    │ mobx@6.15.0       │ 5.8      │ 719.17        │ 10.31x           │
+├───────┼───────────────────┼──────────┼───────────────┼──────────────────┤
+│ #7    │ hyperactiv@0.11.3 │ 6.8      │ 833.03        │ 11.94x           │
+└───────┴───────────────────┴──────────┴───────────────┴──────────────────┘
+```
+
+### Performance by Scenario
+
+```
+┌───────────────────┬───────────────┬─────────────┬────────────────┬────────────────────┬─────────────┬──────────────┬──────────┐
+│ Library           │ S1: 1: Layers │ S2: 2: Wide │ S3: 3: Diamond │ S4: 4: Conditional │ S5: 5: List │ S6: 6: Batch │ Avg Rank │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ balises@0.2.1     │ #3            │ #1 🏆       │ #1 🏆          │ #2                 │ #1 🏆       │ #1 🏆        │ 1.5      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ preact@1.12.1     │ #1 🏆         │ #2          │ #2             │ #1 🏆              │ #2          │ #2           │ 1.7      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ vue@3.5.26        │ #2            │ #3          │ #3             │ #3                 │ #3          │ #4           │ 3.0      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ maverick@6.0.0    │ #4            │ #4          │ #4             │ #4                 │ #4          │ #3           │ 3.8      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ solid@1.9.10      │ #5            │ #6          │ #5             │ #5                 │ #6          │ #5           │ 5.3      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ mobx@6.15.0       │ #7            │ #5          │ #6             │ #6                 │ #5          │ #6           │ 5.8      │
+├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
+│ hyperactiv@0.11.3 │ #6            │ #7          │ #7             │ #7                 │ #7          │ #7           │ 6.8      │
+└───────────────────┴───────────────┴─────────────┴────────────────┴────────────────────┴─────────────┴──────────────┴──────────┘
+```
+
+**Scenarios:**
+
+- **S1: Layers** - Deep dependency chains (A→B→C→D...)
+- **S2: Wide** - Many independent signals updating in parallel
+- **S3: Diamond** - Multiple paths to same computed (diamond dependencies)
+- **S4: Conditional** - Dynamic subscriptions (like v-if logic)
+- **S5: List** - List operations with filtering (like v-for patterns)
+- **S6: Batch** - Batched/transactional updates
+
+**Interpretation:**
+
+- Balises excels at diamond dependencies, list operations, and batching while maintaining competitive performance across all scenarios
+- Results show pure reactivity performance - real-world apps should consider framework ecosystem, DX, and specific use cases
+- Lower rank = better performance
+
+_Last updated: 2025-12-30_
+
+<!-- BENCHMARK_RESULTS_END -->
+
 ## Scripts
 
 ```bash

package/dist/balises.esm.js

@@ -14,14 +14,14 @@ let batchQueue = null;
 */
 function batch(fn) {
 	batchDepth++;
-	if (batchDepth === 1) batchQueue = [];
+	if (batchDepth === 1) batchQueue = /* @__PURE__ */ new Set();
 	try {
 		return fn();
 	} finally {
 		if (--batchDepth === 0) {
 			const q = batchQueue;
 			batchQueue = null;
-			for (let i = 0; i < q.length; i++) q[i]();
+			for (const sub of q) sub();
 		}
 	}
 }
@@ -31,11 +31,51 @@ function isBatching() {
 }
 /** Add a subscriber to the batch queue */
 function enqueueBatch(sub) {
-	batchQueue.push(sub);
+	batchQueue.add(sub);
 }
 /** Add multiple subscribers to the batch queue */
 function enqueueBatchAll(subs) {
-	batchQueue.push(...subs);
+	for (let i = 0; i < subs.length; i++) batchQueue.add(subs[i]);
+}
+/** Scope disposal: collect all disposers in a scope */
+let disposalStack = null;
+/**
+* Create a disposal scope that collects all subscriptions and computeds created within.
+* Returns the result of the function and a dispose function that cleans up all resources.
+*
+* @example
+* ```ts
+* const [result, dispose] = scope(() => {
+*   const count = signal(0);
+*   const doubled = computed(() => count.value * 2);
+*   effect(() => console.log(doubled.value));
+*   return { count, doubled };
+* });
+*
+* // Later: clean up all subscriptions and computeds
+* dispose();
+* ```
+*/
+function scope(fn) {
+	const disposers = [];
+	if (!disposalStack) disposalStack = [];
+	disposalStack.push(disposers);
+	try {
+		return [fn(), () => {
+			for (let i = disposers.length - 1; i >= 0; i--) disposers[i]();
+			disposers.length = 0;
+		}];
+	} finally {
+		disposalStack.pop();
+		if (disposalStack.length === 0) disposalStack = null;
+	}
+}
+/**
+* Register a disposer in the current scope (if any).
+* This is called internally by computed/effect when they create cleanup functions.
+*/
+function registerDisposer(dispose) {
+	if (disposalStack && disposalStack.length > 0) disposalStack[disposalStack.length - 1].push(dispose);
 }
 
 //#endregion
@@ -53,6 +93,8 @@ function removeFromArray(array, item) {
 /**
 * A reactive value container. When the value changes, all dependent
 * computeds are marked dirty and subscribers are notified.
+*
+* Uses Object.is() for equality checks to correctly handle NaN values.
 */
 var Signal = class {
 	#value;
@@ -66,7 +108,7 @@ var Signal = class {
 		return this.#value;
 	}
 	set value(v) {
-		if (this.#value === v) return;
+		if (Object.is(this.#value, v)) return;
 		this.#value = v;
 		const targets = this.#targets;
 		for (let i = 0; i < targets.length; i++) targets[i].markDirty();
@@ -77,6 +119,18 @@ var Signal = class {
 		this.#subs.push(fn);
 		return () => removeFromArray(this.#subs, fn);
 	}
+	/**
+	* Update the signal value using an updater function.
+	*
+	* @param fn - Function that receives current value and returns new value
+	*
+	* @example
+	* const count = signal(0);
+	* count.update(n => n + 1); // increment
+	*/
+	update(fn) {
+		this.value = fn(this.#value);
+	}
 	/** @internal */
 	get targets() {
 		return this.#targets;
@@ -97,6 +151,8 @@ const signal = (value) => new Signal(value);
 /**
 * A derived reactive value. Automatically tracks dependencies and
 * recomputes when any dependency changes.
+*
+* Uses Object.is() for equality checks to correctly handle NaN values.
 */
 var Computed = class {
 	#fn;
@@ -110,6 +166,7 @@ var Computed = class {
 	constructor(fn) {
 		this.#fn = fn;
 		this.#recompute();
+		registerDisposer(() => this.dispose());
 	}
 	get value() {
 		if (this.#dirty) this.#recompute();
@@ -123,7 +180,10 @@ var Computed = class {
 	dispose() {
 		this.#fn = void 0;
 		const sources = this.#sources;
-		for (let i = 0; i < sources.length; i++) sources[i].deleteTarget(this);
+		for (let i = 0; i < sources.length; i++) {
+			const source = sources[i];
+			if (source) source.deleteTarget(this);
+		}
 		this.#sources = [];
 		this.#subs.length = 0;
 	}
@@ -136,7 +196,10 @@ var Computed = class {
 		const idx = this.#sourceIndex++;
 		if (idx < sources.length) {
 			if (sources[idx] === source) return;
-			for (let i = idx; i < sources.length; i++) sources[i].deleteTarget(this);
+			for (let i = idx; i < sources.length; i++) {
+				const source$1 = sources[i];
+				if (source$1) source$1.deleteTarget(this);
+			}
 			sources.length = idx;
 		}
 		sources.push(source);
@@ -154,20 +217,32 @@ var Computed = class {
 			if (c.#dirty) continue;
 			c.#dirty = true;
 			const targets = c.#targets;
-			for (let j = 0; j < targets.length; j++) {
-				const target = targets[j];
-				if (!target.#dirty) queue.push(target);
-			}
-			if (c.#subs.length) {
+			if (c.#subs.length > 0 && targets.length > 0 && c.#fn && !isBatching()) {
 				const old = c.#value;
-				const notify = () => {
-					if (c.#fn) {
-						c.#recompute();
-						if (c.#value !== old) for (let j = 0; j < c.#subs.length; j++) c.#subs[j]();
+				c.#recompute();
+				if (!Object.is(c.#value, old)) {
+					for (let j = 0; j < targets.length; j++) {
+						const target = targets[j];
+						if (!target.#dirty) queue.push(target);
 					}
-				};
-				if (isBatching()) enqueueBatch(notify);
-				else notify();
+					for (let j = 0; j < c.#subs.length; j++) c.#subs[j]();
+				}
+			} else {
+				for (let j = 0; j < targets.length; j++) {
+					const target = targets[j];
+					if (!target.#dirty) queue.push(target);
+				}
+				if (c.#subs.length) {
+					const old = c.#value;
+					const notify = () => {
+						if (c.#fn) {
+							c.#recompute();
+							if (!Object.is(c.#value, old)) for (let j = 0; j < c.#subs.length; j++) c.#subs[j]();
+						}
+					};
+					if (isBatching()) enqueueBatch(notify);
+					else notify();
+				}
 			}
 		}
 	}
@@ -193,7 +268,10 @@ var Computed = class {
 			const newLen = this.#sourceIndex;
 			if (newLen < prevLen) {
 				const sources = this.#sources;
-				for (let i = newLen; i < prevLen; i++) sources[i].deleteTarget(this);
+				for (let i = newLen; i < prevLen; i++) {
+					const source = sources[i];
+					if (source) source.deleteTarget(this);
+				}
 				sources.length = newLen;
 			}
 			this.#dirty = false;
@@ -204,6 +282,40 @@ var Computed = class {
 /** Create a new computed from the given function. */
 const computed = (fn) => new Computed(fn);
 
+//#endregion
+//#region src/signals/effect.ts
+/**
+* Effect - Run side effects reactively.
+*/
+/**
+* Create a reactive effect that automatically tracks dependencies
+* and re-runs when they change.
+*
+* @param fn - The effect function to run
+* @returns A dispose function to stop the effect
+*
+* @example
+* const count = signal(0);
+* const dispose = effect(() => {
+*   console.log("Count is:", count.value);
+* });
+*
+* count.value = 1; // logs: "Count is: 1"
+* dispose(); // stop the effect
+*/
+function effect(fn) {
+	const c = computed(() => {
+		fn();
+	});
+	const unsub = c.subscribe(() => {});
+	const dispose = () => {
+		unsub();
+		c.dispose();
+	};
+	registerDisposer(dispose);
+	return dispose;
+}
+
 //#endregion
 //#region src/signals/store.ts
 /**
@@ -648,5 +760,5 @@ function each(list, keyFnOrRenderFn, renderFn) {
 }
 
 //#endregion
-export { Computed, Signal, Template, batch, computed, each, html, isSignal, signal, store };
+export { Computed, Signal, Template, batch, computed, each, effect, html, isSignal, scope, signal, store };
 //# sourceMappingURL=balises.esm.js.map