lume-js 0.2.1 → 0.4.0

package/package.json

@@ -1,16 +1,59 @@
 {
   "name": "lume-js",
-  "version": "0.2.1",
+  "version": "0.4.0",
+  "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "echo 'No build step yet, zero-runtime already!'"
+    "build": "echo 'No build step needed - zero-runtime library!'",
+    "size": "node scripts/check-size.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
   },
   "files": [
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "keywords": [
+    "reactive",
+    "state",
+    "dom",
+    "binding",
+    "standards",
+    "minimal",
+    "no-build",
+    "vanilla-js",
+    "data-bind",
+    "proxy",
+    "knockout",
+    "html-first",
+    "framework-agnostic",
+    "minimal-runtime",
+    "no-vdom",
+    "web-standards",
+    "lightweight"
+  ],
+  "author": "Sathvik C",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sathvikc/lume-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sathvikc/lume-js/issues"
+  },
+  "homepage": "https://github.com/sathvikc/lume-js#readme",
   "devDependencies": {
-    "vite": "^7.1.9"
+    "vite": "^7.1.9",
+    "vitest": "^2.1.4",
+    "@vitest/coverage-v8": "^2.1.4",
+    "jsdom": "^25.0.1"
+  },
+  "engines": {
+    "node": ">=20.19.0"
   }
 }

package/src/addons/computed.js

@@ -1,38 +1,136 @@
 /**
- * computed - creates a derived value based on state
- * @param {Function} fn - function that computes value from state
- * @returns {Object} - { get: () => value, recompute: () => void, subscribe: (cb) => unsubscribe }
+ * Lume-JS Computed Addon
+ * 
+ * Creates computed values that automatically update when dependencies change.
+ * Uses core effect() for automatic dependency tracking.
+ * 
+ * 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: 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
+ * const unsub = doubled.subscribe(value => {
+ *   console.log('Doubled changed to:', value);
+ * });
+ * 
+ * @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: () => {
-      if (dirty) recalc();
-      return value;
+    /**
+     * Get the current computed value
+     */
+    get 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);
-      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/watch.js

@@ -3,10 +3,11 @@
  * @param {Object} store - reactive store created with state()
  * @param {string} key - key in store to watch
  * @param {Function} callback - called with new value
+ * @returns {Function} unsubscribe function
  */
 export function watch(store, key, callback) {
-  if (!store.subscribe) {
+  if (!store.$subscribe) {
     throw new Error("store must be created with state()");
   }
-  store.subscribe(key, callback);
-}
+  return store.$subscribe(key, callback);
+}

package/src/core/bindDom.js

