lume-js 2.1.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lume-js",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -28,15 +28,19 @@
     "dev": "vite",
     "dev:site": "node scripts/build-site-assets.js && vite -c vite.site.config.js",
     "build:site": "node scripts/build-site-assets.js && vite build -c vite.site.config.js",
-    "preview:site": "node scripts/build-site-assets.js && vite build -c vite.site.config.js --base / && vite preview -c vite.site.config.js",
+    "preview:site": "node scripts/build-site-assets.js && vite build -c vite.site.config.js --base / && vite preview -c vite.site.config.js --base /",
     "build": "node scripts/build.js",
-    "size": "node scripts/check-size.js",
+    "size": "npm run build && node scripts/check-size.js",
+    "size:ci": "node scripts/check-size.js",
+    "bench": "npm run build && node scripts/bench-core.js",
+    "complexity": "node scripts/complexity.js",
+    "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run size && npm run typecheck && npm test",
-    "prepublishOnly": "npm run build && npm run validate"
+    "validate": "npm run build && node scripts/check-size.js && node scripts/complexity.js && npm run lint && npm run typecheck && npm run coverage",
+    "prepublishOnly": "npm run validate"
   },
   "files": [
     "dist",
@@ -78,6 +82,8 @@
     "@tailwindcss/typography": "^0.5.19",
     "@vitest/coverage-v8": "^2.1.4",
     "autoprefixer": "^10.4.22",
+    "eslint": "^10.3.0",
+    "eslint-plugin-sonarjs": "^4.0.3",
     "highlight.js": "^11.11.1",
     "jsdom": "^25.0.1",
     "marked": "^17.0.1",
@@ -91,4 +97,4 @@
   "engines": {
     "node": ">=20.19.0"
   }
-}
+}

package/src/addons/computed.js

@@ -33,6 +33,11 @@ import { logError } from '../utils/log.js';
  * mutates a state property it depends on, the flush triggered by that
  * mutation is skipped to prevent an infinite microtask loop.
  *
+ * @security After each computation, a re-entry guard stays active until the
+ * next microtask. If a dependency changes synchronously during this window,
+ * the computed will not recompute until a subsequent microtask. This is
+ * intentional — it prevents infinite loops from self-mutating computeds.
+ *
  * @param {function} fn - Function that computes the value
  * @returns {object} Object with .value property and methods
  * 

package/src/addons/hydrateState.js

@@ -2,8 +2,16 @@
  * Reads initial state from a `<script type="application/json">` element
  * embedded in the server-rendered HTML. Useful for SSR / hydration patterns.
  *
+ * @security Hydration trusts the DOM. An attacker who can inject HTML before
+ * the legitimate script (DOM clobbering) can control the parsed data. The
+ * element must be a real `<script type="application/json">` tag; non-script
+ * elements are rejected. Use the optional `validate` parameter to enforce a
+ * schema (e.g., whitelist allowed keys) before passing to `state()`.
+ *
  * @param {string} [selector='#__LUME_DATA__'] - CSS selector for the script element
- * @returns {object} Parsed JSON object, or empty object if not found / invalid
+ * @param {function} [validate] - Optional validator: (data) => boolean. If it
+ *   returns false, hydrateState returns {} instead of the parsed data.
+ * @returns {object} Parsed JSON object, or empty object if not found / invalid / rejected
  *
  * @example
  * ```html
@@ -16,15 +24,35 @@
  * import { state } from 'lume-js';
  * import { hydrateState } from 'lume-js/addons';
  *
- * const store = state(hydrateState());
+ * // With optional schema validation
+ * const data = hydrateState('#__LUME_DATA__', d =>
+ *   typeof d.title === 'string' && typeof d.count === 'number'
+ * );
+ * const store = state(data);
  * ```
  */
