lume-js 0.3.0 → 0.4.1

package/src/index.d.ts

@@ -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,5 +103,40 @@ export function state<T extends object>(obj: T): ReactiveState<T>;
  */
 export function bindDom(
   root: HTMLElement,
-  store: ReactiveState<any>
-): Unsubscribe;
+  store: ReactiveState<any>,
+  options?: BindDomOptions
+): 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;
+
+/**
+ * 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

@@ -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 { state, isReactive } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
+export { effect } from "./core/effect.js";