lume-js 0.2.1 → 0.4.0

package/src/core/utils.js

@@ -1,14 +1,41 @@
+/**
+ * Utility functions for Lume.js
+ */
+
 /**
  * Resolve a nested path in an object.
- * Example: path "user.name" returns obj.user.name
+ * Example: resolvePath(obj, ['user', 'address']) returns obj.user.address
  *
  * @param {object} obj - The root object
  * @param {string[]} pathArr - Array of keys
  * @returns {object} Last object in the path
+ * @throws {Error} If path is invalid or doesn't exist
  */
 export function resolvePath(obj, pathArr) {
-  return pathArr.reduce((acc, key) => {
-    if (!acc) throw new Error(`Invalid path: ${pathArr.join(".")}`);
-    return acc[key];
-  }, obj);
-}
+  // If no path, return the object itself
+  if (!pathArr || pathArr.length === 0) {
+    return obj;
+  }
+
+  let current = obj;
+  
+  for (let i = 0; i < pathArr.length; i++) {
+    const key = pathArr[i];
+    
+    if (current === null || current === undefined) {
+      throw new Error(
+        `Cannot access property "${key}" of ${current} at path: ${pathArr.slice(0, i + 1).join('.')}`
+      );
+    }
+    
+    if (!(key in current)) {
+      throw new Error(
+        `Property "${key}" does not exist at path: ${pathArr.slice(0, i + 1).join('.')}`
+      );
+    }
+    
+    current = current[key];
+  }
+  
+  return current;
+}

package/src/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Lume.js TypeScript Definitions
+ * 
+ * Provides type safety for reactive state management
+ */
+
+/**
+ * Unsubscribe function returned by $subscribe
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Subscriber callback function
+ */
+export type Subscriber<T> = (value: T) => void;
+
+/**
+ * Reactive state object with $subscribe method
+ */
+export type ReactiveState<T extends object> = T & {
+  /**
+   * Subscribe to changes on a specific property key
+   * @param key - Property key to watch
+   * @param callback - Function called when property changes
+   * @returns Unsubscribe function for cleanup
+   */
+  $subscribe<K extends keyof T>(
+    key: K,
+    callback: Subscriber<T[K]>
+  ): Unsubscribe;
+};
+
+/**
+ * Create a reactive state object
+ * 
+ * @param obj - Plain object to make reactive
+ * @returns Reactive proxy with $subscribe method
+ * @throws {Error} If obj is not a plain object
+ * 
+ * @example
+ * ```typescript
+ * const store = state({
+ *   count: 0,
+ *   user: state({
+ *     name: 'Alice'
+ *   })
+ * });
+ * 
+ * store.count++; // Triggers reactivity
+ * 
+ * const unsub = store.$subscribe('count', (val) => {
+ *   console.log('Count:', val);
+ * });
+ * 
+ * // Cleanup
+ * unsub();
+ * ```
+ */
+export function state<T extends object>(obj: T): ReactiveState<T>;
+
+/**
+ * Bind reactive state to DOM elements
+ * 
+ * @param root - Root element to scan for [data-bind] attributes
+ * @param store - Reactive state object
+ * @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
+ * const store = state({ count: 0 });
+ * const cleanup = bindDom(document.body, store);
+ * 
+ * // Later: cleanup all bindings
+ * cleanup();
+ * ```
+ * 
+ * HTML:
+ * ```html
+ * <span data-bind="count"></span>
+ * <input data-bind="name">
+ * ```
+ */
+export function bindDom(
+  root: HTMLElement,
+  store: ReactiveState<any>
+): Unsubscribe;
+
+/**
+ * Create an effect that automatically tracks dependencies
+ * 
+ * The effect runs immediately and re-runs when any accessed state properties change.
+ * Only tracks properties that are actually accessed during execution.
+ * 
+ * @param fn - Function to run reactively
+ * @returns Cleanup function to stop the effect
+ * @throws {Error} If fn is not a function
+ * 
+ * @example
+ * ```typescript
+ * const store = state({ count: 0, name: 'Alice' });
+ * 
+ * const cleanup = effect(() => {
+ *   // Only tracks 'count' (name 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
+ * ```
+ */
+export function effect(fn: () => void): Unsubscribe;

package/src/index.js

@@ -4,10 +4,12 @@
  * Exposes:
  * - state(): create reactive state
  * - bindDom(): zero-runtime DOM binding
+ * - effect(): reactive effect with automatic dependency tracking
  *
  * Usage:
- *   import { state, bindDom } from "lume-js";
+ *   import { state, bindDom, effect } from "lume-js";
  */
 
 export { state } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
+export { effect } from "./core/effect.js";