pulse-js-framework 1.4.4 → 1.4.6

package/runtime/pulse.js

@@ -1,36 +1,195 @@
 /**
  * Pulse - Reactive Primitives
+ * @module pulse-js-framework/runtime/pulse
  *
  * The core reactivity system based on "pulsations" -
  * reactive values that propagate changes through the system.
+ *
+ * @example
+ * import { pulse, effect, computed } from './pulse.js';
+ *
+ * const count = pulse(0);
+ * const doubled = computed(() => count.get() * 2);
+ *
+ * effect(() => {
+ *   console.log('Count:', count.get(), 'Doubled:', doubled.get());
+ * });
+ *
+ * count.set(5); // Logs: Count: 5 Doubled: 10
+ */
+
+import { loggers } from './logger.js';
+
+const log = loggers.pulse;
+
+/**
+ * @typedef {Object} ReactiveContext
+ * @property {EffectFn|null} currentEffect - Currently executing effect for dependency tracking
+ * @property {number} batchDepth - Nesting depth of batch() calls
+ * @property {Set<EffectFn>} pendingEffects - Effects queued during batch
+ * @property {boolean} isRunningEffects - Flag to prevent recursive effect flushing
+ * @property {string|null} currentModuleId - Current module ID for HMR effect tracking
+ * @property {Map<string, Set<EffectFn>>} effectRegistry - Module ID to effects mapping for HMR
+ */
+
+/**
+ * Global reactive context - holds all tracking state.
+ * Exported for testing purposes (use resetContext() to reset).
+ * @type {ReactiveContext}
+ */
+export const context = {
+  currentEffect: null,
+  batchDepth: 0,
+  pendingEffects: new Set(),
+  isRunningEffects: false,
+  // HMR support
+  currentModuleId: null,
+  effectRegistry: new Map()
+};
+
+/**
+ * Reset the reactive context to initial state.
+ * Use this in tests to ensure isolation between test cases.
+ * @returns {void}
+ * @example
+ * // In test setup/teardown
+ * import { resetContext } from 'pulse-js-framework/runtime/pulse';
+ * beforeEach(() => resetContext());
+ */
+export function resetContext() {
+  context.currentEffect = null;
+  context.batchDepth = 0;
+  context.pendingEffects.clear();
+  context.isRunningEffects = false;
+  context.currentModuleId = null;
+  context.effectRegistry.clear();
+}
+
+/**
+ * Set the current module ID for HMR effect tracking.
+ * Effects created while a module ID is set will be registered for cleanup.
+ * @param {string} moduleId - The module identifier (typically import.meta.url)
+ * @returns {void}
+ */
+export function setCurrentModule(moduleId) {
+  context.currentModuleId = moduleId;
+}
+
+/**
+ * Clear the current module ID after module initialization.
+ * @returns {void}
+ */
+export function clearCurrentModule() {
+  context.currentModuleId = null;
+}
+
+/**
+ * Dispose all effects associated with a module.
+ * Called during HMR to clean up before re-executing the module.
+ * @param {string} moduleId - The module identifier to dispose
+ * @returns {void}
+ */
+export function disposeModule(moduleId) {
+  const effects = context.effectRegistry.get(moduleId);
+  if (effects) {
+    for (const effectFn of effects) {
+      // Run cleanup functions
+      for (const cleanup of effectFn.cleanups) {
+        try {
+          cleanup();
+        } catch (e) {
+          log.error('HMR cleanup error:', e);
+        }
+      }
+      effectFn.cleanups = [];
+
+      // Unsubscribe from all dependencies
+      for (const dep of effectFn.dependencies) {
+        dep._unsubscribe(effectFn);
+      }
+      effectFn.dependencies.clear();
+    }
+    context.effectRegistry.delete(moduleId);
+  }
+}
+
+/**
+ * @typedef {Object} EffectFn
+ * @property {Function} run - The effect function to execute
+ * @property {Set<Pulse>} dependencies - Set of pulse dependencies
+ * @property {Array<Function>} cleanups - Cleanup functions to run
+ */
+
+/**
+ * @typedef {Object} PulseOptions
+ * @property {function(*, *): boolean} [equals] - Custom equality function (default: Object.is)
+ */
+
+/**
+ * @typedef {Object} ComputedOptions
+ * @property {boolean} [lazy=false] - If true, only compute when value is read
+ */
+
+/**
+ * @typedef {Object} MemoOptions
+ * @property {function(*, *): boolean} [equals] - Custom equality function for args comparison
  */
 
