lume-js 0.3.0 → 0.4.1

package/README.md

@@ -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.2.1-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
@@ -43,7 +45,10 @@ npm install lume-js
 
 ```html
 <script type="module">
-  import { state, bindDom } from 'https://cdn.jsdelivr.net/npm/lume-js/src/index.js';
+  import { state, bindDom, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/src/index.js';
+  
+  // For addons:
+  import { computed, watch } from 'https://cdn.jsdelivr.net/npm/lume-js/src/addons/index.js';
 </script>
 ```
 
@@ -51,6 +56,16 @@ npm install lume-js
 
 ## Quick Start
 
+### Examples
+
+Run the live examples (including the new Todo app) with Vite:
+
+```bash
+npm run dev
+```
+
+Then open the Examples index (Vite will auto-open): `http://localhost:5173/examples/`
+
 **HTML:**
 ```html
 <div>
@@ -64,7 +79,7 @@ npm install lume-js
 
 **JavaScript:**
 ```javascript
-import { state, bindDom } from 'lume-js';
+import { state, bindDom, effect } from 'lume-js';
 
 // Create reactive state
 const store = state({
@@ -72,16 +87,24 @@ const store = state({
   name: 'World'
 });
 
-// Bind to DOM
+// Bind to DOM (updates on state changes)
 const cleanup = bindDom(document.body, store);
 
+// Auto-update document title when name changes
+const effectCleanup = effect(() => {
+  document.title = `Hello, ${store.name}!`;
+});
+
 // Update state with standard JavaScript
 document.getElementById('increment').addEventListener('click', () => {
   store.count++;
 });
 
 // Cleanup when done (important!)
-window.addEventListener('beforeunload', () => cleanup());
+window.addEventListener('beforeunload', () => {
+  cleanup();
+  effectCleanup();
+});
 ```
 
 That's it! No build step, no custom syntax, just HTML and JavaScript.
@@ -92,7 +115,7 @@ That's it! No build step, no custom syntax, just HTML and JavaScript.
 
 ### `state(object)`
 
-Creates a reactive state object using Proxy.
+Creates a reactive state object using Proxy with automatic dependency tracking.
 
 ```javascript
 const store = state({
@@ -109,21 +132,63 @@ store.user.name = 'Bob';
 ```
 
 **Features:**
+- ✅ Automatic dependency tracking for effects
+- ✅ Per-state microtask batching for performance
 - ✅ Validates input (must be plain object)
 - ✅ Only triggers updates when value actually changes
 - ✅ Returns cleanup function from `$subscribe`
+- ✅ Deduplicates effect runs per flush cycle
 
-### `bindDom(root, store)`
+### `effect(fn)`
+
+Creates an effect that automatically tracks dependencies and re-runs when they change.
+
+```javascript
+const store = state({ count: 0, name: 'Alice' });
+
+const cleanup = effect(() => {
+  // Only tracks 'count' (name is not accessed)
+  console.log(`Count: ${store.count}`);
+});
+
+store.count = 5;    // Effect re-runs
+store.name = 'Bob'; // Effect does NOT re-run
+
+cleanup(); // Stop the effect
+```
+
+**Features:**
+- ✅ Automatic dependency collection (tracks what you actually access)
+- ✅ Dynamic dependencies (re-tracks on every execution)
+- ✅ Returns cleanup function
+- ✅ Prevents infinite recursion
+- ✅ Integrates with per-state batching (no global scheduler)
+
+**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, 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">`
@@ -134,14 +199,111 @@ cleanup();
 - ✅ Radio buttons: `<input type="radio" data-bind="choice">`
 - ✅ Nested paths: `<span data-bind="user.name"></span>`
 
-**NEW in v0.3.0:**
-- Returns cleanup function
-- Better error messages with `[Lume.js]` prefix
-- Handles edge cases (empty bindings, invalid paths)
+**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. Returns unsubscribe function.
+Manually subscribe to state changes. Calls callback immediately with current value, then on every change.
 
 ```javascript
 const unsubscribe = store.$subscribe('count', (value) => {
@@ -157,10 +319,135 @@ const unsubscribe = store.$subscribe('count', (value) => {
 unsubscribe();
 ```
 
-**NEW in v0.3.0:**
-- Returns unsubscribe function (was missing in v0.2.x)
-- Validates callback is a function
-- Only notifies on actual value changes
+**Features:**
+- ✅ Returns unsubscribe function
+- ✅ Validates callback is a function
+- ✅ Calls immediately with current value (not batched)
+- ✅ Only notifies on actual value changes (via batching)
+
+---
+
+## Addons
+
+Lume.js provides optional addons for advanced reactivity patterns. Import from `lume-js/addons`.
+
+### `computed(fn)`
+
+Creates a computed value that automatically updates when its dependencies change.
+
+```javascript
+import { state, effect } 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();
+```
+
+**Features:**
+- ✅ Automatic dependency tracking using `effect()`
+- ✅ Cached values (only recomputes when dependencies change)
+- ✅ Subscribe to changes with `.subscribe(callback)`
+- ✅ Cleanup with `.dispose()`
+- ✅ Error handling (sets to undefined on error)
+
+### `watch(store, key, callback)`
+
+Alias for `$subscribe` - observes changes to a specific state key.
+
+```javascript
+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();
+```
+
+**Note:** `watch()` is just a convenience wrapper around `store.$subscribe()`. Use whichever feels more natural.
+
+---
+
+## 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
+  });
+  ```
 
 ---
 
@@ -262,14 +549,65 @@ window.addEventListener('beforeunload', () => {
 <input type="checkbox" data-bind="user.settings.notifications">
 ```
 
+### Using Effects for Auto-Updates
+
+```javascript
+import { state, effect } from 'lume-js';
+
+const store = state({ 
+  firstName: 'Alice', 
+  lastName: 'Smith' 
+});
+
+// Auto-update title when name changes
+effect(() => {
+  document.title = `${store.firstName} ${store.lastName}`;
+});
+
+store.firstName = 'Bob'; 
+// Title automatically updates to "Bob Smith" in next microtask
+```
+
+### Computed Values
+
+```javascript
+import { state } from 'lume-js';
+import { computed } from 'lume-js/addons';
+
+const cart = state({
+  items: state([
+    state({ price: 10, quantity: 2 }),
+    state({ price: 15, quantity: 1 })
+  ])
+});
+
+const total = computed(() => {
+  return cart.items.reduce((sum, item) => 
+    sum + (item.price * item.quantity), 0
+  );
+});
+
+console.log(total.value); // 35
+
+cart.items[0].quantity = 3;
+// After microtask:
+console.log(total.value); // 45
+```
+
 ### Integration with GSAP
 
 ```javascript
 import gsap from 'gsap';
-import { state } from 'lume-js';
+import { state, effect } from 'lume-js';
 
 const ui = state({ x: 0, y: 0 });
 
+// Use effect for automatic animation updates
+effect(() => {
+  gsap.to('.box', { x: ui.x, y: ui.y, duration: 0.5 });
+});
+
+// Or use $subscribe
 const unsubX = ui.$subscribe('x', (value) => {
   gsap.to('.box', { x: value, duration: 0.5 });
 });
@@ -283,17 +621,28 @@ window.addEventListener('beforeunload', () => unsubX());
 ### Cleanup Pattern (Important!)
 
 ```javascript
+import { state, effect, bindDom } from 'lume-js';
+import { computed } from 'lume-js/addons';
+
 const store = state({ data: [] });
 const cleanup = bindDom(root, store);
 
 const unsub1 = store.$subscribe('data', handleData);
 const unsub2 = store.$subscribe('status', handleStatus);
 
+const effectCleanup = effect(() => {
+  console.log('Data length:', store.data.length);
+});
+
+const total = computed(() => store.data.length * 2);
+
 // Cleanup when component unmounts
 function destroy() {
-  cleanup();      // Remove DOM bindings
-  unsub1();       // Remove subscription 1
-  unsub2();       // Remove subscription 2
+  cleanup();           // Remove DOM bindings
+  unsub1();            // Remove subscription 1
+  unsub2();            // Remove subscription 2
+  effectCleanup();     // Stop effect
+  total.dispose();     // Stop computed
 }
 
 // For SPA frameworks
@@ -380,25 +729,27 @@ document.addEventListener('click', () => store.clicks++);
 
 ---
 
-## What's New in v0.3.0?
-
-### Breaking Changes
-- ✅ `subscribe` → `$subscribe` (restored from v0.1.0)
-- ✅ `$subscribe` now returns unsubscribe function
-
-### New Features
-- ✅ TypeScript definitions (`index.d.ts`)
-- ✅ `bindDom()` returns cleanup function
+## What's New
+
+### Core Features
+- ✅ **Automatic dependency tracking** - `effect()` automatically tracks which state properties are accessed
+- ✅ **Per-state batching** - Each state object maintains its own microtask flush for optimal performance
+- ✅ **Effect deduplication** - Effects only run once per flush cycle, even if multiple dependencies change
+- ✅ **TypeScript support** - Full type definitions in `index.d.ts`
+- ✅ **Cleanup functions** - All reactive APIs return cleanup/unsubscribe functions
+
+### Addons
+- ✅ **`computed()`** - Memoized computed values with automatic dependency tracking
+- ✅ **`watch()`** - Convenience alias for `$subscribe`
+
+### API Design
+- ✅ `state()` - Create reactive state with automatic tracking support
+- ✅ `effect()` - Core reactivity primitive (automatic dependency collection)
+- ✅ `bindDom()` - DOM binding with two-way sync for form inputs
+- ✅ `$subscribe()` - Manual subscriptions (calls immediately with current value)
+- ✅ All functions return cleanup/unsubscribe functions
 - ✅ Better error handling with `[Lume.js]` prefix
-- ✅ Input validation (only plain objects)
-- ✅ Only triggers on actual value changes
-- ✅ Support for checkboxes, radio buttons, number inputs
-- ✅ Comprehensive example in `/examples/comprehensive/`
-
-### Bug Fixes
-- ✅ Fixed memory leaks (no cleanup in v0.2.x)
-- ✅ Fixed addon examples (used wrong API)
-- ✅ Better path resolution with detailed errors
+- ✅ Input validation on all public APIs
 
 ---
 
@@ -413,13 +764,49 @@ document.addEventListener('click', () => store.clicks++);
 
 ---
 
+## Testing
+
+Lume.js uses [Vitest](https://vitest.dev) with a jsdom environment. The test suite mirrors the source tree: files under `tests/core/**` map to `src/core/**`, and `tests/addons/**` map to `src/addons/**`.
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage with HTML report in ./coverage
+npm run coverage
+```
+
+**Import alias:** Tests use an alias so you can import from `src/...` without relative `../../` paths.
+
+```js
+// vitest.config.js
+resolve: {
+  alias: {
+    src: fileURLToPath(new URL('./src', import.meta.url))
+  }
+}
+```
+
+**Current coverage:**
+- 100% statements, functions, and lines
+- 100% branches (including edge-case paths)
+- 67 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, reactive identity, and cleanup semantics
+
+---
+
 ## Contributing
 
 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

@@ -1,14 +1,28 @@
 {
   "name": "lume-js",
-  "version": "0.3.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!'",
-    "preview": "vite preview"
+    "size": "node scripts/check-size.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
   },
   "files": [
     "src",
@@ -45,7 +59,10 @@
   },
   "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"