lume-js 2.2.1 → 2.3.1

package/src/state.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Lume.js Universal State Entry — TypeScript Definitions
+ *
+ * Source of truth for the DOM-free kernel: state(), batch(),
+ * withReadObserver() and their types. This file must type-check WITHOUT
+ * lib.dom — it is what `lume-js/state` consumers in Node, Deno, and
+ * workers resolve (the full `lume-js` entry re-exports everything here
+ * and adds the DOM-flavored API on top).
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+  /**
+   * 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;
+
+  /**
+   * 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>;
+
+/**
+ * Group multiple state writes and flush them together, synchronously,
+ * when the outermost batch() returns.
+ *
+ * Guarantees:
+ * - Subscribers see only the final value of each key written in the batch.
+ * - An effect depending on several stores mutated in the batch runs exactly
+ *   ONCE (normal microtask batching is per-state: such effects run once per
+ *   mutated store).
+ * - Nested batch() calls are absorbed into the outermost batch.
+ * - If fn throws, writes made before the throw still flush, then the error
+ *   propagates.
+ *
+ * fn must be synchronous. Writes after an `await` fall back to normal
+ * per-state microtask flushing (a console warning is logged if fn returns
+ * a Promise).
+ *
+ * @param fn - Function performing state writes
+ * @returns The return value of fn
+ * @throws {Error} If fn is not a function
+ *
+ * @example
+ * ```typescript
+ * 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<T>(fn: () => T): T;
+
+/**
+ * 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;

package/src/state.js

@@ -0,0 +1,25 @@
+/**
+ * Lume-JS Universal State Entry
+ *
+ * The DOM-free kernel: reactive state + cross-store batching. Runs anywhere
+ * JavaScript runs — Node, Deno, Bun, workers, CLI tools, browsers.
+ *
+ * Use this entry when you don't need DOM binding:
+ *
+ *   import { state, batch } from "lume-js/state";
+ *
+ *   const store = state({ count: 0 });
+ *   store.$subscribe("count", v => console.log("count:", v));
+ *
+ *   batch(() => {
+ *     store.count = 1;
+ *     store.count = 2;
+ *   }); // subscribers see only 2, synchronously
+ *
+ * For DOM binding and effects, use the full core instead:
+ *
+ *   import { state, bindDom, effect, batch } from "lume-js";
+ */
+
+export { state, withReadObserver } from "./core/state.js";
+export { batch } from "./core/batch.js";

package/dist/shared-x2HJmEyO.mjs

