npm - lume-js - Versions diffs - 0.4.0 → 0.4.1 - Mend

lume-js 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -5,7 +5,7 @@
 Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required, no framework lock-in.
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.4.0-green.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.1-green.svg)](package.json)
 ## Why Lume.js?
@@ -29,6 +29,8 @@ Minimal reactive state management using only standard JavaScript and HTML - no c
 **Lume.js is essentially "Modern Knockout.js" - standards-only reactivity for 2025.**
+📖 **New to the project?** Read [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) to understand our design philosophy and why certain choices were made.
 ---
 ## Installation
@@ -164,17 +166,29 @@ cleanup(); // Stop the effect
 **How it works:** Effects use `globalThis.__LUME_CURRENT_EFFECT__` to track which state properties are accessed during execution. When any tracked property changes, the effect is queued in that state's pending effects set and runs once in the next microtask.
-### `bindDom(root, store)`
+### `bindDom(root, store, options?)`
 Binds reactive state to DOM elements with `data-bind` attributes.
+**Automatically waits for DOMContentLoaded** if the document is still loading, making it safe to call from anywhere (even in `<head>`).
 ```javascript
+// 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 all bindings
 cleanup();
 ```
+**Parameters:**
+- `root` (HTMLElement) - Root element to scan for `[data-bind]` attributes
+- `store` (Object) - Reactive state object
+- `options` (Object, optional)
+  - `immediate` (Boolean) - Skip auto-wait, bind immediately. Default: `false`
 **Supports:**
 - ✅ Text content: `<span data-bind="count"></span>`
 - ✅ Input values: `<input data-bind="name">`
@@ -185,12 +199,108 @@ cleanup();
 - ✅ Radio buttons: `<input type="radio" data-bind="choice">`
 - ✅ Nested paths: `<span data-bind="user.name"></span>`
