lume-js 0.3.0 → 0.4.1

package/src/addons/computed.js

@@ -1,53 +1,136 @@
 /**
- * computed - creates a derived value based on state
+ * Lume-JS Computed Addon
  * 
- * NOTE: This is a basic implementation. For production use,
- * consider more robust solutions with automatic dependency tracking.
+ * Creates computed values that automatically update when dependencies change.
+ * Uses core effect() for automatic dependency tracking.
  * 
- * @param {Function} fn - function that computes value from state
- * @returns {Object} - { value, recompute, subscribe }
+ * Usage:
+ *   import { computed } from "lume-js/addons/computed";
+ *   
+ *   const doubled = computed(() => store.count * 2);
+ *   console.log(doubled.value); // Auto-updates when store.count changes
+ * 
+ * Features:
+ * - Automatic dependency tracking (no manual recompute)
+ * - Cached values (only recomputes when dependencies change)
+ * - Subscribe to changes
+ * - Cleanup with dispose()
+ * 
+ * @module addons/computed
+ */
+
+import { effect } from '../core/effect.js';
+
+/**
+ * Creates a computed value with automatic dependency tracking
+ * 
+ * The computation function runs immediately and tracks which state
+ * properties are accessed. When any dependency changes, the value
+ * is automatically recomputed.
+ * 
+ * @param {function} fn - Function that computes the value
+ * @returns {object} Object with .value property and methods
  * 
  * @example
- * const store = state({ count: 0 });
+ * const store = state({ count: 5 });
+ * 
  * const doubled = computed(() => store.count * 2);
+ * console.log(doubled.value); // 10
+ * 
+ * store.count = 10;
+ * // After microtask:
+ * console.log(doubled.value); // 20 (auto-updated)
  * 
+ * @example
  * // Subscribe to changes
- * doubled.subscribe(val => console.log('Doubled:', val));
+ * const unsub = doubled.subscribe(value => {
+ *   console.log('Doubled changed to:', value);
+ * });
  * 
- * // Manually trigger recomputation after state changes
- * store.$subscribe('count', () => doubled.recompute());
+ * @example
+ * // Cleanup
+ * doubled.dispose();
  */
 export function computed(fn) {
-  let value;
-  let dirty = true;
-  const subscribers = new Set();
+  if (typeof fn !== 'function') {
+    throw new Error('computed() requires a function');
+  }
 
-  const recalc = () => {
+  let cachedValue;
+  let isInitialized = false;
+  const subscribers = [];
+  
+  // Use effect to automatically track dependencies
+  const cleanupEffect = effect(() => {
     try {
-      value = fn();
-    } catch (err) {
-      console.error("[computed] Error computing value:", err);
-      value = undefined;
+      const newValue = fn();
+      
+      // Check if value actually changed
+      if (!isInitialized || newValue !== cachedValue) {
+        cachedValue = newValue;
+        isInitialized = true;
+        
+        // Notify all subscribers
+        subscribers.forEach(callback => callback(cachedValue));
+      }
+    } catch (error) {
+      console.error('[Lume.js computed] Error in computation:', error);
+      // Set to undefined on error, mark as initialized
+      if (!isInitialized || cachedValue !== undefined) {
+        cachedValue = undefined;
+        isInitialized = true;
+        
+        // Notify subscribers of error state
+        subscribers.forEach(callback => callback(cachedValue));
+      }
     }
-    dirty = false;
-    subscribers.forEach(cb => cb(value));
-  };
-
+  });
+  
   return {
+    /**
+     * Get the current computed value
+     */
     get value() {
-      if (dirty) recalc();
-      return value;
+      if (!isInitialized) {
+        throw new Error('Computed value accessed before initialization');
+      }
+      return cachedValue;
     },
-    recompute: () => {
-      dirty = true;
-      recalc();
-    },
-    subscribe: cb => {
-      subscribers.add(cb);
-      // Immediately notify subscriber with current value
-      if (!dirty) cb(value);
-      else recalc(); // Compute first time
-      return () => subscribers.delete(cb); // unsubscribe function
+    
+    /**
+     * Subscribe to changes in computed value
+     * 
+     * @param {function} callback - Called when value changes
+     * @returns {function} Unsubscribe function
+     */
+    subscribe(callback) {
+      if (typeof callback !== 'function') {
+        throw new Error('subscribe() requires a function');
+      }
+      
+      subscribers.push(callback);
+      
+      // Call immediately with current value
+      if (isInitialized) {
+        callback(cachedValue);
+      }
+      
+      // Return unsubscribe function
+      return () => {
+        const index = subscribers.indexOf(callback);
+        if (index > -1) {
+          subscribers.splice(index, 1);
+        }
+      };
     },
+    
+    /**
+     * Clean up computed value and stop tracking
+     */
+    dispose() {
+      cleanupEffect();
+      subscribers.length = 0;
+      isInitialized = false;
+    }
   };
 }

package/src/addons/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Lume.js Addons TypeScript Definitions
+ * 
+ * Optional utilities for advanced reactive patterns.
+ * Import from "lume-js/addons" for tree-shaking.
+ */
+
+import type { Unsubscribe, Subscriber, ReactiveState } from '../index.js';
+
+/**
+ * Computed value container returned by computed().
+ * T is the computed result type; when an error occurs the value becomes undefined.
+ */
+export interface Computed<T> {
+  /** Current computed value (undefined if computation threw). */
+  readonly value: T | undefined;
+  /** Subscribe to changes; immediate invocation with current value (may be undefined). */
+  subscribe(callback: Subscriber<T | undefined>): Unsubscribe;
+  /** Dispose computed value and stop tracking dependencies. */
+  dispose(): void;
+}
+
+/**
+ * Create a computed value that automatically re-evaluates when accessed reactive state keys change.
+ * Uses effect() internally for dependency tracking.
+ * 
+ * @param fn - Pure function that derives a value from reactive state.
+ * @returns Computed value container with .value, .subscribe(), and .dispose()
+ * @throws {Error} If fn is not a function
+ * 
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { computed } from 'lume-js/addons';
+ * 
+ * const store = state({ count: 5 });
+ * const doubled = computed(() => store.count * 2);
+ * 
+ * console.log(doubled.value); // 10
+ * 
+ * store.count = 10;
+ * // After microtask:
+ * console.log(doubled.value); // 20 (auto-updated)
+ * 
+ * // Subscribe to changes
+ * const unsub = doubled.subscribe(value => {
+ *   console.log('Doubled:', value);
+ * });
+ * 
+ * // Cleanup
+ * doubled.dispose();
+ * unsub();
+ * ```
+ */
+export function computed<T>(fn: () => T): Computed<T>;
+
+/**
+ * Watch a single key on a reactive state object; convenience wrapper around $subscribe.
+ * 
+ * @param store - Reactive state object created with state().
+ * @param key - Property key to observe.
+ * @param callback - Invoked immediately and on subsequent changes.
+ * @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 });
+ * 
+ * const unwatch = watch(store, 'count', (value) => {
+ *   console.log('Count is now:', value);
+ * });
+ * 
+ * // Cleanup
+ * unwatch();
+ * ```
+ */
+export function watch<T extends object, K extends keyof T>(
+  store: ReactiveState<T>,
+  key: K,
+  callback: Subscriber<T[K]>
+): Unsubscribe;

package/src/core/bindDom.js

@@ -4,10 +4,19 @@
  *
  * Binds reactive state to DOM elements using [data-bind].
  * Supports two-way binding for INPUT/TEXTAREA/SELECT.
+ * 
+ * Automatically waits for DOMContentLoaded if the document is still loading,
+ * ensuring safe binding regardless of when the function is called.
  *
  * Usage:
  *   import { bindDom } from "lume-js";
+ *   
+ *   // Default: Auto-waits for DOM (safe anywhere)
  *   const cleanup = bindDom(document.body, store);
+ *   
+ *   // Advanced: Force immediate binding (no auto-wait)
+ *   const cleanup = bindDom(myElement, store, { immediate: true });
+ *   
  *   // Later: cleanup();
  *
  * HTML:
@@ -23,9 +32,11 @@ import { resolvePath } from "./utils.js";
  * 
  * @param {HTMLElement} root - Root element to scan for [data-bind]
  * @param {object} store - Reactive state object
+ * @param {object} [options] - Optional configuration
+ * @param {boolean} [options.immediate=false] - Skip auto-wait, bind immediately
  * @returns {function} Cleanup function to remove all bindings
  */
-export function bindDom(root, store) {
+export function bindDom(root, store, options = {}) {
   if (!(root instanceof HTMLElement)) {
     throw new Error('bindDom() requires a valid HTMLElement as root');
   }
@@ -34,52 +45,79 @@ export function bindDom(root, store) {
     throw new Error('bindDom() requires a reactive state object');
   }
 
-  const nodes = root.querySelectorAll("[data-bind]");
-  const unsubscribers = [];
+  const { immediate = false } = options;
 
-  nodes.forEach(el => {
-    const bindPath = el.getAttribute("data-bind");
-    
-    if (!bindPath) {
-      console.warn('[Lume.js] Empty data-bind attribute found', el);
-      return;
-    }
+  // Core binding logic extracted to separate function
+  const performBinding = () => {
+    const nodes = root.querySelectorAll("[data-bind]");
+    const cleanups = [];
 
-    const pathArr = bindPath.split(".");
-    const lastKey = pathArr.pop();
+    nodes.forEach(el => {
+      const bindPath = el.getAttribute("data-bind");
+      
+      if (!bindPath) {
+        console.warn('[Lume.js] Empty data-bind attribute found', el);
+        return;
+      }
 
-    let target;
-    try {
-      target = resolvePath(store, pathArr);
-    } catch (err) {
-      console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
-      return;
-    }
+      const pathArr = bindPath.split(".");
+      const lastKey = pathArr.pop();
 
-    if (!target || typeof target.$subscribe !== 'function') {
-      console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
-      return;
-    }
-
-    // Subscribe to changes
-    const unsub = target.$subscribe(lastKey, val => {
-      updateElement(el, val);
-    });
+      let target;
+      try {
+        target = resolvePath(store, pathArr);
+      } catch (err) {
+        console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
+        return;
+      }
 
-    unsubscribers.push(unsub);
+      if (!target || typeof target.$subscribe !== 'function') {
+        console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
+        return;
+      }
 
-    // Two-way binding for form inputs
-    if (isFormInput(el)) {
-      el.addEventListener("input", e => {
-        target[lastKey] = getInputValue(e.target);
+      // Subscribe to changes - receives already-batched notifications
+      const unsubscribe = target.$subscribe(lastKey, val => {
+        updateElement(el, val);
       });
-    }
-  });
+      cleanups.push(unsubscribe);
+
+      // Two-way binding for form inputs
+      if (isFormInput(el)) {
+        const handler = e => {
+          target[lastKey] = getInputValue(e.target);
+        };
+        el.addEventListener("input", handler);
+        cleanups.push(() => el.removeEventListener("input", handler));
+      }
+    });
 
-  // Return cleanup function
-  return () => {
-    unsubscribers.forEach(unsub => unsub());
+    return () => {
+      cleanups.forEach(cleanup => cleanup());
+    };
   };
+
+  // Auto-wait for DOM if needed (unless immediate flag is set)
+  if (!immediate && document.readyState === 'loading') {
+    let cleanup = null;
+    const onReady = () => {
+      cleanup = performBinding();
+    };
+    document.addEventListener('DOMContentLoaded', onReady, { once: true });
+    
+    // Return cleanup function that handles both cases
+    return () => {
+      if (cleanup) {
+        cleanup();
+      } else {
+        // If cleanup hasn't been created yet, remove the event listener
+        document.removeEventListener('DOMContentLoaded', onReady);
+      }
+    };
+  }
+
+  // Immediate binding (DOM already ready or immediate flag set)
+  return performBinding();
 }
 
 /**
@@ -89,8 +127,13 @@ export function bindDom(root, store) {
 function updateElement(el, val) {
   if (el.tagName === "INPUT") {
     if (el.type === "checkbox") {
+      // Single checkbox: bind to boolean value
+      // For multiple checkboxes, use nested state objects:
+      //   <input data-bind="tags.javascript"> → state({ tags: state({ javascript: true }) })
       el.checked = Boolean(val);
     } else if (el.type === "radio") {
+      // Radio: checked when el.value matches state value
+      // String() handles null/undefined gracefully (no radio selected)
       el.checked = el.value === String(val);
     } else {
       el.value = val ?? '';

package/src/core/effect.js

@@ -0,0 +1,104 @@
+/**
+ * Lume-JS Effect
+ * 
+ * Automatic dependency tracking for reactive effects.
+ * Tracks which state properties are accessed during execution
+ * and automatically re-runs when those properties change.
+ * 
+ * Part of core because it's fundamental to modern reactivity.
+ * 
+ * Usage:
+ *   import { effect } from "lume-js";
+ *   
+ *   effect(() => {
+ *     console.log('Count is:', store.count);
+ *     // Automatically re-runs when store.count changes
+ *   });
+ * 
+ * Features:
+ * - Automatic dependency collection
+ * - Dynamic dependencies (tracks what you actually access)
+ * - Returns cleanup function
+ * - Plays nicely with per-state batching (no global scheduler)
+ *
+ */
+
+/**
+ * Creates an effect that automatically tracks dependencies
+ *
+ * The effect runs immediately and collects dependencies by tracking
+ * which state properties are accessed. When any dependency changes,
+ * the effect re-runs automatically.
+ * 
+ * @param {function} fn - Function to run reactively
+ * @returns {function} Cleanup function to stop the effect
+ * 
+ * @example
+ * const store = state({ count: 0, name: 'Alice' });
+ * 
+ * const cleanup = effect(() => {
+ *   // Only tracks 'count' (name not accessed)
+ *   document.title = `Count: ${store.count}`;
+ * });
+ * 
+ * store.count = 5;  // Effect re-runs
+ * store.name = 'Bob'; // Effect does NOT re-run
+ * 
+ * cleanup(); // Stop tracking
+ */
+export function effect(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('effect() requires a function');
+  }
+
+  const cleanups = [];
+  let isRunning = false; // Prevent infinite recursion
+  
+  /**
+   * Execute the effect function and collect dependencies
+   *
+   * The execution re-tracks accessed keys on every run. Subscriptions
+   * are cleaned up and re-established so the effect always reflects
+   * current dependencies.
+   */
+  const execute = () => {
+    if (isRunning) return; // Prevent re-entry
+    
+    // Clean up previous subscriptions
+    cleanups.forEach(cleanup => cleanup());
+    cleanups.length = 0;
+    
+    // Create effect context for tracking
+    const effectContext = {
+      fn,
+      cleanups,
+      execute, // Reference to this execute function
+      tracking: {} // Map of tracked keys
+    };
+    
+    // Set as current effect (for state.js to detect)
+    globalThis.__LUME_CURRENT_EFFECT__ = effectContext;
+    isRunning = true;
+    
+    try {
+      // Run the effect function (this triggers state getters)
+      fn();
+    } catch (error) {
+      console.error('[Lume.js effect] Error in effect:', error);
+      throw error;
+    } finally {
+      // Always clean up, even if error
+      globalThis.__LUME_CURRENT_EFFECT__ = undefined;
+      isRunning = false;
+    }
+  };
+  
+  // Run immediately to collect initial dependencies
+  execute();
+
+  // Return cleanup function
+  return () => {
+    cleanups.forEach(cleanup => cleanup());
+    cleanups.length = 0;
+  };
+}

package/src/core/state.js

@@ -1,14 +1,17 @@
-// src/core/state.js
 /**
  * Lume-JS Reactive State Core
  *
  * Provides minimal reactive state with standard JavaScript.
+ * Features automatic microtask batching for performance.
+ * Supports automatic dependency tracking for effects.
  * 
  * Features:
  * - Lightweight and Go-style
  * - Explicit nested states
  * - $subscribe for listening to key changes
  * - Cleanup with unsubscribe
+ * - Per-state microtask batching for writes
+ * - Effect dependency tracking support (deduped per state flush)
  *
  * Usage:
  *   import { state } from "lume-js";
@@ -17,12 +20,18 @@
  *   unsub(); // cleanup
  */
 
+// Per-state batching – each state object maintains its own microtask flush.
+// This keeps effects simple and aligned with Lume's minimal philosophy.
+
 /**
  * Creates a reactive state object.
  * 
  * @param {Object} obj - Initial state object
  * @returns {Proxy} Reactive proxy with $subscribe method
  */
+// Internal symbol used to mark reactive proxies (non-enumerable via Proxy trap)
+const REACTIVE_MARKER = Symbol('__LUME_REACTIVE__');
+
 export function state(obj) {
   // Validate input
   if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
@@ -30,26 +39,101 @@ export function state(obj) {
   }
 
   const listeners = {};
+  const pendingNotifications = new Map(); // Per-state pending changes
+  const pendingEffects = new Set(); // Dedupe effects per state
+  let flushScheduled = false;
 
-  // Notify subscribers of a key
-  function notify(key, val) {
-    if (listeners[key]) {
-      listeners[key].forEach(fn => fn(val));
-    }
+  /**
+   * Schedule a single microtask flush for this state object.
+   *
+   * Flush order per state:
+   * 1) Notify subscribers for changed keys (key → subscribers)
+   * 2) Run each queued effect exactly once (Set-based dedupe)
+   *
+   * Notes:
+   * - Batching is per state; effects that depend on multiple states
+   *   may run once per state that changed (by design).
+   */
+  function scheduleFlush() {
+    if (flushScheduled) return;
+    
+    flushScheduled = true;
+    queueMicrotask(() => {
+      flushScheduled = false;
+      
+      // Notify all subscribers of changed keys
+      // Snapshot listeners array to handle unsubscribes during iteration
+      for (const [key, value] of pendingNotifications) {
+        if (listeners[key]) {
+          const subscribersSnapshot = Array.from(listeners[key]);
+          subscribersSnapshot.forEach(fn => fn(value));
+        }
+      }
+      
+      pendingNotifications.clear();
+      
+      // Run each effect exactly once (Set deduplicates)
+      const effects = Array.from(pendingEffects);
+      pendingEffects.clear();
+      effects.forEach(effect => effect());
+    });
   }
 
   const proxy = new Proxy(obj, {
     get(target, key) {
+      // Reactive marker check (avoid tracking for internal symbol)
+      if (key === REACTIVE_MARKER) return true;
+      // Skip effect tracking for internal meta methods (e.g. $subscribe)
+      if (typeof key === 'string' && key.startsWith('$')) {
+        return target[key];
+      }
+      // Support effect tracking
+      // Check if we're inside an effect context
+      if (typeof globalThis.__LUME_CURRENT_EFFECT__ !== 'undefined') {
+        const currentEffect = globalThis.__LUME_CURRENT_EFFECT__;
+        
+        if (currentEffect && !currentEffect.tracking[key]) {
+          // Mark as tracked
+          currentEffect.tracking[key] = true;
+          
+          // Subscribe to changes for this key (skip initial call for effects)
+          const unsubscribe = (() => {
+            if (!listeners[key]) listeners[key] = [];
+            
+            const effectFn = () => {
+              // Queue effect in this state's pending set
+              // Set deduplicates - effect runs once even if multiple keys change
+              pendingEffects.add(currentEffect.execute);
+            };
+            
+            listeners[key].push(effectFn);
+            
+            // Return unsubscribe function (no initial call for effects)
+            return () => {
+              if (listeners[key]) {
+                listeners[key] = listeners[key].filter(subscriber => subscriber !== effectFn);
+              }
+            };
+          })();
+          
+          // Store cleanup function
+          currentEffect.cleanups.push(unsubscribe);
+        }
+      }
+      
       return target[key];
     },
+    
     set(target, key, value) {
       const oldValue = target[key];
+      if (oldValue === value) return true;
+      
       target[key] = value;
       
-      // Only notify if value actually changed
-      if (oldValue !== value) {
-        notify(key, value);
-      }
+      // Batch notifications at the state level (per-state, not global)
+      pendingNotifications.set(key, value);
+      scheduleFlush();
+      
       return true;
     }
   });
@@ -71,7 +155,7 @@ export function state(obj) {
     if (!listeners[key]) listeners[key] = [];
     listeners[key].push(fn);
     
-    // Call immediately with current value
+    // Call immediately with current value (NOT batched)
     fn(proxy[key]);
 
     // Return unsubscribe function
@@ -83,4 +167,14 @@ export function state(obj) {
   };
 
   return proxy;
+}
+
+/**
+ * Determine if an object is a Lume reactive proxy.
+ * Defensive: ensures object and marker presence.
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isReactive(obj) {
+  return !!(obj && typeof obj === 'object' && obj[REACTIVE_MARKER]);
 }