@@ -1,50 +1,128 @@
+// src/core/bindDom.js
 /**
- * Lume-JS Zero-runtime DOM binding
+ * Lume-JS DOM Binding
  *
  * Binds reactive state to DOM elements using [data-bind].
- * Supports two-way binding for INPUT/TEXTAREA.
+ * Supports two-way binding for INPUT/TEXTAREA/SELECT.
  *
  * Usage:
  *   import { bindDom } from "lume-js";
- *   bindDom(document.body, store);
+ *   const cleanup = bindDom(document.body, store);
+ *   // Later: cleanup();
  *
  * HTML:
  *   <span data-bind="count"></span>
  *   <input data-bind="user.name">
+ *   <select data-bind="theme"></select>
  */
 
 import { resolvePath } from "./utils.js";
 
 /**
- * Zero-runtime DOM binding for a reactive store
+ * DOM binding for reactive state
  * 
- * @param {HTMLElement} root - root element to scan for [data-bind]
- * @param {object} store - reactive state object
+ * @param {HTMLElement} root - Root element to scan for [data-bind]
+ * @param {object} store - Reactive state object
+ * @returns {function} Cleanup function to remove all bindings
  */
 export function bindDom(root, store) {
+  if (!(root instanceof HTMLElement)) {
+    throw new Error('bindDom() requires a valid HTMLElement as root');
+  }
+
+  if (!store || typeof store !== 'object') {
+    throw new Error('bindDom() requires a reactive state object');
+  }
+
   const nodes = root.querySelectorAll("[data-bind]");
+  const cleanups = [];
 
   nodes.forEach(el => {
-    const pathArr = el.getAttribute("data-bind").split(".");
+    const bindPath = el.getAttribute("data-bind");
+    
+    if (!bindPath) {
+      console.warn('[Lume.js] Empty data-bind attribute found', el);
+      return;
+    }
+
+    const pathArr = bindPath.split(".");
     const lastKey = pathArr.pop();
 
     let target;
     try {
-      target = resolvePath(store, pathArr); // must be wrapped with state() if nested
+      target = resolvePath(store, pathArr);
     } catch (err) {
-      console.warn(`Skipping binding for ${el}: ${err.message}`);
+      console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
       return;
     }
 
-    // Subscribe once
-    target.subscribe(lastKey, val => {
-      if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") el.value = val;
-      else el.textContent = val;
+    if (!target || typeof target.$subscribe !== 'function') {
+      console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
+      return;
+    }
+
+    // Subscribe to changes - receives already-batched notifications
+    const unsubscribe = target.$subscribe(lastKey, val => {
+      updateElement(el, val);
     });
+    cleanups.push(unsubscribe);
 
-    // 2-way binding for inputs
-    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
-      el.addEventListener("input", e => target[lastKey] = e.target.value);
+    // 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 () => {
+    cleanups.forEach(cleanup => cleanup());
+  };
 }
+
+/**
+ * Update DOM element with new value
+ * @private
+ */
+function updateElement(el, val) {
+  if (el.tagName === "INPUT") {
+    if (el.type === "checkbox") {
+      el.checked = Boolean(val);
+    } else if (el.type === "radio") {
+      el.checked = el.value === String(val);
+    } else {
+      el.value = val ?? '';
+    }
+  } else if (el.tagName === "TEXTAREA") {
+    el.value = val ?? '';
+  } else if (el.tagName === "SELECT") {
+    el.value = val ?? '';
+  } else {
+    el.textContent = val ?? '';
+  }
+}
+
+/**
+ * Get value from form input
+ * @private
+ */
+function getInputValue(el) {
+  if (el.type === "checkbox") {
+    return el.checked;
+  } else if (el.type === "number" || el.type === "range") {
+    return el.valueAsNumber;
+  }
+  return el.value;
+}
+
+/**
+ * Check if element is a form input
+ * @private
+ */
+function isFormInput(el) {
+  return el.tagName === "INPUT" || 
+         el.tagName === "TEXTAREA" || 
+         el.tagName === "SELECT";
+}

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,41 +1,128 @@
 /**
  * Lume-JS Reactive State Core
  *
- * Provides minimal, zero-runtime reactive state.
+ * 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
+ * - $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";
  *   const store = state({ count: 0 });
- *   store.subscribe("count", val => console.log(val));
+ *   const unsub = store.$subscribe("count", val => console.log(val));
+ *   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
+ * @returns {Proxy} Reactive proxy with $subscribe method
  */
 export function state(obj) {
+  // Validate input
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('state() requires a plain object');
+  }
+
   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
+      for (const [key, value] of pendingNotifications) {
+        if (listeners[key]) {
+          listeners[key].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) {
+      // 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;
-      notify(key, value);
+      
+      // Batch notifications at the state level (per-state, not global)
+      pendingNotifications.set(key, value);
+      scheduleFlush();
+      
       return true;
     }
   });
@@ -43,15 +130,30 @@ export function state(obj) {
   /**
    * Subscribe to changes for a specific key.
    * Calls the callback immediately with the current value.
+   * Returns an unsubscribe function for cleanup.
    * 
-   * @param {string} key 
-   * @param {function} fn 
+   * @param {string} key - Property key to watch
+   * @param {function} fn - Callback function
+   * @returns {function} Unsubscribe function
    */
-  proxy.subscribe = (key, fn) => {
+  proxy.$subscribe = (key, fn) => {
+    if (typeof fn !== 'function') {
+      throw new Error('Subscriber must be a function');
+    }
+
     if (!listeners[key]) listeners[key] = [];
     listeners[key].push(fn);
-    fn(proxy[key]); // initialize
+    
+    // Call immediately with current value (NOT batched)
+    fn(proxy[key]);
+
+    // Return unsubscribe function
+    return () => {
+      if (listeners[key]) {
+        listeners[key] = listeners[key].filter(subscriber => subscriber !== fn);
+      }
+    };
   };
 
   return proxy;
-}
+}