+**Multiple Checkboxes Pattern:**
+For multiple checkboxes, use nested state instead of arrays:
+```javascript
+// ✅ Recommended: Nested state objects
+const store = state({
+  tags: state({
+    javascript: true,
+    python: false,
+    go: true
+  })
+});
+```
+```html
+<input type="checkbox" data-bind="tags.javascript"> JavaScript
+<input type="checkbox" data-bind="tags.python"> Python
+<input type="checkbox" data-bind="tags.go"> Go
+```
+Nested state is **more explicit and easier to validate** than array-based bindings. See [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md#why-nested-state-for-multiple-checkboxes-instead-of-arrays) for the full rationale.
 **Features:**
+- ✅ Auto-waits for DOM if needed (no timing issues!)
 - ✅ Returns cleanup function
 - ✅ Better error messages with `[Lume.js]` prefix
 - ✅ Handles edge cases (empty bindings, invalid paths)
 - ✅ Two-way binding for form inputs
+### `isReactive(obj)`
+Checks whether a value is a reactive proxy created by `state()`.
+```javascript
+import { state, isReactive } from 'lume-js';
+const original = { count: 1 };
+const store = state(original);
+isReactive(store);    // true
+isReactive(original); // false
+isReactive(null);     // false
+```
+**How it works:**
+Lume.js uses an internal `Symbol` checked via the Proxy `get` trap rather than mutating the proxy or storing external WeakSet state. Accessing `obj[REACTIVE_SYMBOL]` returns `true` only for reactive proxies, and the symbol is not enumerable or visible via `Object.getOwnPropertySymbols`.
+**Characteristics:**
+- ✅ Zero mutation of the proxy
+- ✅ Invisible to enumeration and reflection
+- ✅ Fast: single symbol identity check in the `get` path
+- ✅ Supports nested reactive states naturally
+- ✅ Skips tracking meta `$`-prefixed methods (e.g. `$subscribe`)
+**When to use:** Utility/debugging, conditional wrapping patterns like:
+```javascript
+function ensureReactive(val) {
+  return isReactive(val) ? val : state(val);
+}
+```
+**Why Auto-Ready?**
+Works seamlessly regardless of script placement:
+```html
+<!-- ✅ Works in <head> -->
+<script type="module">
+  import { state, bindDom } from 'lume-js';
+  const store = state({ count: 0 });
+  bindDom(document.body, store); // Auto-waits for DOM!
+</script>
+<!-- ✅ Works inline in <body> -->
+<body>
+  <span data-bind="count"></span>
+  <script type="module">
+    // bindDom() waits for DOMContentLoaded automatically
+  </script>
+</body>
+<!-- ✅ Works with defer -->
+<script type="module" defer>
+  // Already loaded, executes immediately
+</script>
+```
+**When to use `immediate: true`:**
+Rare scenarios where you're dynamically creating DOM or need precise control:
+```javascript
+// Dynamic DOM injection
+const container = document.createElement('div');
+container.innerHTML = '<span data-bind="count"></span>';
+document.body.appendChild(container);
+// Bind immediately (DOM already exists)
+bindDom(container, store, { immediate: true });
+```
 ### `$subscribe(key, callback)`
 Manually subscribe to state changes. Calls callback immediately with current value, then on every change.
@@ -277,6 +387,70 @@ unwatch();
 ---
+## Choosing the Right Reactive Pattern
+Lume.js provides three ways to react to state changes. Here's when to use each:
+| Pattern | Use When | Pros | Cons |
+|---------|----------|------|------|
+| **`bindDom()`** | Syncing state ↔ DOM | Zero code, declarative HTML | DOM-only, no custom logic |
+| **`$subscribe()`** | Listening to specific keys | Explicit, immediate, simple | Manual dependency tracking |
+| **`effect()`** | Auto-run code on any state access | Automatic dependencies, concise | Microtask delay, can infinite loop |
+| **`computed()`** | Deriving values from state | Cached, automatic recompute | Addon import, slight overhead |
+**Quick Decision Tree:**
+```
+Need to update DOM?
+├─ Yes, just sync form/text → Use bindDom()
+└─ No, custom logic needed
+   ├─ Watch single key? → Use $subscribe()
+   ├─ Watch multiple keys dynamically? → Use effect()
+   └─ Derive a value? → Use computed()
+```
+**Examples:**
+```javascript
+// 1. bindDom - Zero code DOM sync
+<span data-bind="count"></span>
+bindDom(document.body, store);
+// 2. $subscribe - Specific key, immediate execution
+store.$subscribe('count', (val) => {
+  if (val > 10) showNotification('High!');
+});
+// 3. effect - Multiple keys, automatic tracking
+effect(() => {
+  document.title = `${store.user.name}: ${store.count}`;
+  // Tracks both user.name and count automatically
+});
+// 4. computed - Derive cached value
+import { computed } from 'lume-js/addons';
+const total = computed(() => store.items.reduce((sum, i) => sum + i.price, 0));
+console.log(total.value);
+```
+**Gotchas:**
+- ⚠️ **effect()** runs in next microtask (~0.002ms delay). Use `$subscribe()` for immediate execution.
+- ⚠️ **Don't mutate tracked state inside effect** - causes infinite loops:
+  ```javascript
+  // ❌ BAD - Infinite loop
+  effect(() => {
+    store.count++; // Writes to what it reads!
+  });
+  // ✅ GOOD - Read-only or separate keys
+  effect(() => {
+    store.displayCount = store.count * 2; // Different keys
+  });
+  ```
+---
 ## Examples
 ### Basic Counter
@@ -619,7 +793,7 @@ resolve: {
 **Current coverage:**
 - 100% statements, functions, and lines
 - 100% branches (including edge-case paths)
-- 37 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, and cleanup semantics
+- 67 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, reactive identity, and cleanup semantics
 ---
@@ -629,7 +803,10 @@ We welcome contributions! Please:
 1. **Focus on:** Examples, documentation, bug fixes, performance
 2. **Avoid:** Adding core features without discussion (keep it minimal!)
-3. **Check:** Project specification for philosophy
+3. **Read:** [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) to understand our philosophy and why certain choices were made
+4. **Propose alternatives:** If you think a design decision should be reconsidered, open an issue with your reasoning
+Before suggesting new features, check if they align with Lume's core principles: standards-only, minimal API, no build step required.
 ---

package/package.json CHANGED Viewed

@@ -1,10 +1,21 @@
 {
   "name": "lume-js",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./addons": {
+      "import": "./src/addons/index.js",
+      "types": "./src/addons/index.d.ts"
+    }
+  },
   "scripts": {
     "dev": "vite",
     "build": "echo 'No build step needed - zero-runtime library!'",

package/src/addons/index.d.ts ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 cleanups = [];
+  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;
-    }
+      let target;
+      try {
+        target = resolvePath(store, pathArr);
+      } catch (err) {
+        console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
+        return;
+      }
+      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);
+      // 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));
+      }
     });
