lume-js 2.2.1 → 2.3.1

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:
@@ -23,6 +24,7 @@
  */
 
 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, logWarn } 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.
@@ -89,6 +107,57 @@ 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() {
+    // Drain BEFORE delivering. Iterating the live Map is wrong twice over:
+    // a subscriber writing back to an already-delivered key would update
+    // the in-flight entry (never revisited) and the trailing clear() would
+    // destroy it — a silently lost update; and a subscriber opening a
+    // batch() would re-deliver every in-flight entry through the wave's
+    // re-entrant call. Draining first means write-backs land in the now-
+    // empty live Map and are delivered by the next flush iteration/wave.
+    const entries = Array.from(pendingNotifications);
+    pendingNotifications.clear();
+    for (const [key, value] of entries) {
+      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++;
+        }
+      }
+    }
+  }
+
+  /** 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.
    *
@@ -100,57 +169,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]();
@@ -163,7 +203,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.'
@@ -172,29 +212,47 @@ 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']);
@@ -269,33 +327,20 @@ export function state(obj) {
     };
   };
 
-  const MAX_SUBSCRIBERS = 1000;
-
   obj.$subscribe = (key, fn) => {
     if (typeof fn !== 'function') {
       throw new Error('Subscriber must be a function');
     }
 
-    if (!listeners[key]) listeners[key] = [];
-    if (listeners[key].length >= MAX_SUBSCRIBERS) {
-      logWarn(`[Lume.js state] Subscriber limit (${MAX_SUBSCRIBERS}) reached for key "${key}". New subscriber ignored.`);
-      return () => {};
-    }
-    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

@@ -6,7 +6,13 @@
  * @returns {{ attr: string, apply: function }}
  */
 