@@ -1,260 +0,0 @@
-function logWarn(msg, ...rest) {
-  if (typeof console !== "undefined" && typeof console.warn === "function") {
-    console.warn(msg, ...rest);
-  }
-}
-function logError(msg, ...rest) {
-  if (typeof console !== "undefined" && typeof console.error === "function") {
-    console.error(msg, ...rest);
-  }
-}
-const readers = /* @__PURE__ */ new Set();
-function withReadObserver(onRead, fn) {
-  readers.add(onRead);
-  try {
-    return fn();
-  } finally {
-    readers.delete(onRead);
-  }
-}
-function state(obj) {
-  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
-    throw new Error("state() requires a plain object");
-  }
-  if (Object.isFrozen(obj) || Object.isSealed(obj)) {
-    throw new Error("state() requires a mutable plain object");
-  }
-  const listeners = /* @__PURE__ */ Object.create(null);
-  const pendingNotifications = /* @__PURE__ */ new Map();
-  const pendingEffects = /* @__PURE__ */ new Set();
-  const beforeFlushHooks = [];
-  let flushScheduled = false;
-  function scheduleFlush() {
-    if (flushScheduled) return;
-    flushScheduled = true;
-    queueMicrotask(() => {
-      let iterations = 0;
-      const MAX_ITERATIONS = 100;
-      try {
-        while ((pendingNotifications.size > 0 || pendingEffects.size > 0) && iterations < MAX_ITERATIONS) {
-          iterations++;
-          for (let i = 0; i < beforeFlushHooks.length; i++) {
-            try {
-              beforeFlushHooks[i]();
-            } catch (err) {
-              logError("[Lume.js state] Error in beforeFlush hook:", err);
-            }
-          }
-          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);
-                }
-                if (subs[i] === fn) i++;
-              }
-            }
-          }
-          pendingNotifications.clear();
-          const effects = new Array(pendingEffects.size);
-          let idx = 0;
-          for (const effect2 of pendingEffects) {
-            effects[idx++] = effect2;
-          }
-          pendingEffects.clear();
-          for (let i = 0; i < effects.length; i++) {
-            try {
-              effects[i]();
-            } catch (err) {
-              logError("[Lume.js state] Error in effect:", err);
-            }
-          }
-        }
-      } finally {
-        flushScheduled = false;
-      }
-      if (iterations >= MAX_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."
-        );
-      }
-    });
-  }
-  const REACTIVE_BRAND = Symbol("lume.reactive");
-  obj[REACTIVE_BRAND] = true;
-  const registerEffect = (key, executeFn) => {
-    if (!listeners[key]) listeners[key] = [];
-    const callback = () => {
-      pendingEffects.add(executeFn);
-    };
-    listeners[key].push(callback);
-    return () => {
-      if (listeners[key]) {
-        const idx = listeners[key].indexOf(callback);
-        if (idx !== -1) {
-          listeners[key].splice(idx, 1);
-          if (listeners[key].length === 0) delete listeners[key];
-        }
-      }
-    };
-  };
-  const BLOCKED_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-  const proxy = new Proxy(obj, {
-    get(target, key) {
-      if (typeof key === "string" && key.startsWith("$")) {
-        return target[key];
-      }
-      const value = target[key];
-      if (readers.size > 0) {
-        for (const reader of readers) {
-          reader(proxy, key, registerEffect);
-        }
-      }
-      return value;
-    },
-    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];
-      if (Object.is(oldValue, value)) return true;
-      target[key] = value;
-      pendingNotifications.set(key, value);
-      scheduleFlush();
-      return true;
-    }
-  });
-  obj.$beforeFlush = (fn) => {
-    if (typeof fn !== "function") {
-      throw new Error("$beforeFlush requires a function");
-    }
-    if (beforeFlushHooks.indexOf(fn) === -1) {
-      beforeFlushHooks.push(fn);
-    }
-    return () => {
-      const idx = beforeFlushHooks.indexOf(fn);
-      if (idx !== -1) {
-        beforeFlushHooks.splice(idx, 1);
-      }
-    };
-  };
-  const MAX_SUBSCRIBERS = 1e3;
-  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);
-    fn(proxy[key]);
-    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 proxy;
-}
-let currentEffect = null;
-function effect(fn, deps) {
-  if (typeof fn !== "function") {
-    throw new Error("effect() requires a function");
-  }
-  const cleanups = [];
-  let isRunning = false;
-  const execute = () => {
-    if (isRunning) return;
-    isRunning = true;
-    try {
-      fn();
-    } catch (error) {
-      logError("[Lume.js effect] Error in effect:", error);
-      throw error;
-    } finally {
-      isRunning = false;
-    }
-  };
-  if (Array.isArray(deps)) {
-    for (const dep of deps) {
-      if (Array.isArray(dep) && dep.length >= 2) {
-        const [store, ...keys] = dep;
-        if (store && typeof store.$subscribe === "function") {
-          for (const key of keys) {
-            let isFirst = true;
-            const unsub = store.$subscribe(key, () => {
-              if (isFirst) {
-                isFirst = false;
-                return;
-              }
-              execute();
-            });
-            cleanups.push(unsub);
-          }
-        }
-      }
-    }
-    execute();
-  } else {
-    const executeWithTracking = () => {
-      if (isRunning) return;
-      const oldCleanups = cleanups.splice(0);
-      const myContext = {
-        fn,
-        cleanups,
-        execute: executeWithTracking,
-        tracking: {}
-      };
-      const previousEffect = currentEffect;
-      currentEffect = myContext;
-      isRunning = true;
-      try {
-        const onRead = (proxy, key, registerEffect) => {
-          if (currentEffect !== myContext) return;
-          if (myContext.tracking[key]) return;
-          myContext.tracking[key] = true;
-          myContext.cleanups.push(registerEffect(key, myContext.execute));
-        };
-        withReadObserver(onRead, fn);
-      } catch (error) {
-        cleanups.length = 0;
-        cleanups.push(...oldCleanups);
-        logError("[Lume.js effect] Error in effect:", error);
-        throw error;
-      } finally {
-        currentEffect = previousEffect;
-        isRunning = false;
-      }
-      if (cleanups.length > 0) {
-        for (const cleanup of oldCleanups) cleanup();
-      } else {
-        cleanups.push(...oldCleanups);
-      }
-    };
-    executeWithTracking();
-  }
-  return () => {
-    while (cleanups.length) cleanups.pop()();
-  };
-}
-export {
-  logError as a,
-  effect as e,
-  logWarn as l,
-  state as s,
-  withReadObserver as w
-};
-//# sourceMappingURL=shared-x2HJmEyO.mjs.map