-    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 () => {
-    cleanups.forEach(cleanup => cleanup());
+    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/state.js CHANGED Viewed

@@ -29,6 +29,9 @@
  * @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)) {
@@ -59,9 +62,11 @@ export function state(obj) {
       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]) {
-          listeners[key].forEach(fn => fn(value));
+          const subscribersSnapshot = Array.from(listeners[key]);
+          subscribersSnapshot.forEach(fn => fn(value));
         }
       }
@@ -76,6 +81,12 @@ export function state(obj) {
   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') {
@@ -156,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]);
 }

package/src/index.d.ts CHANGED Viewed

@@ -58,20 +58,39 @@ export type ReactiveState<T extends object> = T & {
  */
 export function state<T extends object>(obj: T): ReactiveState<T>;
+/**
+ * Options for bindDom function
+ */
+export interface BindDomOptions {
+  /**
+   * Skip auto-wait for DOM, bind immediately
+   * @default false
+   */
+  immediate?: boolean;
+}
 /**
  * Bind reactive state to DOM elements
  *
+ * Automatically waits for DOMContentLoaded if the document is still loading,
+ * ensuring safe binding regardless of when the function is called.
+ *
  * @param root - Root element to scan for [data-bind] attributes
  * @param store - Reactive state object
+ * @param options - Optional configuration
  * @returns Cleanup function to remove all bindings
  * @throws {Error} If root is not an HTMLElement
  * @throws {Error} If store is not a reactive state object
  *
  * @example
  * ```typescript
+ * // Default: Auto-waits for DOM (safe anywhere)
  * const store = state({ count: 0 });
  * const cleanup = bindDom(document.body, store);
  *
+ * // Advanced: Force immediate binding (no auto-wait)
+ * const cleanup = bindDom(myElement, store, { immediate: true });
+ *
  * // Later: cleanup all bindings
  * cleanup();
  * ```
@@ -84,7 +103,8 @@ export function state<T extends object>(obj: T): ReactiveState<T>;
  */
 export function bindDom(
   root: HTMLElement,
-  store: ReactiveState<any>
+  store: ReactiveState<any>,
+  options?: BindDomOptions
 ): Unsubscribe;
 /**
@@ -112,4 +132,11 @@ export function bindDom(
  * cleanup(); // Stop the effect
  * ```
  */
-export function effect(fn: () => void): Unsubscribe;
+export function effect(fn: () => void): Unsubscribe;
+/**
+ * Check if a value is a Lume reactive proxy produced by state().
+ * Returns true only for objects created by state().
+ * @param obj - Value to check
+ */
+export function isReactive(obj: any): boolean;

package/src/index.js CHANGED Viewed

@@ -10,6 +10,6 @@
  *   import { state, bindDom, effect } from "lume-js";
  */
-export { state } from "./core/state.js";
+export { state, isReactive } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
 export { effect } from "./core/effect.js";