-export function hydrateState(selector = '#__LUME_DATA__') {
+export function hydrateState(selector = '#__LUME_DATA__', validate) {
   const el = typeof document !== 'undefined' ? document.querySelector(selector) : null;
   if (!el) return {};
+
+  // Reject non-script elements or scripts without the correct type.
+  // This mitigates DOM clobbering where an attacker injects a matching
+  // element with a different tag name (e.g., a div or a script with
+  // a different type that would still match querySelector by id).
+  if (el.tagName !== 'SCRIPT' || el.type !== 'application/json') {
+    return {};
+  }
+
+  let data;
   try {
-    return JSON.parse(el.textContent);
+    data = JSON.parse(el.textContent);
   } catch {
     return {};
   }
+
+  if (typeof validate === 'function' && !validate(data)) {
+    return {};
+  }
+
+  return data;
 }

package/src/addons/index.d.ts

@@ -56,26 +56,44 @@ export interface Computed<T> {
  */
 export function computed<T>(fn: () => T): Computed<T>;
 
+export interface WatchOptions {
+  /**
+   * Whether to call the callback immediately with the current value (default: true).
+   * Set to false to skip the initial call and only react to future changes.
+   */
+  immediate?: boolean;
+}
+
 /**
  * Watch a single key on a reactive state object; convenience wrapper around $subscribe.
- * 
+ *
+ * By default the callback fires immediately with the current value, then on every change.
+ * Pass `{ immediate: false }` to skip the initial call and only react to future changes.
+ *
  * @param store - Reactive state object created with state().
  * @param key - Property key to observe.
- * @param callback - Invoked immediately and on subsequent changes.
+ * @param callback - Called with new value on change (and immediately unless immediate=false).
+ * @param options - Watch options
  * @returns Unsubscribe function for cleanup
  * @throws {Error} If store is not a reactive state object
- * 
+ *
  * @example
  * ```typescript
  * import { state } from 'lume-js';
  * import { watch } from 'lume-js/addons';
- * 
+ *
  * const store = state({ count: 0 });
- * 
+ *
+ * // Fires immediately with 0, then on every change
  * const unwatch = watch(store, 'count', (value) => {
  *   console.log('Count is now:', value);
  * });
- * 
+ *
+ * // Only fires on future changes (not the initial value)
+ * watch(store, 'count', (value) => {
+ *   console.log('Count changed to:', value);
+ * }, { immediate: false });
+ *
  * // Cleanup
  * unwatch();
  * ```
@@ -83,7 +101,8 @@ export function computed<T>(fn: () => T): Computed<T>;
 export function watch<T extends object, K extends keyof T>(
   store: ReactiveState<T>,
   key: K,
-  callback: Subscriber<T[K]>
+  callback: Subscriber<T[K]>,
+  options?: WatchOptions
 ): Unsubscribe;
 
 /**

package/src/addons/repeat.js

@@ -259,6 +259,7 @@ export function repeat(container, store, arrayKey, options) {
     if (restoreScroll) restoreScroll();
   }
 
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- keyed DOM reconciliation: create/reuse/remove nodes, key dedup, scroll/focus preservation
   function updateList() {
     const items = store[arrayKey];
 
@@ -332,6 +333,7 @@ export function repeat(container, store, arrayKey, options) {
       nextEls.push(el);
     }
 
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- DOM cleanup pass: remove stale nodes, call per-item cleanup callbacks, update maps
     applyPreservation(containerEl, () => {
       reconcileDOM(containerEl, nextEls);
 

package/src/addons/watch.js

@@ -3,11 +3,20 @@
  * @param {Object} store - reactive store created with state()
  * @param {string} key - key in store to watch
  * @param {Function} callback - called with new value
+ * @param {Object} [options]
+ * @param {boolean} [options.immediate=true] - call callback immediately with current value
  * @returns {Function} unsubscribe function
  */
-export function watch(store, key, callback) {
+export function watch(store, key, callback, { immediate = true } = {}) {
   if (!store.$subscribe) {
     throw new Error("store must be created with state()");
   }
+  if (!immediate) {
+    let skipped = false;
+    return store.$subscribe(key, (val) => {
+      if (!skipped) { skipped = true; return; }
+      callback(val);
+    });
+  }
   return store.$subscribe(key, callback);
 }

package/src/addons/withPlugins.js

@@ -24,6 +24,10 @@
  *   onNotify(key, value)             — called before subscribers are notified
  *   onSubscribe(key)                 — called when $subscribe is invoked
  *
+ * @security Plugins run with full application privilege. A plugin can read
+ * all state, alter any write, or suppress mutations. Only pass trusted objects.
+ * Plugin objects are frozen after registration to prevent post-init mutation.
+ *
  * @param {object} store - A reactive proxy from state()
  * @param {Array<object>} plugins - Array of plugin objects
  * @returns {Proxy} A new proxy wrapping the store with plugin behavior
@@ -33,13 +37,15 @@ import { logError } from '../utils/log.js';
 export function withPlugins(store, plugins = []) {
   if (!plugins.length) return store;
 
-  // Call onInit hooks once at wrap time
+  // Call onInit hooks once at wrap time, then freeze each plugin to prevent
+  // post-registration mutation of its hooks (defense-in-depth).
   for (const p of plugins) {
     try {
       p.onInit?.();
     } catch (e) {
       logError(`[Lume.js] Plugin "${p.name}" error in onInit:`, e);
     }
+    Object.freeze(p);
   }
 
   // Track pending notifications for onNotify hooks.

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';

package/src/core/effect.js

@@ -58,6 +58,7 @@ let currentEffect = null;
  *   analytics.log(store.count);  // Won't track store.count automatically
  * }, [[store, 'count']]);        // Explicit: only re-run on store.count
  */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- handles both auto-tracking and explicit-deps modes with cleanup; splitting would require exporting internal state
 export function effect(fn, deps) {
   if (typeof fn !== 'function') {
     throw new Error('effect() requires a function');

package/src/core/state.js

@@ -22,7 +22,7 @@
  *   unsub(); // cleanup
  */
 
-import { logError } from '../utils/log.js';
+import { logError, logWarn } from '../utils/log.js';
 
 // Per-state batching – each state object maintains its own microtask flush.
 // This keeps effects simple and aligned with Lume's minimal philosophy.
@@ -55,6 +55,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
  */
@@ -100,6 +106,7 @@ export function state(obj) {
     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;
@@ -190,6 +197,8 @@ export function state(obj) {
     };
   };
 
+  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)
@@ -210,6 +219,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
@@ -255,12 +269,18 @@ 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);
 
     // Call immediately with current value (NOT batched)

package/src/handlers/ariaAttr.js

@@ -0,0 +1,14 @@
+/**
+ * Create a handler for an ARIA attribute.
+ * Coerces value to "true"/"false" string — use stringAttr("aria-X") for token/string ARIA attrs.
+ *
+ * @param {string} name - ARIA name, with or without "aria-" prefix
+ * @returns {{ attr: string, apply: function }}
+ */
+export function ariaAttr(name) {
+  const fullName = name.startsWith('aria-') ? name : `aria-${name}`;
+  return {
+    attr: `data-${fullName}`,
+    apply(el, val) { el.setAttribute(fullName, val ? 'true' : 'false'); }
+  };
+}

package/src/handlers/boolAttr.js

@@ -0,0 +1,14 @@
+/**
+ * Create a handler for any HTML boolean attribute.
+ * Uses toggleAttribute() — works correctly with any attribute name
+ * (readonly, contenteditable, etc.) without worrying about camelCase property names.
+ *
+ * @param {string} name - Attribute name (e.g., 'readonly', 'open', 'contenteditable')
+ * @returns {{ attr: string, apply: function }}
+ */
+export function boolAttr(name) {
+  return {
+    attr: `data-${name}`,
+    apply(el, val) { el.toggleAttribute(name, Boolean(val)); }
+  };
+}

package/src/handlers/className.js

@@ -0,0 +1,5 @@
+/** data-classname="key" → el.className = val || '' */
+export const className = {
+  attr: 'data-classname',
+  apply(el, val) { el.className = val || ''; }
+};

package/src/handlers/classToggle.js

@@ -0,0 +1,14 @@
+/**
+ * Create handlers for CSS class toggling.
+ * Each name creates a handler: data-class-{name}="key" → el.classList.toggle(name, Boolean(val))
+ * Returns an array — pass directly to handlers (auto-flattened by bindDom).
+ *
+ * @param {...string} names - CSS class names to create handlers for
+ * @returns {Array<{ attr: string, apply: function }>}
+ */
+export function classToggle(...names) {
+  return names.map(name => ({
+    attr: `data-class-${name}`,
+    apply(el, val) { el.classList.toggle(name, Boolean(val)); }
+  }));
+}

package/src/handlers/htmlAttrs.js

@@ -0,0 +1,57 @@
+import { show }       from './show.js';
+import { boolAttr }   from './boolAttr.js';
+import { ariaAttr }   from './ariaAttr.js';
+import { stringAttr } from './stringAttr.js';
+
+/** @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes */
+const BOOL_ATTRS = [
+  'readonly', 'open', 'novalidate', 'formnovalidate', 'multiple',
+  'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'defer',
+  'async', 'reversed', 'selected', 'inert', 'allowfullscreen',
+];
+
+/** @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes */
+const STRING_ATTRS = [
+  'href', 'src', 'alt', 'title', 'placeholder', 'action', 'method',
+  'target', 'rel', 'type', 'name', 'role', 'lang', 'tabindex',
+  'pattern', 'min', 'max', 'step', 'minlength', 'maxlength',
+  'width', 'height', 'for', 'form', 'accept', 'autocomplete',
+  'loading', 'decoding', 'inputmode', 'enterkeyhint', 'draggable',
+  'contenteditable', 'spellcheck', 'translate', 'dir', 'id',
+  'poster', 'preload', 'download', 'media', 'sizes', 'srcset',
+  'colspan', 'rowspan', 'scope', 'headers', 'wrap', 'sandbox',
+];
+
+/** ARIA boolean state attributes — coerced to "true"/"false" string. */
+const ARIA_BOOL_ATTRS = [
+  'pressed', 'selected', 'disabled', 'checked', 'invalid', 'required',
+  'busy', 'modal', 'multiselectable', 'multiline', 'readonly', 'atomic',
+];
+
+/** ARIA string/token/numeric attributes — value passed through as-is. */
+const ARIA_STRING_ATTRS = [
+  'current', 'live', 'relevant', 'haspopup',
+  'sort', 'autocomplete', 'orientation',
+  'label', 'describedby', 'labelledby', 'controls', 'owns',
+  'activedescendant', 'errormessage', 'details', 'flowto',
+  'valuenow', 'valuemin', 'valuemax', 'valuetext',
+  'colcount', 'colindex', 'colspan', 'rowcount', 'rowindex', 'rowspan',
+  'level', 'setsize', 'posinset', 'placeholder', 'roledescription',
+  'keyshortcuts', 'braillelabel', 'brailleroledescription',
+];
+
+/**
+ * One-import preset that enables all standard HTML attributes as reactive handlers.
+ * Returns a flat array — pass directly to handlers option.
+ *
+ * @returns {Array<{ attr: string, apply: function }>}
+ */
+export function htmlAttrs() {
+  return [
+    show,
+    ...BOOL_ATTRS.map(name => boolAttr(name)),
+    ...STRING_ATTRS.map(name => stringAttr(name)),
+    ...ARIA_BOOL_ATTRS.map(name => ariaAttr(name)),
+    ...ARIA_STRING_ATTRS.map(name => stringAttr(`aria-${name}`)),
+  ];
+}

package/src/handlers/index.d.ts

@@ -14,6 +14,19 @@ import type { Handler } from '../index.js';
  */
 export const show: Handler;
 
+/**
+ * data-classname="key" → el.className = val (replaces full class string)
+ * Use classToggle() for toggling individual classes.
+ *
+ * @example
+ * ```typescript
+ * bindDom(root, store, { handlers: [className] });
+ * // <div data-classname="cardClass">...</div>
+ * // store.cardClass = 'card card--error card--large';
+ * ```
+ */
+export const className: Handler;
+
 /**
  * Create a handler for any HTML boolean property.
  * Use for properties beyond the built-in hidden/disabled/checked/required.