-const DANGEROUS_SCHEME = /^(javascript|vbscript|data\s*:\s*text\/html)/i;
+// Matched against a normalized copy of the value (C0 controls, space, and
+// DEL stripped; lowercased) because the browser URL parser ignores those
+// characters when determining the scheme — "java\tscript:alert(1)" and
+// " javascript:alert(1)" both execute. The colon is required so legitimate
+// relative URLs like "javascript-tutorial.html" are not blocked.
+const DANGEROUS_SCHEME = /^(?:javascript:|vbscript:|data:text\/html)/;
+const IGNORED_URL_CHARS = /[\u0000-\u0020\u007F]/g;
 const URI_ATTRS = new Set(['href', 'src', 'action', 'srcset', 'poster', 'formaction']);
 
 export function stringAttr(name) {
@@ -18,7 +24,8 @@ export function stringAttr(name) {
         return;
       }
       const strVal = String(val);
-      if (URI_ATTRS.has(name) && DANGEROUS_SCHEME.test(strVal)) {
+      if (URI_ATTRS.has(name) &&
+          DANGEROUS_SCHEME.test(strVal.replace(IGNORED_URL_CHARS, '').toLowerCase())) {
         el.removeAttribute(name);
         return;
       }

package/src/index.d.ts

@@ -4,186 +4,23 @@
  * Provides type safety for reactive state management
  */
 
-/**
- * Unsubscribe function returned by $subscribe
- */
-export type Unsubscribe = () => void;
-
-/**
- * Subscriber callback function
- */
-export type Subscriber<T> = (value: T) => void;
-
-/**
- * Internal unique symbol for reactive state branding
- * @internal
- */
-declare const lumeReactiveSymbol: unique symbol;
-
-/**
- * Plugin interface for extending state behavior
- * 
- * All hooks are optional. Hooks execute in the order plugins are registered.
- * 
- * @example
- * ```typescript
- * const debugPlugin: Plugin = {
- *   name: 'debug',
- *   onGet: (key, value) => {
- *     console.log(`GET ${key}:`, value);
- *     return value; // Return value to pass to next plugin
- *   },
- *   onSet: (key, newValue, oldValue) => {
- *     console.log(`SET ${key}:`, oldValue, '→', newValue);
- *     return newValue; // Return value to pass to next plugin
- *   }
- * };
- * 
- * const store = withPlugins(state({ count: 0 }), [debugPlugin]);
- * ```
- */
-export interface Plugin {
-  /**
-   * Plugin name (for debugging)
-   */
-  name: string;
-
-  /**
-   * Called when state object is created
-   * Runs synchronously before Proxy is returned
-   */
-  onInit?(): void;
-
-  /**
-   * Called when a property is accessed (before value returned)
-   * Can transform the value by returning a new value
-   * 
-   * Chain pattern: Each plugin receives the output of the previous plugin
-   * 
-   * @param key - Property key being accessed
-   * @param value - Current value (possibly transformed by previous plugins)
-   * @returns Transformed value, or undefined to keep current value
-   */
-  onGet?(key: string, value: any): any;
-
-  /**
-   * Called when a property is updated (before subscribers notified)
-   * Can transform or validate the new value
-   * 
-   * Chain pattern: Each plugin receives the output of the previous plugin
-   * 
-   * @param key - Property key being updated
-   * @param newValue - New value being set (possibly transformed by previous plugins)
-   * @param oldValue - Previous value
-   * @returns Transformed value, or undefined to keep current value
-   */
-  onSet?(key: string, newValue: any, oldValue: any): any;
-
-  /**
-   * Called when a subscriber is added
-   * Useful for tracking active subscriptions
-   * 
-   * @param key - Property key being subscribed to
-   */
-  onSubscribe?(key: string): void;
-
-  /**
-   * Called when subscribers are about to be notified
-   * Runs in microtask, before subscribers receive value
-   * 
-   * @param key - Property key that changed
-   * @param value - New value being notified
-   */
-  onNotify?(key: string, value: any): void;
-}
-
-/**
- * Type-safe plugin interface for when you know the state shape.
- * Provides better intellisense for key names and value types.
- * 
- * @example
- * ```typescript
- * interface AppState {
- *   count: number;
- *   name: string;
- * }
- * 
- * const myPlugin: TypedPlugin<AppState> = {
- *   name: 'typed',
- *   onSet: (key, newValue, oldValue) => {
- *     // key is 'count' | 'name', values are properly typed
- *     return newValue;
- *   }
- * };
- * ```
- */
-export interface TypedPlugin<T extends object> {
-  name: string;
-  onInit?(): void;
-  onGet?<K extends keyof T>(key: K, value: T[K]): T[K] | undefined;
-  onSet?<K extends keyof T>(key: K, newValue: T[K], oldValue: T[K]): T[K] | undefined;
-  onSubscribe?<K extends keyof T>(key: K): void;
-  onNotify?<K extends keyof T>(key: K, value: T[K]): void;
-}
+// ── Kernel types & functions ─────────────────────────────────────────────
+// The DOM-free kernel (state, batch, withReadObserver and their types)
+// lives in ./state.d.ts — the source of truth for the `lume-js/state`
+// entry, which must type-check without lib.dom (Node/worker consumers).
+// This entry re-exports the kernel and adds the DOM-flavored API.
 
-/**
- * Reactive state object with $subscribe method
- */
-export type ReactiveState<T extends object> = T & {
-  /**
-   * Subscribe to changes on a specific property key
-   * @param key - Property key to watch
-   * @param callback - Function called when property changes
-   * @returns Unsubscribe function for cleanup
-   */
-  $subscribe<K extends keyof T>(
-    key: K,
-    callback: Subscriber<T[K]>
-  ): Unsubscribe;
+export type {
+  Unsubscribe,
+  Subscriber,
+  Plugin,
+  TypedPlugin,
+  ReactiveState,
+} from './state.js';
 
-  /**
-   * Register a callback to run before each flush.
-   * Dedupes duplicate function references.
-   * @param fn - Callback function
-   * @returns Unsubscribe function for cleanup
-   */
-  $beforeFlush(fn: () => void): Unsubscribe;
+export { state, batch, withReadObserver } from './state.js';
 
-  /**
-   * Brand to identify reactive state objects at the type level
-   * @internal
-   */
-  readonly [lumeReactiveSymbol]?: true;
-};
-
-/**
- * Create a reactive state object
- * 
- * @param obj - Plain object to make reactive
- * @returns Reactive proxy with $subscribe method
- * @throws {Error} If obj is not a plain object
- * 
- * @example
- * ```typescript
- * const store = state({
- *   count: 0,
- *   user: state({
- *     name: 'Alice'
- *   })
- * });
- * 
- * store.count++; // Triggers reactivity
- * 
- * const unsub = store.$subscribe('count', (val) => {
- *   console.log('Count:', val);
- * });
- * 
- * // Cleanup
- * unsub();
- * ```
- * 
- */
-export function state<T extends object>(obj: T): ReactiveState<T>;
+import type { ReactiveState, Unsubscribe } from './state.js';
 
 /**
  * Handler interface for extending bindDom with custom reactive data-* attributes.
@@ -353,29 +190,6 @@ export function effect(fn: () => void): Unsubscribe;
  */
 export function effect(fn: () => void, deps: EffectDependency[]): Unsubscribe;
 
-/**
- * Run a function with a read observer active.
- *
- * The observer receives `(proxy, key, registerEffect)` for every property read
- * during the synchronous execution of `fn`. Used internally by `effect()` for
- * auto-tracking, and exposed for building custom reactive primitives.
- *
- * @param onRead - Called on each property access inside fn
- * @param fn - The function to run under observation
- * @returns The return value of fn
- *
- * @internal
- */
-export function withReadObserver<T>(
-  onRead: (
-    proxy: ReactiveState<any>,
-    key: string,
-    registerEffect: (key: string, executeFn: () => void) => () => void
-  ) => void,
-  fn: () => T
-): T;
-
-
 // ============================================================================
 // Utility Types
 // ============================================================================

package/src/index.js

@@ -5,12 +5,14 @@
  * - state(): create reactive state
  * - bindDom(): zero-runtime DOM binding
  * - effect(): reactive effect with automatic dependency tracking
+ * - batch(): group writes across states, flush once synchronously
  * - withReadObserver(): advanced API for custom reactive primitives
  *
  * Usage:
- *   import { state, bindDom, effect } from "lume-js";
+ *   import { state, bindDom, effect, batch } from "lume-js";
  */
 
 export { state, withReadObserver } from "./core/state.js";
+export { batch } from "./core/batch.js";
 export { bindDom } from "./core/bindDom.js";
 export { effect } from "./core/effect.js";