lume-js 2.2.0 → 2.3.0

package/src/core/batch.js

@@ -0,0 +1,139 @@
+/**
+ * Lume-JS Cross-Store Batching
+ *
+ * While batchDepth > 0, states skip their microtask flush and enqueue a
+ * small flush handle here instead (via enqueueIfBatching, called from
+ * state.js's scheduler); batch() drains the set synchronously when the
+ * outermost batch ends. Effects collected from all enqueued states run
+ * from one Set per wave, so an effect depending on several mutated stores
+ * runs exactly once per batch instead of once per store.
+ *
+ * This module never imports state.js — state.js imports from here — so
+ * there is no cycle, no global scheduler object, and no import side effect.
+ */
+
+import { logError, logWarn } from '../utils/log.js';
+
+// Cap for cascading flush waves (effects mutating state that re-triggers
+// effects). Shared with the per-state microtask flush in state.js.
+export const MAX_FLUSH_ITERATIONS = 100;
+
+let batchDepth = 0;
+const batchedStates = new Set();
+
+/**
+ * Called by state.js when a write is scheduled. Returns true if a batch is
+ * active and the state's flush handle was captured (the caller must then
+ * skip its own microtask scheduling).
+ *
+ * Internal API between core modules — not exported from the package root.
+ *
+ * @param {{runBeforeFlushHooks: function, notifySubscribers: function, takeEffects: function}} handle
+ * @returns {boolean}
+ */
+export function enqueueIfBatching(handle) {
+  if (batchDepth === 0) return false;
+  batchedStates.add(handle);
+  return true;
+}
+
+function flushBatchedStates() {
+  let iterations = 0;
+  while (batchedStates.size > 0 && iterations < MAX_FLUSH_ITERATIONS) {
+    iterations++;
+    const wave = Array.from(batchedStates);
+    batchedStates.clear();
+
+    // Notify each state's subscribers, collecting effects into one
+    // deduplicated set (the same effect queued by N stores runs once).
+    const effects = new Set();
+    for (const s of wave) {
+      s.runBeforeFlushHooks();
+      s.notifySubscribers();
+      for (const fx of s.takeEffects()) effects.add(fx);
+    }
+
+    // Effects run after all subscribers of the wave. Writes they make
+    // re-enter batchedStates (depth is still held) → next iteration.
+    for (const fx of effects) {
+      try { fx(); }
+      catch (err) { logError('[Lume.js state] Error in effect:', err); }
+    }
+  }
+  if (iterations >= MAX_FLUSH_ITERATIONS) {
+    // Drop the runaway wave so a future, unrelated batch doesn't inherit
+    // it. Nothing is lost permanently: the states keep their queued work
+    // and flush it on their next write via the normal microtask path.
+    batchedStates.clear();
+    logError(
+      '[Lume.js state] Maximum batch flush iterations reached (100). ' +
+      'This usually indicates an infinite loop caused by an effect or computed mutating state it depends on.'
+    );
+  }
+}
+
+/**
+ * Group multiple state writes and flush them together, synchronously,
+ * when the outermost batch() returns.
+ *
+ * Guarantees:
+ * - Subscribers see only the final value of each key (intermediate writes
+ *   within the batch are coalesced, as with microtask batching).
+ * - An effect that depends on several stores mutated in the batch runs
+ *   exactly ONCE — unlike microtask batching, which is per-state and runs
+ *   such effects once per store.
+ * - Nested batch() calls are absorbed: everything flushes when the
+ *   outermost batch ends.
+ * - If fn throws, writes made before the throw still flush, then the
+ *   error propagates. State scheduling is left clean either way.
+ *
+ * `fn` must be synchronous — writes after an `await` happen outside the
+ * batch and fall back to normal per-state microtask flushing (a console
+ * warning is logged if fn returns a Promise).
+ *
+ * @param {function} fn - Function performing state writes
+ * @returns {*} The return value of fn
+ *
+ * @example
+ * import { state, effect, batch } from 'lume-js';
+ *
+ * const a = state({ value: 1 });
+ * const b = state({ value: 2 });
+ * effect(() => render(a.value + b.value));
+ *
+ * batch(() => {
+ *   a.value = 10;
+ *   b.value = 20;
+ * }); // render() ran exactly once, seeing 30
+ */
+export function batch(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('batch() requires a function');
+  }
+
+  // Nested batch: let the outermost batch flush everything
+  if (batchDepth > 0) return fn();
+
+  batchDepth++;
+  let result;
+  try {
+    result = fn();
+    if (result && typeof result.then === 'function') {
+      logWarn(
+        '[Lume.js batch] batch() received an async function. Only writes before the first await are batched; ' +
+        'later writes flush via normal microtasks.'
+      );
+    }
+    return result;
+  } finally {
+    // Flush while depth is still held so cascading writes from
+    // subscribers/effects keep collecting into batchedStates (deduped),
+    // then release. Runs on success AND when fn throws (writes made
+    // before the throw are committed, then the error propagates).
+    try {
+      flushBatchedStates();
+    } finally {
+      batchDepth--;
+    }
+  }
+}

