lume-js 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sathvik C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# lume-js
+
+Minimal reactive state + DOM binding with **zero runtime** overhead.  
+Inspired by Go-style simplicity.
+
+## Philosophy
+- ⚡ Zero runtime, direct DOM updates (no VDOM, no diffing).
+- 🔑 Simple `state()` and `bindDom()` — that's it.
+- 🧩 Explicit nesting (`state({ user: state({ name: "Alice" }) })`).
+- ✨ Works anywhere — plain JS, or alongside other frameworks.
+
+## Install
+
+```bash
+npm install lume-js
+```
+
+## Example
+
+**main.js**
+```js
+import { state, bindDom } from "lume-js";
+
+const store = state({
+  count: 0,
+  user: state({ name: "Alice" })
+});
+
+bindDom(document.body, store);
+
+document.getElementById("inc").addEventListener("click", () => {
+  store.count++;
+});
+
+document.getElementById("changeName").addEventListener("click", () => {
+  store.user.name = store.user.name === "Alice" ? "Bob" : "Alice";
+});
+```
+
+**index.html**
+```html
+<p>Count: <span data-bind="count"></span></p>
+<p>User Name: <span data-bind="user.name"></span></p>
+
+<button id="inc">Increment</button>
+<button id="changeName">Change Name</button>
+```
+
+## Status
+
+🚧 Early alpha (`0.1.0`). API may change. Feedback welcome!

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "lume-js",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "0.2.0",
+  "main": "src/index.js",
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "vite examples",
+    "build": "echo 'No build step yet, zero-runtime already!'"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC"
+  "files": [
+    "src"
+  ],
+  "devDependencies": {
+    "vite": "^7.1.9"
+  }
 }

package/src/core/bindDom.js

@@ -0,0 +1,50 @@
+/**
+ * Lume-JS Zero-runtime DOM binding
+ *
+ * Binds reactive state to DOM elements using [data-bind].
+ * Supports two-way binding for INPUT/TEXTAREA.
+ *
+ * Usage:
+ *   import { bindDom } from "lume-js";
+ *   bindDom(document.body, store);
+ *
+ * HTML:
+ *   <span data-bind="count"></span>
+ *   <input data-bind="user.name">
+ */
+
+import { resolvePath } from "./utils.js";
+
+/**
+ * Zero-runtime DOM binding for a reactive store
+ * 
+ * @param {HTMLElement} root - root element to scan for [data-bind]
+ * @param {object} store - reactive state object
+ */
+export function bindDom(root, store) {
+  const nodes = root.querySelectorAll("[data-bind]");
+
+  nodes.forEach(el => {
+    const pathArr = el.getAttribute("data-bind").split(".");
+    const lastKey = pathArr.pop();
+
+    let target;
+    try {
+      target = resolvePath(store, pathArr); // must be wrapped with state() if nested
+    } catch (err) {
+      console.warn(`Skipping binding for ${el}: ${err.message}`);
+      return;
+    }
+
+    // Subscribe once
+    target.$subscribe(lastKey, val => {
+      if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") el.value = val;
+      else el.textContent = val;
+    });
+
+    // 2-way binding for inputs
+    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
+      el.addEventListener("input", e => target[lastKey] = e.target.value);
+    }
+  });
+}

package/src/core/state.js

@@ -0,0 +1,57 @@
+/**
+ * Lume-JS Reactive State Core
+ *
+ * Provides minimal, zero-runtime reactive state.
+ * 
+ * Features:
+ * - Lightweight and Go-style
+ * - Explicit nested states
+ * - $subscribe for listening to key changes
+ *
+ * Usage:
+ *   import { state } from "lume-js";
+ *   const store = state({ count: 0 });
+ *   store.$subscribe("count", val => console.log(val));
+ */
+
+
+/**
+ * Creates a reactive state object.
+ * 
+ * @param {Object} obj - Initial state object
+ * @returns {Proxy} Reactive proxy with $subscribe method
+ */
+export function state(obj) {
+  const listeners = {};
+
+  // Notify subscribers of a key
+  function notify(key, val) {
+    if (listeners[key]) listeners[key].forEach(fn => fn(val));
+  }
+
+  const proxy = new Proxy(obj, {
+    get(target, key) {
+      return target[key];
+    },
+    set(target, key, value) {
+      target[key] = value;
+      notify(key, value);
+      return true;
+    }
+  });
+
+  /**
+   * Subscribe to changes for a specific key.
+   * Calls the callback immediately with the current value.
+   * 
+   * @param {string} key 
+   * @param {function} fn 
+   */
+  proxy.$subscribe = (key, fn) => {
+    if (!listeners[key]) listeners[key] = [];
+    listeners[key].push(fn);
+    fn(proxy[key]); // initialize
+  };
+
+  return proxy;
+}

package/src/core/utils.js

@@ -0,0 +1,14 @@
+/**
+ * Resolve a nested path in an object.
+ * Example: path "user.name" returns obj.user.name
+ *
+ * @param {object} obj - The root object
+ * @param {string[]} pathArr - Array of keys
+ * @returns {object} Last object in the path
+ */
+export function resolvePath(obj, pathArr) {
+  return pathArr.reduce((acc, key) => {
+    if (!acc) throw new Error(`Invalid path: ${pathArr.join(".")}`);
+    return acc[key];
+  }, obj);
+}

package/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * Lume-JS Library Core API
+ *
+ * Exposes:
+ * - state(): create reactive state
+ * - bindDom(): zero-runtime DOM binding
+ *
+ * Usage:
+ *   import { state, bindDom } from "lume-js";
+ */
+
+export { state } from "./core/state.js";
+export { bindDom } from "./core/bindDom.js";

package/index.js

@@ -1 +0,0 @@
-console.log("hello world!");