-// Current tracking context for automatic dependency collection
-let currentEffect = null;
-let batchDepth = 0;
-let pendingEffects = new Set();
-let isRunningEffects = false;
-let cleanupQueue = [];
+/**
+ * @typedef {Object} MemoComputedOptions
+ * @property {Array<Pulse|Function>} [deps] - Dependencies to watch for changes
+ * @property {function(*, *): boolean} [equals] - Custom equality function
+ */
 
 /**
- * Register a cleanup function for the current effect
- * Called when the effect re-runs or is disposed
+ * @typedef {Object} ReactiveState
+ * @property {Object.<string, Pulse>} $pulses - Access to underlying pulse objects
+ * @property {function(string): Pulse} $pulse - Get pulse by key
+ */
+
+/**
+ * @typedef {Object} PromiseState
+ * @property {Pulse<T>} value - The resolved value
+ * @property {Pulse<boolean>} loading - Loading state
+ * @property {Pulse<Error|null>} error - Error state
+ * @template T
+ */
+
+/**
+ * Register a cleanup function for the current effect.
+ * Called when the effect re-runs or is disposed.
+ * @param {Function} fn - Cleanup function to register
+ * @returns {void}
+ * @example
+ * effect(() => {
+ *   const timer = setInterval(() => console.log('tick'), 1000);
+ *   onCleanup(() => clearInterval(timer));
+ * });
  */
 export function onCleanup(fn) {
-  if (currentEffect) {
-    currentEffect.cleanups.push(fn);
+  if (context.currentEffect) {
+    context.currentEffect.cleanups.push(fn);
   }
 }
 
 /**
- * Pulse - A reactive value container
- * When the value changes, it "pulses" to all its dependents
+ * Pulse - A reactive value container.
+ * When the value changes, it "pulses" to all its dependents.
+ * @template T
  */
 export class Pulse {
+  /** @type {T} */
   #value;
+  /** @type {Set<EffectFn>} */
   #subscribers = new Set();
+  /** @type {function(T, T): boolean} */
   #equals;
 
+  /**
+   * Create a new Pulse with an initial value
+   * @param {T} value - The initial value
+   * @param {PulseOptions} [options={}] - Configuration options
+   */
   constructor(value, options = {}) {
     this.#value = value;
     this.#equals = options.equals ?? Object.is;
@@ -38,17 +197,28 @@ export class Pulse {
 
   /**
    * Get the current value and track dependency if in an effect context
+   * @returns {T} The current value
+   * @example
+   * const name = pulse('Alice');
+   * effect(() => {
+   *   console.log(name.get()); // Tracks dependency automatically
+   * });
    */
   get() {
-    if (currentEffect) {
-      this.#subscribers.add(currentEffect);
-      currentEffect.dependencies.add(this);
+    if (context.currentEffect) {
+      this.#subscribers.add(context.currentEffect);
+      context.currentEffect.dependencies.add(this);
     }
     return this.#value;
   }
 
   /**
    * Set a new value and notify all subscribers
+   * @param {T} newValue - The new value to set
+   * @returns {void}
+   * @example
+   * const count = pulse(0);
+   * count.set(5);
    */
   set(newValue) {
     if (this.#equals(this.#value, newValue)) return;
@@ -58,13 +228,25 @@ export class Pulse {
 
   /**
    * Update value using a function
+   * @param {function(T): T} fn - Update function receiving current value
+   * @returns {void}
+   * @example
+   * const count = pulse(0);
+   * count.update(n => n + 1); // Increment
    */
   update(fn) {
     this.set(fn(this.#value));
   }
 
   /**
-   * Subscribe to changes
+   * Subscribe to value changes
+   * @param {function(T): void} fn - Callback invoked on each change
+   * @returns {function(): void} Unsubscribe function
+   * @example
+   * const count = pulse(0);
+   * const unsub = count.subscribe(value => console.log(value));
+   * count.set(1); // Logs: 1
+   * unsub(); // Stop listening
    */
   subscribe(fn) {
     const subscriber = { run: fn, dependencies: new Set() };
@@ -74,6 +256,13 @@ export class Pulse {
 
   /**
    * Create a derived pulse that recomputes when this changes
+   * @template U
+   * @param {function(T): U} fn - Derivation function
+   * @returns {Pulse<U>} A new computed pulse
+   * @example
+   * const count = pulse(5);
+   * const doubled = count.derive(n => n * 2);
+   * doubled.get(); // 10
    */
   derive(fn) {
     return computed(() => fn(this.get()));
@@ -81,14 +270,16 @@ export class Pulse {
 
   /**
    * Notify all subscribers of a change
+   * @private
+   * @returns {void}
    */
   #notify() {
     // Copy subscribers to avoid mutation during iteration
     const subs = [...this.#subscribers];
 
     for (const subscriber of subs) {
-      if (batchDepth > 0 || isRunningEffects) {
-        pendingEffects.add(subscriber);
+      if (context.batchDepth > 0 || context.isRunningEffects) {
+        context.pendingEffects.add(subscriber);
       } else {
         runEffect(subscriber);
       }
@@ -96,7 +287,10 @@ export class Pulse {
   }
 
   /**
-   * Unsubscribe a specific subscriber
+   * Unsubscribe a specific subscriber (internal use)
+   * @param {EffectFn} subscriber - The subscriber to remove
+   * @returns {void}
+   * @internal
    */
   _unsubscribe(subscriber) {
     this.#subscribers.delete(subscriber);
@@ -104,6 +298,10 @@ export class Pulse {
 
   /**
    * Get value without tracking (for debugging/inspection)
+   * @returns {T} The current value without tracking dependency
+   * @example
+   * const count = pulse(5);
+   * count.peek(); // 5, no dependency tracked
    */
   peek() {
     return this.#value;
@@ -111,6 +309,9 @@ export class Pulse {
 
   /**
    * Initialize value without triggering notifications (internal use)
+   * @param {T} value - The value to set
+   * @returns {void}
+   * @internal
    */
   _init(value) {
     this.#value = value;
@@ -118,6 +319,9 @@ export class Pulse {
 
   /**
    * Set from computed - propagates to subscribers (internal use)
+   * @param {T} newValue - The new value
+   * @returns {void}
+   * @internal
    */
   _setFromComputed(newValue) {
     if (this.#equals(this.#value, newValue)) return;
@@ -127,6 +331,9 @@ export class Pulse {
 
   /**
    * Add a subscriber directly (internal use)
+   * @param {EffectFn} subscriber - The subscriber to add
+   * @returns {void}
+   * @internal
    */
   _addSubscriber(subscriber) {
     this.#subscribers.add(subscriber);
@@ -134,6 +341,8 @@ export class Pulse {
 
   /**
    * Trigger notification to all subscribers (internal use)
+   * @returns {void}
+   * @internal
    */
   _triggerNotify() {
     this.#notify();
@@ -142,6 +351,9 @@ export class Pulse {
 
 /**
  * Run a single effect safely
+ * @private
+ * @param {EffectFn} effectFn - The effect to run
+ * @returns {void}
  */
 function runEffect(effectFn) {
   if (!effectFn || !effectFn.run) return;
@@ -149,25 +361,27 @@ function runEffect(effectFn) {
   try {
     effectFn.run();
   } catch (error) {
-    console.error('Effect error:', error);
+    log.error('Effect error:', error);
   }
 }
 
 /**
  * Flush all pending effects
+ * @private
+ * @returns {void}
  */
 function flushEffects() {
-  if (isRunningEffects) return;
+  if (context.isRunningEffects) return;
 
-  isRunningEffects = true;
+  context.isRunningEffects = true;
   let iterations = 0;
   const maxIterations = 100; // Prevent infinite loops
 
   try {
-    while (pendingEffects.size > 0 && iterations < maxIterations) {
+    while (context.pendingEffects.size > 0 && iterations < maxIterations) {
       iterations++;
-      const effects = [...pendingEffects];
-      pendingEffects.clear();
+      const effects = [...context.pendingEffects];
+      context.pendingEffects.clear();
 
       for (const effect of effects) {
         runEffect(effect);
@@ -175,24 +389,48 @@ function flushEffects() {
     }
 
     if (iterations >= maxIterations) {
-      console.warn('Pulse: Maximum effect iterations reached. Possible infinite loop.');
-      pendingEffects.clear();
+      log.warn('Maximum effect iterations reached. Possible infinite loop.');
+      context.pendingEffects.clear();
     }
   } finally {
-    isRunningEffects = false;
+    context.isRunningEffects = false;
   }
 }
 
 /**
- * Create a simple pulse with an initial value
+ * Create a reactive pulse with an initial value
+ * @template T
+ * @param {T} value - The initial value
+ * @param {PulseOptions} [options] - Configuration options
+ * @returns {Pulse<T>} A new Pulse instance
+ * @example
+ * const count = pulse(0);
+ * const user = pulse({ name: 'Alice' });
+ *
+ * // With custom equality
+ * const data = pulse(obj, { equals: (a, b) => a.id === b.id });
  */
 export function pulse(value, options) {
   return new Pulse(value, options);
 }
 
 /**
- * Create a computed pulse that automatically updates
- * when its dependencies change
+ * Create a computed pulse that automatically updates when its dependencies change
+ * @template T
+ * @param {function(): T} fn - Computation function
+ * @param {ComputedOptions} [options={}] - Configuration options
+ * @returns {Pulse<T>} A read-only Pulse that updates automatically
+ * @example
+ * const firstName = pulse('John');
+ * const lastName = pulse('Doe');
+ * const fullName = computed(() => `${firstName.get()} ${lastName.get()}`);
+ *
+ * fullName.get(); // 'John Doe'
+ * firstName.set('Jane');
+ * fullName.get(); // 'Jane Doe'
+ *
+ * // Lazy computation (only runs when read)
+ * const expensive = computed(() => heavyCalculation(), { lazy: true });
  */
 export function computed(fn, options = {}) {
   const { lazy = false } = options;
@@ -212,13 +450,13 @@ export function computed(fn, options = {}) {
     p.get = function() {
       if (dirty) {
         // Run computation
-        const prevEffect = currentEffect;
+        const prevEffect = context.currentEffect;
         const tempEffect = {
           run: () => {},
           dependencies: new Set(),
           cleanups: []
         };
-        currentEffect = tempEffect;
+        context.currentEffect = tempEffect;
 
         try {
           cachedValue = fn();
@@ -241,14 +479,14 @@ export function computed(fn, options = {}) {
 
           p._init(cachedValue);
         } finally {
-          currentEffect = prevEffect;
+          context.currentEffect = prevEffect;
         }
       }
 
       // Track dependency on this computed
-      if (currentEffect) {
-        p._addSubscriber(currentEffect);
-        currentEffect.dependencies.add(p);
+      if (context.currentEffect) {
+        p._addSubscriber(context.currentEffect);
+        context.currentEffect.dependencies.add(p);
       }
 
       return cachedValue;
@@ -288,8 +526,29 @@ export function computed(fn, options = {}) {
 
 /**
  * Create an effect that runs when its dependencies change
+ * @param {function(): void|function(): void} fn - Effect function, may return a cleanup function
+ * @returns {function(): void} Dispose function to stop the effect
+ * @example
+ * const count = pulse(0);
+ *
+ * // Basic effect
+ * const dispose = effect(() => {
+ *   console.log('Count is:', count.get());
+ * });
+ *
+ * count.set(1); // Logs: Count is: 1
+ * dispose(); // Stop listening
+ *
+ * // With cleanup
+ * effect(() => {
+ *   const timer = setInterval(() => tick(), 1000);
+ *   return () => clearInterval(timer); // Cleanup on re-run or dispose
+ * });
  */
 export function effect(fn) {
+  // Capture module ID at creation time for HMR tracking
+  const moduleId = context.currentModuleId;
+
   const effectFn = {
     run: () => {
       // Run cleanup functions from previous run
@@ -297,7 +556,7 @@ export function effect(fn) {
         try {
           cleanup();
         } catch (e) {
-          console.error('Cleanup error:', e);
+          log.error('Cleanup error:', e);
         }
       }
       effectFn.cleanups = [];
@@ -309,21 +568,29 @@ export function effect(fn) {
       effectFn.dependencies.clear();
 
       // Set as current effect for dependency tracking
-      const prevEffect = currentEffect;
-      currentEffect = effectFn;
+      const prevEffect = context.currentEffect;
+      context.currentEffect = effectFn;
 
       try {
         fn();
       } catch (error) {
-        console.error('Effect execution error:', error);
+        log.error('Effect execution error:', error);
       } finally {
-        currentEffect = prevEffect;
+        context.currentEffect = prevEffect;
       }
     },
     dependencies: new Set(),
     cleanups: []
   };
 
+  // HMR: Register effect with current module
+  if (moduleId) {
+    if (!context.effectRegistry.has(moduleId)) {
+      context.effectRegistry.set(moduleId, new Set());
+    }
+    context.effectRegistry.get(moduleId).add(effectFn);
+  }
+
   // Run immediately to collect dependencies
   effectFn.run();
 
@@ -334,7 +601,7 @@ export function effect(fn) {
       try {
         cleanup();
       } catch (e) {
-        console.error('Cleanup error:', e);
+        log.error('Cleanup error:', e);
       }
     }
     effectFn.cleanups = [];
@@ -343,28 +610,69 @@ export function effect(fn) {
       dep._unsubscribe(effectFn);
     }
     effectFn.dependencies.clear();
+
+    // HMR: Remove from registry
+    if (moduleId && context.effectRegistry.has(moduleId)) {
+      context.effectRegistry.get(moduleId).delete(effectFn);
+    }
   };
 }
 
 /**
- * Batch multiple updates into one
- * Effects only run after all updates complete
+ * Batch multiple updates into one. Effects only run after all updates complete.
+ * @template T
+ * @param {function(): T} fn - Function containing multiple updates
+ * @returns {T} The return value of fn
+ * @example
+ * const x = pulse(0);
+ * const y = pulse(0);
+ *
+ * effect(() => console.log(x.get(), y.get()));
+ *
+ * // Without batch: logs twice
+ * x.set(1);
+ * y.set(1);
+ *
+ * // With batch: logs once
+ * batch(() => {
+ *   x.set(2);
+ *   y.set(2);
+ * });
  */
 export function batch(fn) {
-  batchDepth++;
+  context.batchDepth++;
   try {
-    fn();
+    return fn();
   } finally {
-    batchDepth--;
-    if (batchDepth === 0) {
+    context.batchDepth--;
+    if (context.batchDepth === 0) {
       flushEffects();
     }
   }
 }
 
 /**
- * Create a reactive state object from a plain object
- * Each property becomes a pulse
+ * Create a reactive state object from a plain object.
+ * Each property becomes a pulse with getters/setters.
+ * @template T
+ * @param {T} obj - Plain object with initial values
+ * @returns {T & ReactiveState} Reactive state object
+ * @example
+ * const state = createState({
+ *   count: 0,
+ *   items: ['a', 'b']
+ * });
+ *
+ * // Use as regular properties
+ * state.count = 5;
+ * console.log(state.count); // 5
+ *
+ * // Array helpers
+ * state.items$push('c');
+ * state.items$filter(item => item !== 'a');
+ *
+ * // Access underlying pulses
+ * state.$pulse('count').subscribe(v => console.log(v));
  */
 export function createState(obj) {
   const state = {};
@@ -454,8 +762,21 @@ export function createState(obj) {
 }
 
 /**
- * Memoize a function based on reactive dependencies
- * Only recomputes when dependencies change
+ * Memoize a function based on its arguments.
+ * Only recomputes when arguments change.
+ * @template {function} T
+ * @param {T} fn - Function to memoize
+ * @param {MemoOptions} [options={}] - Configuration options
+ * @returns {T} Memoized function
+ * @example
+ * const expensiveCalc = memo((x, y) => {
+ *   console.log('Computing...');
+ *   return x * y;
+ * });
+ *
+ * expensiveCalc(2, 3); // Logs: Computing... Returns: 6
+ * expensiveCalc(2, 3); // Returns: 6 (cached, no log)
+ * expensiveCalc(3, 4); // Logs: Computing... Returns: 12
  */
 export function memo(fn, options = {}) {
   const { equals = Object.is } = options;
@@ -480,8 +801,20 @@ export function memo(fn, options = {}) {
 }
 
 /**
- * Create a memoized computed value
- * Combines memo with computed for expensive derivations
+ * Create a memoized computed value.
+ * Combines memo with computed for expensive derivations.
+ * @template T
+ * @param {function(): T} fn - Computation function
+ * @param {MemoComputedOptions} [options={}] - Configuration options
+ * @returns {Pulse<T>} A computed pulse that only recalculates when deps change
+ * @example
+ * const items = pulse([1, 2, 3, 4, 5]);
+ * const filter = pulse('');
+ *
+ * const filtered = memoComputed(
+ *   () => items.get().filter(i => String(i).includes(filter.get())),
+ *   { deps: [items, filter] }
+ * );
  */
 export function memoComputed(fn, options = {}) {
   const { deps = [], equals = Object.is } = options;
@@ -505,7 +838,26 @@ export function memoComputed(fn, options = {}) {
 }
 
 /**
- * Watch specific pulses and run a callback when they change
+ * Watch specific pulses and run a callback when they change.
+ * Unlike effect, provides both new and old values.
+ * @template T
+ * @param {Pulse<T>|Array<Pulse<T>>} sources - Pulse(s) to watch
+ * @param {function(Array<T>, Array<T>): void} callback - Called with (newValues, oldValues)
+ * @returns {function(): void} Dispose function to stop watching
+ * @example
+ * const count = pulse(0);
+ *
+ * const stop = watch(count, ([newVal], [oldVal]) => {
+ *   console.log(`Changed from ${oldVal} to ${newVal}`);
+ * });
+ *
+ * count.set(1); // Logs: Changed from 0 to 1
+ * stop();
+ *
+ * // Watch multiple
+ * watch([a, b], ([newA, newB], [oldA, oldB]) => {
+ *   console.log('Values changed');
+ * });
  */
 export function watch(sources, callback) {
   const sourcesArray = Array.isArray(sources) ? sources : [sources];
@@ -520,7 +872,22 @@ export function watch(sources, callback) {
 }
 
 /**
- * Create a pulse from a promise
+ * Create pulses from a promise, tracking loading and error states.
+ * @template T
+ * @param {Promise<T>} promise - The promise to track
+ * @param {T} [initialValue=undefined] - Initial value while loading
+ * @returns {PromiseState<T>} Object with value, loading, and error pulses
+ * @example
+ * const { value, loading, error } = fromPromise(
+ *   fetch('/api/data').then(r => r.json()),
+ *   [] // Initial value
+ * );
+ *
+ * effect(() => {
+ *   if (loading.get()) return console.log('Loading...');
+ *   if (error.get()) return console.log('Error:', error.get());
+ *   console.log('Data:', value.get());
+ * });
  */
 export function fromPromise(promise, initialValue = undefined) {
   const p = pulse(initialValue);
@@ -545,15 +912,26 @@ export function fromPromise(promise, initialValue = undefined) {
 }
 
 /**
- * Untrack - read pulses without creating dependencies
+ * Execute a function without tracking any pulse dependencies.
+ * Useful for reading values without creating subscriptions.
+ * @template T
+ * @param {function(): T} fn - Function to execute untracked
+ * @returns {T} The return value of fn
+ * @example
+ * effect(() => {
+ *   const a = aSignal.get(); // Tracked
+ *   const b = untrack(() => bSignal.get()); // Not tracked
+ *   console.log(a, b);
+ * });
+ * // Effect only re-runs when aSignal changes, not bSignal
  */
 export function untrack(fn) {
-  const prevEffect = currentEffect;
-  currentEffect = null;
+  const prevEffect = context.currentEffect;
+  context.currentEffect = null;
   try {
     return fn();
   } finally {
-    currentEffect = prevEffect;
+    context.currentEffect = prevEffect;
   }
 }
 
@@ -569,5 +947,11 @@ export default {
   untrack,
   onCleanup,
   memo,
-  memoComputed
+  memoComputed,
+  context,
+  resetContext,
+  // HMR support
+  setCurrentModule,
+  clearCurrentModule,
+  disposeModule
 };