package/src/core/bindDom.js

@@ -24,6 +24,11 @@
  * Usage:
  *   import { bindDom } from "lume-js";
  *   const cleanup = bindDom(document.body, store);
+ *
+ * @security `data-bind` attribute values are resolved once at bind time and
+ * trusted as state path expressions. If an attacker can inject `data-bind`
+ * attributes into the DOM, they can subscribe to any reachable reactive state.
+ * Ensure your HTML is trusted or sanitize it before calling bindDom().
  */
 
 import { logWarn } from '../utils/log.js';
@@ -141,7 +146,7 @@ function handleDataBind(el, store, path, bindingMap) {
   if (!result) return null;
 
   const { target, key } = result;
-  const unsub = target.$subscribe(key, val => updateElement(el, val));
+  const unsub = target.$subscribe(key, val => applyBindValue(el, val));
 
   if (isFormInput(el)) {
     bindingMap.set(el, { target, key });
@@ -200,9 +205,13 @@ function resolveProp(store, path) {
 }
 
 /**
- * Update element with value (for data-bind)
+ * Update element with value (for data-bind).
+ *
+ * Exported for internal reuse (e.g. the repeat addon's template bindings)
+ * so addon and core data-bind semantics never drift. Not part of the
+ * public package API.
  */
-function updateElement(el, val) {
+export function applyBindValue(el, val) {
   if (el.tagName === "INPUT") {
     if (el.type === "checkbox") el.checked = Boolean(val);
     else if (el.type === "radio") el.checked = el.value === String(val);

package/src/core/effect.js

@@ -29,6 +29,8 @@ import { logError } from '../utils/log.js';
  * Features:
  * - Automatic dependency collection via withReadObserver scope (default)
  * - Explicit dependencies for side-effects
+ * - Explicit-deps notifications are coalesced: one run per microtask,
+ *   no matter how many tracked keys (or stores) changed in the same tick
  * - Returns cleanup function
  * - Compatible with per-state batching
  */
@@ -87,6 +89,27 @@ export function effect(fn, deps) {
 
   // EXPLICIT DEPS MODE: deps array provided
   if (Array.isArray(deps)) {
+    // Coalesce notifications: when several tracked keys change in the same
+    // flush (or several stores flush in the same tick), run the effect once
+    // per microtask instead of once per changed key. This matches the
+    // dedupe guarantee auto-tracking mode gets from the per-state effect queue.
+    let scheduled = false;
+    let disposed = false;
+    cleanups.push(() => { disposed = true; });
+
+    const scheduleExecute = () => {
+      if (scheduled) return;
+      scheduled = true;
+      queueMicrotask(() => {
+        scheduled = false;
+        if (disposed) return;
+        // execute() logs and re-throws; swallow here so a throwing effect
+        // doesn't become an uncaught error inside the microtask (same
+        // containment the state flush loop provides for subscribers).
+        try { execute(); } catch { /* already logged by execute() */ }
+      });
+    };
+
     // Subscribe to each [store, key1, key2, ...] tuple explicitly
     for (const dep of deps) {
       if (Array.isArray(dep) && dep.length >= 2) {
@@ -102,7 +125,7 @@ export function effect(fn, deps) {
                 isFirst = false;
                 return; // Skip first call, we'll run execute() below
               }
-              execute();
+              scheduleExecute();
             });
             cleanups.push(unsub);
           }
@@ -123,12 +146,13 @@ export function effect(fn, deps) {
       // them so the effect stays reactive.
       const oldCleanups = cleanups.splice(0);
 
-      // Create effect context for tracking
+      // Tracking is keyed per store proxy (WeakMap<proxy, Set<key>>) so the
+      // same key name on two different stores creates two subscriptions.
       const myContext = {
         fn,
         cleanups,
         execute: executeWithTracking,
-        tracking: {}
+        tracking: new WeakMap()
       };
 
       // Set as current effect (for state.js to detect)
@@ -141,8 +165,13 @@ export function effect(fn, deps) {
         const onRead = (proxy, key, registerEffect) => {
           // Only the currently active effect (not a nested one) creates subscriptions
           if (currentEffect !== myContext) return;
-          if (myContext.tracking[key]) return;
-          myContext.tracking[key] = true;
+          let keys = myContext.tracking.get(proxy);
+          if (!keys) {
+            keys = new Set();
+            myContext.tracking.set(proxy, keys);
+          }
+          if (keys.has(key)) return;
+          keys.add(key);
           myContext.cleanups.push(registerEffect(key, myContext.execute));
         };
         withReadObserver(onRead, fn);

package/src/core/state.js

@@ -12,6 +12,7 @@
  * - $subscribe for listening to key changes
  * - Cleanup with unsubscribe
  * - Per-state microtask batching for writes
+ * - batch() for grouping writes across states with cross-store effect dedupe
  * - Scope-based read tracking via withReadObserver (multi-observer safe)
  *
  * Usage:
@@ -22,7 +23,8 @@
  *   unsub(); // cleanup
  */
 
-import { logError } from '../utils/log.js';
+import { logError, logWarn } from '../utils/log.js';
+import { enqueueIfBatching, MAX_FLUSH_ITERATIONS } from './batch.js';
 
 // Per-state batching – each state object maintains its own microtask flush.
 // This keeps effects simple and aligned with Lume's minimal philosophy.
@@ -48,6 +50,22 @@ import { logError } from '../utils/log.js';
 // own independent Set via ES module / CommonJS isolation.
 const readers = new Set();
 
+/**
+ * Brand symbol stamped on every object passed to state().
+ *
+ * Uses the global symbol registry (Symbol.for) so independent copies of
+ * lume-js on the same page (e.g. a CDN build next to a bundled chunk)
+ * agree on the same brand. This is a type tag for reliable detection
+ * (see isReactive in addons), not a security boundary — any code can
+ * stamp it.
+ *
+ * Internal API — exported for addons; not re-exported from the package root.
+ */
+export const REACTIVE_BRAND = Symbol.for('lume.reactive');
+
+// batch() lives in ./batch.js (which never imports this module — no cycle).
+// state.js participates through enqueueIfBatching in scheduleFlush below.
+
 /**
  * Run a function with a read observer active.
  * The observer receives (proxy, key, registerEffect) for every property read.
@@ -55,6 +73,12 @@ const readers = new Set();
  *
  * Internal API — used by effect.js for auto-tracking. May be stabilized
  * for third-party addons in a future release.
+ *
+ * @security The observer sees reads from ALL state instances within the same
+ * module instance, including nested scopes. Only pass trusted observer functions.
+ * A future scoped variant (e.g., scopedReadObserver(store, fn)) may limit
+ * observation to a single state instance.
+ *
  * @param {function} onRead - Called on each property access inside fn
  * @param {function} fn - The function to run under observation
  */
@@ -83,6 +107,49 @@ export function state(obj) {
   const beforeFlushHooks = [];
   let flushScheduled = false;
 
+  // ── Flush steps ──────────────────────────────────────────────────────
+  // Named pieces shared by the per-state microtask flush and batch().
+
+  function runBeforeFlushHooks() {
+    for (let i = 0; i < beforeFlushHooks.length; i++) {
+      try {
+        beforeFlushHooks[i]();
+      } catch (err) {
+        logError('[Lume.js state] Error in beforeFlush hook:', err);
+      }
+    }
+  }
+
+  function notifySubscribers() {
+    for (const [key, value] of pendingNotifications) {
+      if (listeners[key]) {
+        const subs = listeners[key];
+        let i = 0;
+        while (i < subs.length) {
+          const fn = subs[i];
+          try {
+            fn(value);
+          } catch (err) {
+            logError(`[Lume.js state] Error notifying subscriber for key "${String(key)}":`, err);
+          }
+          // Only advance if fn wasn't removed (something shifted into its place)
+          if (subs[i] === fn) i++;
+        }
+      }
+    }
+    pendingNotifications.clear();
+  }
+
+  /** Drain queued effects (Set deduplicates) into an array. */
+  function takeEffects() {
+    const effects = Array.from(pendingEffects);
+    pendingEffects.clear();
+    return effects;
+  }
+
+  // Handle this state gives batch() — flush steps only, no live queues.
+  const batchHandle = { runBeforeFlushHooks, notifySubscribers, takeEffects };
+
   /**
    * Schedule a single microtask flush for this state object.
    *
@@ -94,57 +161,28 @@ export function state(obj) {
    *
    * Notes:
    * - Batching is per state; effects that depend on multiple states
-   *   may run once per state that changed (by design).
+   *   may run once per state that changed (by design). Use batch() to
+   *   group writes across states and run such effects once.
+   * - Inside batch(), the microtask is skipped: the state enqueues
+   *   itself for the synchronous flush at the end of the batch.
    */
   function scheduleFlush() {
+    // Inside batch(): the batch captures this state's flush handle and
+    // flushes synchronously at the end — skip the microtask.
+    if (enqueueIfBatching(batchHandle)) return;
+
     if (flushScheduled) return;
 
     flushScheduled = true;
-    // eslint-disable-next-line sonarjs/cognitive-complexity -- single-pass flush loop: hooks → subscribers → effects → cycle detection; must stay atomic
     queueMicrotask(() => {
       let iterations = 0;
-      const MAX_ITERATIONS = 100;
 
       try {
-        while ((pendingNotifications.size > 0 || pendingEffects.size > 0) && iterations < MAX_ITERATIONS) {
+        while ((pendingNotifications.size > 0 || pendingEffects.size > 0) && iterations < MAX_FLUSH_ITERATIONS) {
           iterations++;
-
-          // Run registered before-flush hooks (e.g. plugin onNotify)
-          for (let i = 0; i < beforeFlushHooks.length; i++) {
-            try {
-              beforeFlushHooks[i]();
-            } catch (err) {
-              logError('[Lume.js state] Error in beforeFlush hook:', err);
-            }
-          }
-
-          // Notify all subscribers of changed keys
-          for (const [key, value] of pendingNotifications) {
-            if (listeners[key]) {
-              const subs = listeners[key];
-              let i = 0;
-              while (i < subs.length) {
-                const fn = subs[i];
-                try {
-                  fn(value);
-                } catch (err) {
-                  logError(`[Lume.js state] Error notifying subscriber for key "${String(key)}":`, err);
-                }
-                // Only advance if fn wasn't removed (something shifted into its place)
-                if (subs[i] === fn) i++;
-              }
-            }
-          }
-
-          pendingNotifications.clear();
-
-          // Run each effect exactly once (Set deduplicates)
-          const effects = new Array(pendingEffects.size);
-          let idx = 0;
-          for (const effect of pendingEffects) {
-            effects[idx++] = effect;
-          }
-          pendingEffects.clear();
+          runBeforeFlushHooks();
+          notifySubscribers();
+          const effects = takeEffects();
           for (let i = 0; i < effects.length; i++) {
             try {
               effects[i]();
@@ -157,7 +195,7 @@ export function state(obj) {
         flushScheduled = false;
       }
 
-      if (iterations >= MAX_ITERATIONS) {
+      if (iterations >= MAX_FLUSH_ITERATIONS) {
         logError(
           '[Lume.js state] Maximum flush iterations reached (100). ' +
           'This usually indicates an infinite loop caused by an effect or computed mutating state it depends on.'
@@ -166,31 +204,51 @@ export function state(obj) {
     });
   }
 
-  // Brand symbol for type-level reactive identification
-  const REACTIVE_BRAND = Symbol('lume.reactive');
-  obj[REACTIVE_BRAND] = true;
+  // Stamp the shared brand (non-enumerable: spreads/Object.assign copies
+  // of a store do not inherit the brand and won't masquerade as reactive).
+  Object.defineProperty(obj, REACTIVE_BRAND, { value: true });
 
-  // Defined once per state instance — not per property read — to avoid per-read closure allocation.
-  const registerEffect = (key, executeFn) => {
-    if (!listeners[key]) listeners[key] = [];
-
-    const callback = () => {
-      pendingEffects.add(executeFn);
-    };
-
-    listeners[key].push(callback);
+  const MAX_SUBSCRIBERS = 1000;
+  const noopUnsubscribe = () => {};
 
+  /**
+   * Shared listener registration with a per-key cap (subscriber DoS
+   * protection). Applied identically to $subscribe callbacks and effect
+   * subscriptions so both paths degrade the same way: a loud console
+   * error and a no-op unsubscribe.
+   */
+  function addListener(key, fn, kind) {
+    if (!listeners[key]) listeners[key] = [];
+    if (listeners[key].length >= MAX_SUBSCRIBERS) {
+      logError(
+        `[Lume.js state] Subscriber limit (${MAX_SUBSCRIBERS}) reached for key "${String(key)}". ` +
+        `${kind} ignored — it will NOT receive updates. ` +
+        'This usually means subscriptions are created in a loop without cleanup.'
+      );
+      return noopUnsubscribe;
+    }
+    listeners[key].push(fn);
     return () => {
       if (listeners[key]) {
-        const idx = listeners[key].indexOf(callback);
+        const idx = listeners[key].indexOf(fn);
         if (idx !== -1) {
           listeners[key].splice(idx, 1);
           if (listeners[key].length === 0) delete listeners[key];
         }
       }
     };
+  }
+
+  // Defined once per state instance — not per property read — to avoid per-read closure allocation.
+  const registerEffect = (key, executeFn) => {
+    const callback = () => {
+      pendingEffects.add(executeFn);
+    };
+    return addListener(key, callback, 'Effect subscription');
   };
 
+  const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
   const proxy = new Proxy(obj, {
     get(target, key) {
       // Skip effect tracking for internal meta methods (e.g. $subscribe)
@@ -211,6 +269,11 @@ export function state(obj) {
     },
 
     set(target, key, value) {
+      if (typeof key === 'string' && BLOCKED_KEYS.has(key)) {
+        logWarn(`[Lume.js state] Blocked write to reserved key "${key}"`);
+        return true;
+      }
+
       const oldValue = target[key];
 
       // Skip update if value unchanged - Object.is() handles NaN and -0 correctly
@@ -261,22 +324,15 @@ export function state(obj) {
       throw new Error('Subscriber must be a function');
     }
 
-    if (!listeners[key]) listeners[key] = [];
-    listeners[key].push(fn);
+    const unsubscribe = addListener(key, fn, 'New subscriber');
+
+    // Over the cap: listener was not added, skip the immediate call too
+    if (unsubscribe === noopUnsubscribe) return unsubscribe;
 
     // Call immediately with current value (NOT batched)
     fn(proxy[key]);
 
-    // Return unsubscribe function
-    return () => {
-      if (listeners[key]) {
-        const idx = listeners[key].indexOf(fn);
-        if (idx !== -1) {
-          listeners[key].splice(idx, 1);
-          if (listeners[key].length === 0) delete listeners[key];
-        }
-      }
-    };
+    return unsubscribe;
   };
 
   return proxy;

package/src/handlers/index.d.ts

@@ -85,6 +85,30 @@ export function classToggle(...names: string[]): Handler[];
  */
 export function stringAttr(name: string): Handler;
 
+/**
+ * Create handlers for declarative event wiring.
+ * Each type creates a handler: data-on{type}="key" wires the function held
+ * at that store key as a DOM event listener.
+ *
+ * Reactive like any binding: assigning a new function to the key re-wires
+ * the listener; assigning null/undefined detaches it. Non-function truthy
+ * values detach with a console warning.
+ *
+ * Returns an array — pass directly to handlers (auto-flattened by bindDom).
+ *
+ * @param types - DOM event types ('click', 'input', 'submit', ...)
+ *
+ * @example
+ * ```typescript
+ * const store = state({
+ *   addTodo: (event: Event) => { ... }
+ * });
+ * bindDom(root, store, { handlers: [on('click')] });
+ * // <button data-onclick="addTodo">Add</button>
+ * ```
+ */
+export function on(...types: string[]): Handler[];
+
 /** Form-related handlers preset (readonly) */
 export const formHandlers: Handler[];
 

package/src/handlers/index.js

@@ -25,5 +25,6 @@ export { boolAttr }                from './boolAttr.js';
 export { ariaAttr }                from './ariaAttr.js';
 export { classToggle }             from './classToggle.js';
 export { stringAttr }              from './stringAttr.js';
+export { on }                      from './on.js';
 export { htmlAttrs }               from './htmlAttrs.js';
 export { formHandlers, a11yHandlers } from './presets.js';

package/src/handlers/on.js

@@ -0,0 +1,60 @@
+/**
+ * Create handlers for declarative event wiring.
+ * Each type creates a handler: data-on{type}="key" wires the function held
+ * at that store key as a DOM event listener.
+ *
+ *   <button data-onclick="addTodo">Add</button>
+ *
+ *   const store = state({
+ *     addTodo: (event) => { ... }   // a plain function in state
+ *   });
+ *   bindDom(root, store, { handlers: [on('click')] });
+ *
+ * Reactive like any binding: assigning a new function to the key re-wires
+ * the listener; assigning null/undefined detaches it.
+ *
+ * Returns an array — pass directly to handlers (auto-flattened by bindDom).
+ *
+ * @security Same trust model as data-bind: an injected data-on* attribute
+ * can only reference functions that already exist in reachable state — no
+ * expressions, no eval. Ensure your HTML is trusted or sanitized.
+ *
+ * Note: bindDom's cleanup stops future re-wiring but does not detach
+ * listeners already attached to elements that remain in the DOM. Discard
+ * the bound subtree (the normal SPA teardown) to drop them.
+ *
+ * @param {...string} types - DOM event types ('click', 'input', 'submit', ...)
+ * @returns {Array<{ attr: string, apply: function }>}
+ */
+
+import { logWarn } from '../utils/log.js';
+
+// element → Map<eventType, listener> — tracks what we attached so a
+// re-assigned store key swaps the listener instead of stacking a second one.
+const attached = new WeakMap();
+
+export function on(...types) {
+  return types.map(type => ({
+    attr: `data-on${type}`,
+    apply(el, val) {
+      let byType = attached.get(el);
+      const prev = byType ? byType.get(type) : undefined;
+
+      if (prev) {
+        el.removeEventListener(type, prev);
+        byType.delete(type);
+      }
+
+      if (typeof val === 'function') {
+        el.addEventListener(type, val);
+        if (!byType) {
+          byType = new Map();
+          attached.set(el, byType);
+        }
+        byType.set(type, val);
+      } else if (val != null) {
+        logWarn(`[Lume.js] on('${type}'): bound value is not a function — listener detached`);
+      }
+    }
+  }));
+}

package/src/handlers/stringAttr.js

@@ -5,12 +5,24 @@
  * @param {string} name - HTML attribute name (e.g., 'href', 'src', 'title')
  * @returns {{ attr: string, apply: function }}
  */
+
+const DANGEROUS_SCHEME = /^(javascript|vbscript|data\s*:\s*text\/html)/i;
+const URI_ATTRS = new Set(['href', 'src', 'action', 'srcset', 'poster', 'formaction']);
+
 export function stringAttr(name) {
   return {
     attr: `data-${name}`,
     apply(el, val) {
-      if (val == null) el.removeAttribute(name);
-      else el.setAttribute(name, String(val));
+      if (val == null) {
+        el.removeAttribute(name);
+        return;
+      }
+      const strVal = String(val);
+      if (URI_ATTRS.has(name) && DANGEROUS_SCHEME.test(strVal)) {
+        el.removeAttribute(name);
+        return;
+      }
+      el.setAttribute(name, strVal);
     }
   };
 }