elementdrawing 1.0.0

package/src/jsx/hooks/useMemo.js

@@ -0,0 +1,689 @@
+/**
+ * useMemo Hook Implementation
+ * ElementDrawing Framework - Value memoization with dependency comparison,
+ * cache invalidation, LRU caching, deep comparison, TTL, and profiling.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+const memoCache = new WeakMap();
+
+// ─── Memo Profiling ───────────────────────────────────────────────────────────
+
+const memoProfiles = new WeakMap();
+let memoProfilingEnabled = false;
+
+/**
+ * Enable or disable memo profiling.
+ * @param {boolean} enabled
+ */
+function setMemoProfiling(enabled) {
+  memoProfilingEnabled = enabled;
+}
+
+/**
+ * Get profiling data for a component's memo hooks.
+ * @param {Object} component
+ * @returns {Object|null}
+ */
+function getMemoProfile(component) {
+  return memoProfiles.get(component) || null;
+}
+
+// ─── LRU Cache ────────────────────────────────────────────────────────────────
+
+/**
+ * Simple LRU cache for memo values.
+ * @param {number} capacity - Maximum cache entries
+ */
+class LRUMemoCache {
+  constructor(capacity) {
+    this.capacity = capacity || 10;
+    this.cache = new Map();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  get(key) {
+    if (!this.cache.has(key)) {
+      this.misses++;
+      return undefined;
+    }
+    // Move to end (most recently used)
+    const value = this.cache.get(key);
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    this.hits++;
+    return value;
+  }
+
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.capacity) {
+      // Delete least recently used (first entry)
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  clear() {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  getStats() {
+    return {
+      size: this.cache.size,
+      capacity: this.capacity,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: this.hits + this.misses > 0 ? this.hits / (this.hits + this.misses) : 0,
+    };
+  }
+}
+
+// ─── Dependency Comparison ────────────────────────────────────────────────────
+
+/**
+ * Compare two dependency arrays for shallow equality.
+ * @param {Array|null} prevDeps
+ * @param {Array|null} nextDeps
+ * @returns {boolean}
+ */
+function areDepsEqual(prevDeps, nextDeps) {
+  if (prevDeps === null || nextDeps === null) return false;
+  if (prevDeps.length !== nextDeps.length) return false;
+  for (let i = 0; i < prevDeps.length; i++) {
+    if (Object.is(prevDeps[i], nextDeps[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Deep dependency comparison.
+ */
+function areDepsDeepEqual(prevDeps, nextDeps) {
+  if (prevDeps === null || nextDeps === null) return false;
+  if (prevDeps.length !== nextDeps.length) return false;
+  for (let i = 0; i < prevDeps.length; i++) {
+    if (deepEqualVal(prevDeps[i], nextDeps[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+function deepEqualVal(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!deepEqualVal(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Validate dependency array.
+ * @param {*} deps
+ */
+function validateDeps(deps) {
+  if (deps !== undefined && !Array.isArray(deps)) {
+    throw new Error(
+      '[useMemo] Dependencies must be an array or undefined. ' +
+      `Received: ${typeof deps}`
+    );
+  }
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+// ─── useMemo Hook ──────────────────────────────────────────────────────────────
+
+/**
+ * useMemo - Memoize a computed value based on dependencies.
+ * Only recomputes when dependencies change.
+ *
+ * @param {Function} factory - Function that returns the memoized value
+ * @param {Array} deps - Dependency array; value recomputes when deps change
+ * @returns {*} Memoized value
+ *
+ * @example
+ * const expensiveValue = useMemo(() => computeExpensive(a, b), [a, b]);
+ *
+ * @example
+ * const sortedList = useMemo(() => {
+ *   return items.sort((a, b) => a.name.localeCompare(b.name));
+ * }, [items]);
+ */
+function useMemo(factory, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMemo] Must be called within a component render phase');
+  }
+
+  if (typeof factory !== 'function') {
+    throw new Error(
+      '[useMemo] First argument must be a function. ' +
+      `Received: ${typeof factory}`
+    );
+  }
+
+  validateDeps(deps);
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: check if dependencies changed
+    hook = component._hooks[currentHookIndex];
+
+    const prevDeps = hook.deps;
+    const depsChanged = !areDepsEqual(prevDeps, resolvedDeps);
+
+    if (depsChanged) {
+      // Dependencies changed - recompute the value
+      hook.deps = resolvedDeps;
+
+      try {
+        const prevValue = hook.value;
+        hook.value = factory();
+        hook._computeCount++;
+
+        // Track value change for debugging
+        if (!Object.is(prevValue, hook.value)) {
+          hook._valueChangedCount++;
+        }
+      } catch (error) {
+        console.error('[useMemo] Factory function error:', error);
+        if (component._handleError) {
+          component._handleError(error);
+        }
+        // Keep previous value on error
+      }
+    }
+    // If deps unchanged, keep the existing memoized value
+  } else {
+    // First render: compute initial value
+    let initialValue;
+    try {
+      initialValue = factory();
+    } catch (error) {
+      console.error('[useMemo] Factory function error on mount:', error);
+      if (component._handleError) {
+        component._handleError(error);
+      }
+      initialValue = undefined;
+    }
+
+    hook = {
+      type: 'memo',
+      value: initialValue,
+      deps: resolvedDeps,
+      _computeCount: 1,
+      _valueChangedCount: 1,
+      _createdAt: Date.now(),
+      _lastComputedAt: Date.now(),
+      _onInvalidate: null,
+      _lruCache: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+
+    // Register in the global memo cache for invalidation support
+    if (!memoCache.has(component)) {
+      memoCache.set(component, new Set());
+    }
+    memoCache.get(component).add(currentHookIndex);
+  }
+
+  // Update profiling data
+  if (memoProfilingEnabled) {
+    if (!memoProfiles.has(component)) {
+      memoProfiles.set(component, {});
+    }
+    const profile = memoProfiles.get(component);
+    profile[currentHookIndex] = {
+      computeCount: hook._computeCount,
+      valueChangedCount: hook._valueChangedCount,
+      lastComputedAt: hook._lastComputedAt,
+    };
+  }
+
+  hookIndex++;
+  return hook.value;
+}
+
+// ─── Cache Invalidation ───────────────────────────────────────────────────────
+
+/**
+ * Invalidate a specific memoized value, forcing recomputation on next render.
+ *
+ * @param {Object} component - The component owning the memo
+ * @param {number} hookIdx - The hook index to invalidate
+ */
+function invalidateMemo(component, hookIdx) {
+  if (!component._hooks) return;
+  const hook = component._hooks[hookIdx];
+  if (!hook || hook.type !== 'memo') return;
+
+  // Clear deps to force recomputation
+  hook.deps = null;
+
+  // Call invalidation callback if registered
+  if (typeof hook._onInvalidate === 'function') {
+    try {
+      hook._onInvalidate(hook.value);
+    } catch (error) {
+      console.error('[useMemo] Invalidation callback error:', error);
+    }
+  }
+}
+
+/**
+ * Invalidate all memoized values for a component.
+ * @param {Object} component
+ */
+function invalidateAllMemos(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook, idx) => {
+    if (hook && hook.type === 'memo') {
+      invalidateMemo(component, idx);
+    }
+  });
+}
+
+/**
+ * Register a callback to be called when a memoized value is invalidated.
+ * Must be called during the same render as the useMemo.
+ *
+ * @param {Function} callback - Called with (oldValue) when invalidated
+ */
+function useMemoOnInvalidate(callback) {
+  const component = currentlyRenderingComponent;
+  if (!component) return;
+
+  // Attach to the previous memo hook
+  const prevHookIdx = hookIndex - 1;
+  const hook = component._hooks?.[prevHookIdx];
+  if (hook && hook.type === 'memo') {
+    hook._onInvalidate = callback;
+  }
+}
+
+// ─── Extended useMemo Features ────────────────────────────────────────────────
+
+/**
+ * Memoize with a custom equality function instead of Object.is.
+ *
+ * @param {Function} factory - Factory function
+ * @param {Array} deps - Dependency array
+ * @param {Function} areEqual - Custom equality: (prev, next) => boolean
+ * @returns {*} Memoized value
+ */
+function useMemoWith(factory, deps, areEqual) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMemoWith] Must be called within a component render phase');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+
+    const prevDeps = hook.deps;
+    let depsChanged = !areDepsEqual(prevDeps, resolvedDeps);
+
+    // Even if deps changed by reference, use custom equality to compare values
+    if (depsChanged && typeof areEqual === 'function' && hook.value !== undefined) {
+      try {
+        const newValue = factory();
+        if (areEqual(hook.value, newValue)) {
+          // Values are equal despite dep reference changes
+          hook.deps = resolvedDeps;
+          hook.value = newValue;
+        } else {
+          hook.deps = resolvedDeps;
+          hook.value = newValue;
+          hook._computeCount++;
+          hook._valueChangedCount++;
+        }
+      } catch (error) {
+        console.error('[useMemoWith] Factory error:', error);
+      }
+    } else if (depsChanged) {
+      try {
+        hook.deps = resolvedDeps;
+        hook.value = factory();
+        hook._computeCount++;
+        hook._valueChangedCount++;
+      } catch (error) {
+        console.error('[useMemoWith] Factory error:', error);
+      }
+    }
+  } else {
+    let initialValue;
+    try {
+      initialValue = factory();
+    } catch (error) {
+      console.error('[useMemoWith] Factory error on mount:', error);
+      initialValue = undefined;
+    }
+
+    hook = {
+      type: 'memo',
+      value: initialValue,
+      deps: resolvedDeps,
+      _computeCount: 1,
+      _valueChangedCount: 1,
+      _createdAt: Date.now(),
+      _lastComputedAt: Date.now(),
+      _onInvalidate: null,
+      _lruCache: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+  return hook.value;
+}
+
+/**
+ * Memoize with a time-to-live (TTL). The cached value expires after
+ * the specified duration and will be recomputed.
+ *
+ * @param {Function} factory - Factory function
+ * @param {Array} deps - Dependency array
+ * @param {number} ttlMs - Time-to-live in milliseconds
+ * @returns {*} Memoized value
+ */
+function useMemoTTL(factory, deps, ttlMs) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMemoTTL] Must be called within a component render phase');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+
+    const now = Date.now();
+    const expired = (now - hook._lastComputedAt) > ttlMs;
+    const prevDeps = hook.deps;
+    const depsChanged = !areDepsEqual(prevDeps, resolvedDeps);
+
+    if (expired || depsChanged) {
+      try {
+        hook.deps = resolvedDeps;
+        hook.value = factory();
+        hook._computeCount++;
+        hook._valueChangedCount++;
+        hook._lastComputedAt = now;
+      } catch (error) {
+        console.error('[useMemoTTL] Factory error:', error);
+      }
+    }
+  } else {
+    let initialValue;
+    try {
+      initialValue = factory();
+    } catch (error) {
+      console.error('[useMemoTTL] Factory error on mount:', error);
+      initialValue = undefined;
+    }
+
+    hook = {
+      type: 'memo',
+      value: initialValue,
+      deps: resolvedDeps,
+      _computeCount: 1,
+      _valueChangedCount: 1,
+      _createdAt: Date.now(),
+      _lastComputedAt: Date.now(),
+      _onInvalidate: null,
+      _lruCache: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+  return hook.value;
+}
+
+/**
+ * Memoize with deep comparison of dependencies.
+ *
+ * @param {Function} factory - Factory function
+ * @param {Array} deps - Dependency array (compared deeply)
+ * @returns {*} Memoized value
+ */
+function useDeepCompareMemo(factory, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useDeepCompareMemo] Must be called within a component render phase');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+
+    const prevDeps = hook.deps;
+    const depsChanged = !areDepsDeepEqual(prevDeps, resolvedDeps);
+
+    if (depsChanged) {
+      hook.deps = resolvedDeps;
+      try {
+        hook.value = factory();
+        hook._computeCount++;
+        hook._valueChangedCount++;
+        hook._lastComputedAt = Date.now();
+      } catch (error) {
+        console.error('[useDeepCompareMemo] Factory error:', error);
+      }
+    }
+  } else {
+    let initialValue;
+    try {
+      initialValue = factory();
+    } catch (error) {
+      console.error('[useDeepCompareMemo] Factory error on mount:', error);
+      initialValue = undefined;
+    }
+
+    hook = {
+      type: 'memo',
+      value: initialValue,
+      deps: resolvedDeps,
+      _computeCount: 1,
+      _valueChangedCount: 1,
+      _createdAt: Date.now(),
+      _lastComputedAt: Date.now(),
+      _onInvalidate: null,
+      _lruCache: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+    if (!memoCache.has(component)) {
+      memoCache.set(component, new Set());
+    }
+    memoCache.get(component).add(currentHookIndex);
+  }
+
+  hookIndex++;
+  return hook.value;
+}
+
+/**
+ * Memoize with LRU cache - keeps multiple cached values for different dep sets.
+ *
+ * @param {Function} factory - Factory function
+ * @param {Array} deps - Dependency array
+ * @param {number} capacity - LRU cache capacity (default 10)
+ * @returns {*} Memoized value
+ */
+function useMemoLRU(factory, deps, capacity) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMemoLRU] Must be called within a component render phase');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  const depKey = resolvedDeps ? JSON.stringify(resolvedDeps) : '__no_deps__';
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+
+    // Initialize LRU cache if not present
+    if (!hook._lruCache) {
+      hook._lruCache = new LRUMemoCache(capacity || 10);
+    }
+
+    // Check LRU cache
+    const cached = hook._lruCache.get(depKey);
+    if (cached !== undefined) {
+      hook.value = cached;
+    } else {
+      try {
+        const newValue = factory();
+        hook._lruCache.set(depKey, newValue);
+        hook.value = newValue;
+        hook._computeCount++;
+        hook._valueChangedCount++;
+        hook._lastComputedAt = Date.now();
+      } catch (error) {
+        console.error('[useMemoLRU] Factory error:', error);
+      }
+    }
+  } else {
+    let initialValue;
+    try {
+      initialValue = factory();
+    } catch (error) {
+      console.error('[useMemoLRU] Factory error on mount:', error);
+      initialValue = undefined;
+    }
+
+    const lru = new LRUMemoCache(capacity || 10);
+    lru.set(depKey, initialValue);
+
+    hook = {
+      type: 'memo',
+      value: initialValue,
+      deps: resolvedDeps,
+      _computeCount: 1,
+      _valueChangedCount: 1,
+      _createdAt: Date.now(),
+      _lastComputedAt: Date.now(),
+      _onInvalidate: null,
+      _lruCache: lru,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+  return hook.value;
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Clean up memo cache when a component unmounts.
+ * @param {Object} component
+ */
+function cleanupMemoCache(component) {
+  const indices = memoCache.get(component);
+  if (indices) {
+    indices.forEach((idx) => {
+      const hook = component._hooks?.[idx];
+      if (hook) {
+        hook._onInvalidate = null;
+        if (hook._lruCache) {
+          hook._lruCache.clear();
+        }
+      }
+    });
+    memoCache.delete(component);
+  }
+  memoProfiles.delete(component);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useMemo,
+  useMemoWith,
+  useMemoTTL,
+  useDeepCompareMemo,
+  useMemoLRU,
+  useMemoOnInvalidate,
+  invalidateMemo,
+  invalidateAllMemos,
+  setCurrentComponent,
+  resetHookIndex,
+  areDepsEqual,
+  areDepsDeepEqual,
+  cleanupMemoCache,
+  setMemoProfiling,
+  getMemoProfile,
+  LRUMemoCache,
+};