package/dist/shared-x2HJmEyO.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"shared-x2HJmEyO.mjs","sources":["../src/utils/log.js","../src/core/state.js","../src/core/effect.js"],"sourcesContent":["/**\n * Environment-safe logging utilities for constrained runtimes\n * (e.g. service workers, embedded engines, SSR environments).\n *\n * All core and addon files should import these instead of\n * calling console.* directly to avoid ReferenceError when\n * console is not defined.\n */\n\nexport function logWarn(msg, ...rest) {\n  if (typeof console !== 'undefined' && typeof console.warn === 'function') {\n    console.warn(msg, ...rest);\n  }\n}\n\nexport function logError(msg, ...rest) {\n  if (typeof console !== 'undefined' && typeof console.error === 'function') {\n    console.error(msg, ...rest);\n  }\n}\n","/**\n * Lume-JS Reactive State Core\n *\n * Provides minimal reactive state with standard JavaScript.\n * Features automatic microtask batching for performance.\n * Read tracking is opt-in via withReadObserver — state.js has zero permanent\n * dependency on effect.js or any other module.\n *\n * Features:\n * - Lightweight and Go-style\n * - Explicit nested states\n * - $subscribe for listening to key changes\n * - Cleanup with unsubscribe\n * - Per-state microtask batching for writes\n * - Scope-based read tracking via withReadObserver (multi-observer safe)\n *\n * Usage:\n *   import { state } from \"lume-js\";\n *\n *   const store = state({ count: 0 });\n *   const unsub = store.$subscribe(\"count\", val => console.log(val));\n *   unsub(); // cleanup\n */\n\nimport { logError, logWarn } from '../utils/log.js';\n\n// Per-state batching – each state object maintains its own microtask flush.\n// This keeps effects simple and aligned with Lume's minimal philosophy.\n\n/**\n * Creates a reactive state object.\n *\n * @param {Object} obj - Initial state object (must be plain object)\n * @returns {Proxy} Reactive proxy with $subscribe method\n *\n * @example\n * const store = state({ count: 0 });\n */\n\n// Active read observers — only populated during withReadObserver scopes.\n// This keeps state.js pure: tracking only happens when someone explicitly\n// asks to observe reads within a synchronous function call.\n//\n// Note: This Set is module-level, so all reactive state instances and effects\n// within the SAME module instance share it. This is standard behavior for\n// auto-tracking reactive libraries (Vue, MobX, Solid, etc.). Multiple copies\n// of the lume-js module (e.g. from different bundled chunks) each get their\n// own independent Set via ES module / CommonJS isolation.\nconst readers = new Set();\n\n/**\n * Run a function with a read observer active.\n * The observer receives (proxy, key, registerEffect) for every property read.\n * Multiple observers can be active simultaneously (nested effects, devtools, etc.)\n *\n * Internal API — used by effect.js for auto-tracking. May be stabilized\n * for third-party addons in a future release.\n *\n * @security The observer sees reads from ALL state instances within the same\n * module instance, including nested scopes. Only pass trusted observer functions.\n * A future scoped variant (e.g., scopedReadObserver(store, fn)) may limit\n * observation to a single state instance.\n *\n * @param {function} onRead - Called on each property access inside fn\n * @param {function} fn - The function to run under observation\n */\nexport function withReadObserver(onRead, fn) {\n  readers.add(onRead);\n  try {\n    return fn();\n  } finally {\n    readers.delete(onRead);\n  }\n}\n\nexport function state(obj) {\n  // Validate input\n  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {\n    throw new Error('state() requires a plain object');\n  }\n  if (Object.isFrozen(obj) || Object.isSealed(obj)) {\n    throw new Error('state() requires a mutable plain object');\n  }\n\n  // Object.create(null) - no prototype chain lookups\n  const listeners = Object.create(null);\n  const pendingNotifications = new Map(); // Per-state pending changes\n  const pendingEffects = new Set(); // Dedupe effects per state\n  const beforeFlushHooks = [];\n  let flushScheduled = false;\n\n  /**\n   * Schedule a single microtask flush for this state object.\n   *\n   * Flush order per state:\n   * 1) Notify subscribers for changed keys (key → subscribers)\n   * 2) Run each queued effect exactly once (Set-based dedupe)\n   * 3) Repeat up to 100 iterations to handle cascading updates,\n   *    then log an error to prevent infinite loops.\n   *\n   * Notes:\n   * - Batching is per state; effects that depend on multiple states\n   *   may run once per state that changed (by design).\n   */\n  function scheduleFlush() {\n    if (flushScheduled) return;\n\n    flushScheduled = true;\n    // eslint-disable-next-line sonarjs/cognitive-complexity -- single-pass flush loop: hooks → subscribers → effects → cycle detection; must stay atomic\n    queueMicrotask(() => {\n      let iterations = 0;\n      const MAX_ITERATIONS = 100;\n\n      try {\n        while ((pendingNotifications.size > 0 || pendingEffects.size > 0) && iterations < MAX_ITERATIONS) {\n          iterations++;\n\n          // Run registered before-flush hooks (e.g. plugin onNotify)\n          for (let i = 0; i < beforeFlushHooks.length; i++) {\n            try {\n              beforeFlushHooks[i]();\n            } catch (err) {\n              logError('[Lume.js state] Error in beforeFlush hook:', err);\n            }\n          }\n\n          // Notify all subscribers of changed keys\n          for (const [key, value] of pendingNotifications) {\n            if (listeners[key]) {\n              const subs = listeners[key];\n              let i = 0;\n              while (i < subs.length) {\n                const fn = subs[i];\n                try {\n                  fn(value);\n                } catch (err) {\n                  logError(`[Lume.js state] Error notifying subscriber for key \"${String(key)}\":`, err);\n                }\n                // Only advance if fn wasn't removed (something shifted into its place)\n                if (subs[i] === fn) i++;\n              }\n            }\n          }\n\n          pendingNotifications.clear();\n\n          // Run each effect exactly once (Set deduplicates)\n          const effects = new Array(pendingEffects.size);\n          let idx = 0;\n          for (const effect of pendingEffects) {\n            effects[idx++] = effect;\n          }\n          pendingEffects.clear();\n          for (let i = 0; i < effects.length; i++) {\n            try {\n              effects[i]();\n            } catch (err) {\n              logError('[Lume.js state] Error in effect:', err);\n            }\n          }\n        }\n      } finally {\n        flushScheduled = false;\n      }\n\n      if (iterations >= MAX_ITERATIONS) {\n        logError(\n          '[Lume.js state] Maximum flush iterations reached (100). ' +\n          'This usually indicates an infinite loop caused by an effect or computed mutating state it depends on.'\n        );\n      }\n    });\n  }\n\n  // Brand symbol for type-level reactive identification\n  const REACTIVE_BRAND = Symbol('lume.reactive');\n  obj[REACTIVE_BRAND] = true;\n\n  // Defined once per state instance — not per property read — to avoid per-read closure allocation.\n  const registerEffect = (key, executeFn) => {\n    if (!listeners[key]) listeners[key] = [];\n\n    const callback = () => {\n      pendingEffects.add(executeFn);\n    };\n\n    listeners[key].push(callback);\n\n    return () => {\n      if (listeners[key]) {\n        const idx = listeners[key].indexOf(callback);\n        if (idx !== -1) {\n          listeners[key].splice(idx, 1);\n          if (listeners[key].length === 0) delete listeners[key];\n        }\n      }\n    };\n  };\n\n  const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);\n\n  const proxy = new Proxy(obj, {\n    get(target, key) {\n      // Skip effect tracking for internal meta methods (e.g. $subscribe)\n      if (typeof key === 'string' && key.startsWith('$')) {\n        return target[key];\n      }\n\n      const value = target[key];\n\n      // Notify active read observers (effects, devtools, etc.)\n      if (readers.size > 0) {\n        for (const reader of readers) {\n          reader(proxy, key, registerEffect);\n        }\n      }\n\n      return value;\n    },\n\n    set(target, key, value) {\n      if (typeof key === 'string' && BLOCKED_KEYS.has(key)) {\n        logWarn(`[Lume.js state] Blocked write to reserved key \"${key}\"`);\n        return true;\n      }\n\n      const oldValue = target[key];\n\n      // Skip update if value unchanged - Object.is() handles NaN and -0 correctly\n      if (Object.is(oldValue, value)) return true;\n\n      target[key] = value;\n\n      // Batch notifications at the state level (per-state, not global)\n      pendingNotifications.set(key, value);\n      scheduleFlush();\n\n      return true;\n    }\n  });\n\n  /**\n   * Subscribe to changes for a specific key.\n   * Calls the callback immediately with the current value.\n   * Returns an unsubscribe function for cleanup.\n   *\n   * @param {string} key - Property key to watch\n   * @param {function} fn - Callback function\n   * @returns {function} Unsubscribe function\n   */\n  // Set on obj (not proxy) to avoid triggering the set trap.\n  // The get trap already returns target[key] directly for $-prefixed keys.\n  /**\n   * Register a callback to run before each flush.\n   * Returns an unsubscribe function.\n   */\n  obj.$beforeFlush = (fn) => {\n    if (typeof fn !== 'function') {\n      throw new Error('$beforeFlush requires a function');\n    }\n    if (beforeFlushHooks.indexOf(fn) === -1) {\n      beforeFlushHooks.push(fn);\n    }\n    return () => {\n      const idx = beforeFlushHooks.indexOf(fn);\n      if (idx !== -1) {\n        beforeFlushHooks.splice(idx, 1);\n      }\n    };\n  };\n\n  const MAX_SUBSCRIBERS = 1000;\n\n  obj.$subscribe = (key, fn) => {\n    if (typeof fn !== 'function') {\n      throw new Error('Subscriber must be a function');\n    }\n\n    if (!listeners[key]) listeners[key] = [];\n    if (listeners[key].length >= MAX_SUBSCRIBERS) {\n      logWarn(`[Lume.js state] Subscriber limit (${MAX_SUBSCRIBERS}) reached for key \"${key}\". New subscriber ignored.`);\n      return () => {};\n    }\n    listeners[key].push(fn);\n\n    // Call immediately with current value (NOT batched)\n    fn(proxy[key]);\n\n    // Return unsubscribe function\n    return () => {\n      if (listeners[key]) {\n        const idx = listeners[key].indexOf(fn);\n        if (idx !== -1) {\n          listeners[key].splice(idx, 1);\n          if (listeners[key].length === 0) delete listeners[key];\n        }\n      }\n    };\n  };\n\n  return proxy;\n}\n","import { withReadObserver } from './state.js';\nimport { logError } from '../utils/log.js';\n\n/**\n * Lume-JS Effect\n *\n * Reactive effects with two modes:\n * 1. Auto-tracking (default): Tracks dependencies automatically via withReadObserver\n * 2. Explicit deps: You specify exactly what triggers re-runs\n *\n * Auto-tracking uses scope-based read observation — state.js has zero permanent\n * dependency on this module. Read tracking is only active during the synchronous\n * execution of an effect's body.\n *\n * Usage:\n *   import { effect } from \"lume-js\";\n *\n *   // Auto-tracking mode (existing behavior)\n *   effect(() => {\n *     console.log('Count is:', store.count);\n *     // Automatically re-runs when store.count changes\n *   });\n *\n *   // Explicit deps mode (new - no magic)\n *   effect(() => {\n *     console.log('Count is:', store.count);\n *   }, [[store, 'count']]);  // Only re-runs when store.count changes\n *\n * Features:\n * - Automatic dependency collection via withReadObserver scope (default)\n * - Explicit dependencies for side-effects\n * - Returns cleanup function\n * - Compatible with per-state batching\n */\n\n// Module-scoped effect context (prevents third-party spoofing via globalThis)\nlet currentEffect = null;\n\n// withReadObserver is used below to scope read tracking to synchronous effect execution.\n\n/**\n * Creates an effect that runs reactively\n *\n * @param {function} fn - Function to run reactively\n * @param {Array<[object, string]>} [deps] - Optional explicit dependencies as [store, key] tuples\n * @returns {function} Cleanup function to stop the effect\n *\n * @example\n * // Auto-tracking (default)\n * const store = state({ count: 0 });\n * effect(() => {\n *   document.title = `Count: ${store.count}`;\n * });\n * \n * @example\n * // Explicit deps (no magic)\n * effect(() => {\n *   analytics.log(store.count);  // Won't track store.count automatically\n * }, [[store, 'count']]);        // Explicit: only re-run on store.count\n */\n// eslint-disable-next-line sonarjs/cognitive-complexity -- handles both auto-tracking and explicit-deps modes with cleanup; splitting would require exporting internal state\nexport function effect(fn, deps) {\n  if (typeof fn !== 'function') {\n    throw new Error('effect() requires a function');\n  }\n\n  const cleanups = [];\n  let isRunning = false;\n\n  /**\n   * Execute the effect function\n   */\n  const execute = () => {\n    /* v8 ignore next -- re-entry guard: unreachable because $subscribe fires via microtask after isRunning resets in finally */\n    if (isRunning) return;\n    isRunning = true;\n\n    try {\n      fn();\n    } catch (error) {\n      logError('[Lume.js effect] Error in effect:', error);\n      throw error;\n    } finally {\n      isRunning = false;\n    }\n  };\n\n  // EXPLICIT DEPS MODE: deps array provided\n  if (Array.isArray(deps)) {\n    // Subscribe to each [store, key1, key2, ...] tuple explicitly\n    for (const dep of deps) {\n      if (Array.isArray(dep) && dep.length >= 2) {\n        const [store, ...keys] = dep;\n        if (store && typeof store.$subscribe === 'function') {\n          // Subscribe to each key in this tuple\n          for (const key of keys) {\n            // $subscribe calls immediately, then on changes\n            // We want: call execute immediately once, then on changes\n            let isFirst = true;\n            const unsub = store.$subscribe(key, () => {\n              if (isFirst) {\n                isFirst = false;\n                return; // Skip first call, we'll run execute() below\n              }\n              execute();\n            });\n            cleanups.push(unsub);\n          }\n        }\n      }\n    }\n    // Run immediately\n    execute();\n  }\n  // AUTO-TRACKING MODE: no deps (existing behavior)\n  else {\n    const executeWithTracking = () => {\n      /* v8 ignore next -- defensive guard: synchronous re-entry is unreachable through the public API */\n      if (isRunning) return;\n\n      // Save previous subscriptions instead of cleaning immediately.\n      // If fn() doesn't read any state (early return / error), we restore\n      // them so the effect stays reactive.\n      const oldCleanups = cleanups.splice(0);\n\n      // Create effect context for tracking\n      const myContext = {\n        fn,\n        cleanups,\n        execute: executeWithTracking,\n        tracking: {}\n      };\n\n      // Set as current effect (for state.js to detect)\n      // Save previous context to support nested effects/computed\n      const previousEffect = currentEffect;\n      currentEffect = myContext;\n      isRunning = true;\n\n      try {\n        const onRead = (proxy, key, registerEffect) => {\n          // Only the currently active effect (not a nested one) creates subscriptions\n          if (currentEffect !== myContext) return;\n          if (myContext.tracking[key]) return;\n          myContext.tracking[key] = true;\n          myContext.cleanups.push(registerEffect(key, myContext.execute));\n        };\n        withReadObserver(onRead, fn);\n      } catch (error) {\n        // On error, restore old subscriptions so the effect stays reactive\n        cleanups.length = 0;\n        cleanups.push(...oldCleanups);\n        logError('[Lume.js effect] Error in effect:', error);\n        throw error;\n      } finally {\n        // Restore previous context (not undefined) to support nesting\n        currentEffect = previousEffect;\n        isRunning = false;\n      }\n\n      // If fn() created new subscriptions, clean old ones.\n      // If it didn't (e.g., early return), keep old subscriptions intact.\n      if (cleanups.length > 0) {\n        for (const cleanup of oldCleanups) cleanup();\n      } else {\n        cleanups.push(...oldCleanups);\n      }\n    };\n\n    // Run immediately to collect initial dependencies\n    executeWithTracking();\n  }\n\n  // Return cleanup function\n  return () => {\n    // while/pop is faster than forEach\n    while (cleanups.length) cleanups.pop()();\n  };\n}"],"names":["effect"],"mappings":"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"}