lume-js 2.0.0-beta.2 → 2.0.0

package/src/addons/cleanupGroup.js

@@ -0,0 +1,44 @@
+/**
+ * Creates a cleanup group that can collect and dispose multiple
+ * cleanup/unsubscribe functions at once.
+ *
+ * @returns {CleanupGroup}
+ *
+ * @example
+ * ```js
+ * import { createCleanupGroup } from 'lume-js/addons';
+ *
+ * const group = createCleanupGroup();
+ * group.add(bindDom(root, store));
+ * group.add(effect(() => { ... }));
+ * group.add(store.$subscribe('key', fn));
+ *
+ * // Dispose everything at once
+ * group.dispose();
+ * ```
+ */
+export function createCleanupGroup() {
+  const cleanups = [];
+
+  return {
+    /**
+     * Add a cleanup function to the group.
+     * @param {Function} fn - Cleanup/unsubscribe function
+     */
+    add(fn) {
+      if (typeof fn === 'function') {
+        cleanups.push(fn);
+      }
+    },
+
+    /**
+     * Run all collected cleanup functions and clear the group.
+     */
+    dispose() {
+      while (cleanups.length) {
+        const fn = cleanups.pop();
+        try { fn(); } catch (e) { /* ignore cleanup errors */ }
+      }
+    },
+  };
+}

package/src/addons/hydrateState.js

@@ -0,0 +1,30 @@
+/**
+ * Reads initial state from a `<script type="application/json">` element
+ * embedded in the server-rendered HTML. Useful for SSR / hydration patterns.
+ *
+ * @param {string} [selector='#__LUME_DATA__'] - CSS selector for the script element
+ * @returns {object} Parsed JSON object, or empty object if not found / invalid
+ *
+ * @example
+ * ```html
+ * <script id="__LUME_DATA__" type="application/json">
+ *   {"title": "Welcome", "count": 42}
+ * </script>
+ * ```
+ *
+ * ```js
+ * import { state } from 'lume-js';
+ * import { hydrateState } from 'lume-js/addons';
+ *
+ * const store = state(hydrateState());
+ * ```
+ */
+export function hydrateState(selector = '#__LUME_DATA__') {
+  const el = typeof document !== 'undefined' ? document.querySelector(selector) : null;
+  if (!el) return {};
+  try {
+    return JSON.parse(el.textContent);
+  } catch {
+    return {};
+  }
+}

package/src/addons/index.d.ts

