elementdrawing 1.0.0

package/src/jsx/hooks/useCallback.js

@@ -0,0 +1,472 @@
+/**
+ * useCallback Hook Implementation
+ * ElementDrawing Framework - Callback memoization with dependency comparison,
+ * stable references, debouncing, throttling, profiling, and callback composition.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+
+// ─── Callback Profiling ───────────────────────────────────────────────────────
+
+const callbackProfiles = new WeakMap();
+let profilingEnabled = false;
+
+/**
+ * Enable or disable callback profiling.
+ * @param {boolean} enabled
+ */
+function setCallbackProfiling(enabled) {
+  profilingEnabled = enabled;
+}
+
+/**
+ * Get profiling data for a component's callbacks.
+ * @param {Object} component
+ * @returns {Object|null}
+ */
+function getCallbackProfile(component) {
+  return callbackProfiles.get(component) || null;
+}
+
+// ─── 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 for complex dependency values.
+ */
+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(
+      '[useCallback] 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;
+}
+
+// ─── useCallback Hook ─────────────────────────────────────────────────────────
+
+/**
+ * useCallback - Memoize a callback function based on dependencies.
+ * Returns a stable reference that only changes when dependencies change.
+ *
+ * @param {Function} callback - The callback function to memoize
+ * @param {Array} deps - Dependency array; callback updates when deps change
+ * @returns {Function} Memoized callback with stable reference
+ *
+ * @example
+ * const handleClick = useCallback((event) => {
+ *   setCount(prev => prev + 1);
+ * }, [setCount]);
+ *
+ * @example
+ * // Preventing unnecessary child re-renders
+ * const handleSubmit = useCallback((data) => {
+ *   onSubmit(data);
+ * }, [onSubmit]);
+ *
+ * <ChildComponent onSubmit={handleSubmit} />
+ */
+function useCallback(callback, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useCallback] Must be called within a component render phase');
+  }
+
+  if (typeof callback !== 'function') {
+    throw new Error(
+      '[useCallback] First argument must be a function. ' +
+      `Received: ${typeof callback}`
+    );
+  }
+
+  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 - update the callback
+      hook.callback = callback;
+      hook.deps = resolvedDeps;
+      hook.memoizedCallback = createStableCallback(callback, component, currentHookIndex);
+      hook._updateCount++;
+    }
+    // If deps unchanged, keep the existing memoizedCallback
+  } else {
+    // First render: create the hook
+    hook = {
+      type: 'callback',
+      callback,
+      deps: resolvedDeps,
+      memoizedCallback: null,
+      _callCount: 0,
+      _lastCalledAt: null,
+      _updateCount: 0,
+      _createdAt: Date.now(),
+    };
+
+    hook.memoizedCallback = createStableCallback(callback, component, currentHookIndex);
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Update profiling data
+  if (profilingEnabled) {
+    if (!callbackProfiles.has(component)) {
+      callbackProfiles.set(component, {});
+    }
+    const profile = callbackProfiles.get(component);
+    profile[currentHookIndex] = {
+      callCount: hook._callCount,
+      updateCount: hook._updateCount,
+      lastCalledAt: hook._lastCalledAt,
+    };
+  }
+
+  hookIndex++;
+  return hook.memoizedCallback;
+}
+
+// ─── Stable Callback Creation ─────────────────────────────────────────────────
+
+/**
+ * Create a stable callback wrapper that delegates to the current callback.
+ * The wrapper function reference stays the same across renders while
+ * always calling the latest callback version.
+ *
+ * @param {Function} initialCallback - The initial callback
+ * @param {Object} component - The owning component
+ * @param {number} hookIdx - The hook index
+ * @returns {Function} Stable callback reference
+ */
+function createStableCallback(initialCallback, component, hookIdx) {
+  // The stable wrapper always reads the latest callback from the hook
+  const stableCallback = function stableCallbackWrapper() {
+    const hook = component._hooks?.[hookIdx];
+    if (!hook) {
+      console.warn('[useCallback] Callback called after component unmount');
+      return undefined;
+    }
+
+    const currentCallback = hook.callback;
+    hook._callCount++;
+    hook._lastCalledAt = Date.now();
+
+    try {
+      return currentCallback.apply(this, arguments);
+    } catch (error) {
+      console.error('[useCallback] Callback execution error:', error);
+      if (component._handleError) {
+        component._handleError(error);
+      }
+      throw error;
+    }
+  };
+
+  // Attach metadata for debugging and introspection
+  Object.defineProperty(stableCallback, '_isStable', { value: true });
+  Object.defineProperty(stableCallback, '_hookIndex', { value: hookIdx });
+  Object.defineProperty(stableCallback, '_component', { value: component });
+
+  /**
+   * Get the number of times this callback has been invoked.
+   * @returns {number}
+   */
+  stableCallback.getCallCount = function getCallCount() {
+    const hook = component._hooks?.[hookIdx];
+    return hook ? hook._callCount : 0;
+  };
+
+  /**
+   * Get the timestamp of the last invocation.
+   * @returns {number|null}
+   */
+  stableCallback.getLastCalledAt = function getLastCalledAt() {
+    const hook = component._hooks?.[hookIdx];
+    return hook ? hook._lastCalledAt : null;
+  };
+
+  /**
+   * Get the current underlying callback without calling it.
+   * @returns {Function}
+   */
+  stableCallback.getCurrentCallback = function getCurrentCallback() {
+    const hook = component._hooks?.[hookIdx];
+    return hook ? hook.callback : null;
+  };
+
+  /**
+   * Check if this is the same stable reference as another callback.
+   * @param {Function} other - Another callback to compare
+   * @returns {boolean}
+   */
+  stableCallback.isSameRef = function isSameRef(other) {
+    return other === stableCallback;
+  };
+
+  return stableCallback;
+}
+
+// ─── Extended useCallback Features ────────────────────────────────────────────
+
+/**
+ * Create a debounced version of useCallback.
+ * The returned callback will only execute after the specified delay
+ * since the last invocation.
+ *
+ * @param {Function} callback - The callback to debounce
+ * @param {Array} deps - Dependency array
+ * @param {number} delay - Debounce delay in milliseconds
+ * @returns {Function} Debounced memoized callback
+ */
+function useDebouncedCallback(callback, deps, delay) {
+  const memoizedCallback = useCallback(callback, deps);
+
+  // Simple debounce wrapper
+  let timeoutId = null;
+  const debouncedCallback = function debouncedWrapper() {
+    const args = arguments;
+    const context = this;
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      memoizedCallback.apply(context, args);
+    }, delay);
+  };
+
+  debouncedCallback.cancel = function cancel() {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  debouncedCallback.flush = function flush() {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+      memoizedCallback();
+    }
+  };
+
+  return debouncedCallback;
+}
+
+/**
+ * Create a throttled version of useCallback.
+ * The returned callback will execute at most once per specified interval.
+ *
+ * @param {Function} callback - The callback to throttle
+ * @param {Array} deps - Dependency array
+ * @param {number} interval - Throttle interval in milliseconds
+ * @returns {Function} Throttled memoized callback
+ */
+function useThrottledCallback(callback, deps, interval) {
+  const memoizedCallback = useCallback(callback, deps);
+
+  let lastExecTime = 0;
+  let timeoutId = null;
+
+  const throttledCallback = function throttledWrapper() {
+    const args = arguments;
+    const context = this;
+    const now = Date.now();
+    const elapsed = now - lastExecTime;
+
+    if (elapsed >= interval) {
+      lastExecTime = now;
+      memoizedCallback.apply(context, args);
+    } else if (!timeoutId) {
+      timeoutId = setTimeout(() => {
+        lastExecTime = Date.now();
+        timeoutId = null;
+        memoizedCallback.apply(context, args);
+      }, interval - elapsed);
+    }
+  };
+
+  throttledCallback.cancel = function cancel() {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  return throttledCallback;
+}
+
+/**
+ * Create a callback that only executes once and then becomes a no-op.
+ *
+ * @param {Function} callback - The callback
+ * @param {Array} deps - Dependency array
+ * @returns {Function} One-time callback
+ */
+function useOnceCallback(callback, deps) {
+  let called = false;
+  return useCallback(function onceWrapper() {
+    if (called) return;
+    called = true;
+    return callback.apply(this, arguments);
+  }, deps);
+}
+
+/**
+ * Create a callback with deep dependency comparison.
+ * Useful when dependencies are objects or arrays that may be recreated.
+ *
+ * @param {Function} callback - The callback function
+ * @param {Array} deps - Dependency array (compared deeply)
+ * @returns {Function} Memoized callback
+ */
+function useDeepCompareCallback(callback, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useDeepCompareCallback] 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.callback = callback;
+      hook.deps = resolvedDeps;
+      hook.memoizedCallback = createStableCallback(callback, component, currentHookIndex);
+      hook._updateCount++;
+    }
+  } else {
+    hook = {
+      type: 'callback',
+      callback,
+      deps: resolvedDeps,
+      memoizedCallback: null,
+      _callCount: 0,
+      _lastCalledAt: null,
+      _updateCount: 0,
+      _createdAt: Date.now(),
+    };
+
+    hook.memoizedCallback = createStableCallback(callback, component, currentHookIndex);
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+  return hook.memoizedCallback;
+}
+
+/**
+ * Compose multiple callbacks into a single callback.
+ * Each callback receives the same arguments and results are collected.
+ *
+ * @param {Function[]} callbacks - Array of callbacks to compose
+ * @param {Array} deps - Dependency array
+ * @returns {Function} Composed callback
+ */
+function useComposedCallback(callbacks, deps) {
+  return useCallback(function composedCallback() {
+    const args = arguments;
+    return callbacks.map((cb) => {
+      if (typeof cb === 'function') {
+        return cb.apply(this, args);
+      }
+      return undefined;
+    });
+  }, deps);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useCallback,
+  useDebouncedCallback,
+  useThrottledCallback,
+  useOnceCallback,
+  useDeepCompareCallback,
+  useComposedCallback,
+  setCurrentComponent,
+  resetHookIndex,
+  areDepsEqual,
+  areDepsDeepEqual,
+  setCallbackProfiling,
+  getCallbackProfile,
+};