@@ -320,11 +320,11 @@ export interface DebugPlugin {
  * @example
  * ```typescript
  * import { state } from 'lume-js';
- * import { createDebugPlugin } from 'lume-js/addons';
- * 
- * const store = state({ count: 0 }, { 
- *   plugins: [createDebugPlugin({ label: 'counter' })] 
- * });
+ * import { createDebugPlugin, withPlugins } from 'lume-js/addons';
+ *
+ * const store = withPlugins(state({ count: 0 }), [
+ *   createDebugPlugin({ label: 'counter' })
+ * ]);
  * ```
  */
 export function createDebugPlugin(options?: DebugPluginOptions): DebugPlugin;
@@ -434,3 +434,51 @@ export interface Plugin {
  */
 export function withPlugins<T extends object>(store: ReactiveState<T>, plugins: Plugin[]): ReactiveState<T>;
 
+/**
+ * A group that collects cleanup/unsubscribe functions and can dispose them all at once.
+ *
+ * @example
+ * ```typescript
+ * import { createCleanupGroup } from 'lume-js/addons';
+ *
+ * const group = createCleanupGroup();
+ * group.add(bindDom(root, store));
+ * group.add(effect(() => { ... }));
+ * group.add(store.$subscribe('key', fn));
+ *
+ * // Dispose everything at once
+ * group.dispose();
+ * ```
+ */
+export interface CleanupGroup {
+  /** Add a cleanup/unsubscribe function to the group */
+  add(fn: () => void): void;
+  /** Run all collected cleanup functions and clear the group */
+  dispose(): void;
+}
+
+/**
+ * Creates a cleanup group that can collect and dispose multiple
+ * cleanup/unsubscribe functions at once.
+ *
+ * @returns A CleanupGroup instance
+ */
+export function createCleanupGroup(): CleanupGroup;
+
+/**
+ * Reads initial state from a `<script type="application/json">` element
+ * embedded in the server-rendered HTML.
+ *
+ * @param selector - CSS selector for the script element (default: '#__LUME_DATA__')
+ * @returns Parsed JSON object, or empty object if not found or invalid
+ *
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { hydrateState } from 'lume-js/addons';
+ *
+ * const store = state(hydrateState());
+ * ```
+ */
+export function hydrateState(selector?: string): object;
+

package/src/addons/index.js

@@ -3,6 +3,8 @@ export { watch } from "./watch.js";
 export { repeat, defaultFocusPreservation, defaultScrollPreservation } from "./repeat.js";
 export { createDebugPlugin, debug } from "./debug.js";
 export { withPlugins } from "./withPlugins.js";
+export { createCleanupGroup } from "./cleanupGroup.js";
+export { hydrateState } from "./hydrateState.js";
 
 /**
  * Returns true if the value is a Lume reactive proxy created by state().

package/src/addons/repeat.js

@@ -1,6 +1,5 @@
 /**
  * Lume-JS List Rendering (Addon)
- * @experimental
  *
  * Renders lists with automatic subscription and element reuse by key.
  * 

package/src/addons/withPlugins.js

@@ -60,13 +60,22 @@ export function withPlugins(store, plugins = []) {
     pendingNotifications.clear();
   }
 
-  // Register once on the underlying state; hook survives for lifetime of store.
+  // Register once on the underlying state; capture unsubscribe for cleanup.
+  let flushUnsub;
   if (typeof store.$beforeFlush === 'function') {
-    store.$beforeFlush(runNotifyHooks);
+    flushUnsub = store.$beforeFlush(runNotifyHooks);
   }
 
   return new Proxy(store, {
     get(target, key) {
+      // $dispose — remove the beforeFlush hook and clear pending state
+      if (key === '$dispose') {
+        return () => {
+          if (flushUnsub) flushUnsub();
+          pendingNotifications.clear();
+        };
+      }
+
       // Pass $-prefixed meta methods through without interception
       if (typeof key === 'string' && key.startsWith('$')) {
         const method = target[key];

package/src/core/effect.js

@@ -120,8 +120,7 @@ export function effect(fn, deps) {
       // Save previous subscriptions instead of cleaning immediately.
       // If fn() doesn't read any state (early return / error), we restore
       // them so the effect stays reactive.
-      const oldCleanups = [...cleanups];
-      cleanups.length = 0;
+      const oldCleanups = cleanups.splice(0);
 
       // Create effect context for tracking
       const myContext = {

package/src/index.d.ts

@@ -14,6 +14,12 @@ export type Unsubscribe = () => void;
  */
 export type Subscriber<T> = (value: T) => void;
 
+/**
+ * Internal unique symbol for reactive state branding
+ * @internal
+ */
+declare const lumeReactiveSymbol: unique symbol;
+
 /**
  * Plugin interface for extending state behavior
  * 
@@ -147,7 +153,7 @@ export type ReactiveState<T extends object> = T & {
    * Brand to identify reactive state objects at the type level
    * @internal
    */
-  readonly [Symbol('lume.reactive')]?: true;
+  readonly [lumeReactiveSymbol]?: true;
 };
 
 /**
@@ -347,6 +353,28 @@ export function effect(fn: () => void): Unsubscribe;
  */
 export function effect(fn: () => void, deps: EffectDependency[]): Unsubscribe;
 
+/**
+ * Run a function with a read observer active.
+ *
+ * The observer receives `(proxy, key, registerEffect)` for every property read
+ * during the synchronous execution of `fn`. Used internally by `effect()` for
+ * auto-tracking, and exposed for building custom reactive primitives.
+ *
+ * @param onRead - Called on each property access inside fn
+ * @param fn - The function to run under observation
+ * @returns The return value of fn
+ *
+ * @internal
+ */
+export function withReadObserver<T>(
+  onRead: (
+    proxy: ReactiveState<any>,
+    key: string,
+    registerEffect: (key: string, executeFn: () => void) => () => void
+  ) => void,
+  fn: () => T
+): T;
+
 
 // ============================================================================
 // Utility Types

package/src/index.js

@@ -5,11 +5,12 @@
  * - state(): create reactive state
  * - bindDom(): zero-runtime DOM binding
  * - effect(): reactive effect with automatic dependency tracking
+ * - withReadObserver(): advanced API for custom reactive primitives
  *
  * Usage:
  *   import { state, bindDom, effect } from "lume-js";
  */
 
-export { state } from "./core/state.js";
+export { state, withReadObserver } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
 export { effect } from "./core/effect.js";