@signaltree/core 5.1.1 → 5.1.3

package/dist/lib/signal-tree.js

@@ -0,0 +1,626 @@
+import { signal, isSignal, computed, effect, inject, DestroyRef } from '@angular/core';
+import { resolveEnhancerOrder } from '../enhancers/index.js';
+import { SIGNAL_TREE_MESSAGES, SIGNAL_TREE_CONSTANTS } from './constants.js';
+import { SignalMemoryManager } from './memory/memory-manager.js';
+import { OptimizedUpdateEngine } from './performance/update-engine.js';
+import { SecurityValidator } from './security/security-validator.js';
+import { createLazySignalTree, unwrap } from './utils.js';
+import { deepEqual } from '../deep-equal.js';
+import { isBuiltInObject } from '../is-built-in-object.js';
+
+const NODE_ACCESSOR_SYMBOL = Symbol.for('NodeAccessor');
+function makeNodeAccessor() {
+  const accessor = function (arg) {
+    if (arguments.length === 0) {
+      return unwrap(accessor);
+    }
+    if (typeof arg === 'function') {
+      const updater = arg;
+      const currentValue = unwrap(accessor);
+      const newValue = updater(currentValue);
+      recursiveUpdate(accessor, newValue);
+    } else {
+      recursiveUpdate(accessor, arg);
+    }
+  };
+  accessor[NODE_ACCESSOR_SYMBOL] = true;
+  return accessor;
+}
+function makeRootNodeAccessor(readSignal, writeSignal) {
+  const accessor = function (arg) {
+    if (arguments.length === 0) {
+      return readSignal();
+    }
+    if (typeof arg === 'function') {
+      const updater = arg;
+      writeSignal.set(updater(readSignal()));
+    } else {
+      writeSignal.set(arg);
+    }
+  };
+  accessor[NODE_ACCESSOR_SYMBOL] = true;
+  return accessor;
+}
+function recursiveUpdate(target, updates) {
+  if (!updates || typeof updates !== 'object') {
+    return;
+  }
+  let targetObj;
+  if (isNodeAccessor(target)) {
+    targetObj = target;
+  } else if (target && typeof target === 'object') {
+    targetObj = target;
+  } else {
+    return;
+  }
+  const updatesObj = updates;
+  for (const key in updatesObj) {
+    if (!(key in targetObj)) {
+      continue;
+    }
+    const targetProp = targetObj[key];
+    const updateValue = updatesObj[key];
+    if (isSignal(targetProp)) {
+      if ('set' in targetProp && typeof targetProp.set === 'function') {
+        targetProp.set(updateValue);
+      }
+    } else if (isNodeAccessor(targetProp)) {
+      if (updateValue && typeof updateValue === 'object') {
+        recursiveUpdate(targetProp, updateValue);
+      } else {
+        targetProp(updateValue);
+      }
+    }
+  }
+}
+function isNodeAccessor(value) {
+  return typeof value === 'function' && value && value[NODE_ACCESSOR_SYMBOL] === true;
+}
+function estimateObjectSize(obj, maxDepth = SIGNAL_TREE_CONSTANTS.ESTIMATE_MAX_DEPTH, currentDepth = 0) {
+  if (currentDepth >= maxDepth) return 1;
+  if (obj === null || obj === undefined) return 0;
+  if (typeof obj !== 'object') return 1;
+  let size = 0;
+  try {
+    if (Array.isArray(obj)) {
+      size = obj.length;
+      const sampleSize = Math.min(SIGNAL_TREE_CONSTANTS.ESTIMATE_SAMPLE_SIZE_ARRAY, obj.length);
+      for (let i = 0; i < sampleSize; i++) {
+        size += estimateObjectSize(obj[i], maxDepth, currentDepth + 1) * 0.1;
+      }
+    } else {
+      const keys = Object.keys(obj);
+      size = keys.length;
+      const sampleSize = Math.min(SIGNAL_TREE_CONSTANTS.ESTIMATE_SAMPLE_SIZE_OBJECT, keys.length);
+      for (let i = 0; i < sampleSize; i++) {
+        const value = obj[keys[i]];
+        size += estimateObjectSize(value, maxDepth, currentDepth + 1) * 0.5;
+      }
+    }
+  } catch {
+    return 1;
+  }
+  return Math.floor(size);
+}
+function shouldUseLazy(obj, config, precomputedSize) {
+  if (config.useLazySignals !== undefined) return config.useLazySignals;
+  if (config.debugMode || config.enableDevTools) return false;
+  if (config.batchUpdates && config.useMemoization) return true;
+  const estimatedSize = precomputedSize ?? estimateObjectSize(obj);
+  return estimatedSize > SIGNAL_TREE_CONSTANTS.LAZY_THRESHOLD;
+}
+function validateTree(obj, config, path = []) {
+  if (!config.security) {
+    return;
+  }
+  const validator = new SecurityValidator(config.security);
+  function validate(value, currentPath) {
+    if (value === null || value === undefined) {
+      return;
+    }
+    if (typeof value !== 'object') {
+      validator.validateValue(value);
+      return;
+    }
+    if (isBuiltInObject(value)) {
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        validate(item, [...currentPath, String(index)]);
+      });
+      return;
+    }
+    const keys = [...Object.keys(value), ...Object.getOwnPropertyNames(value)];
+    const uniqueKeys = [...new Set(keys)];
+    for (const key of uniqueKeys) {
+      if (typeof key === 'symbol') continue;
+      try {
+        validator.validateKey(key);
+      } catch (error) {
+        const err = error;
+        throw new Error(`${err.message}\nPath: ${[...currentPath, key].join('.')}`);
+      }
+      const val = value[key];
+      try {
+        validator.validateValue(val);
+      } catch (error) {
+        const err = error;
+        throw new Error(`${err.message}\nPath: ${[...currentPath, key].join('.')}`);
+      }
+      validate(val, [...currentPath, key]);
+    }
+  }
+  validate(obj, path);
+}
+function createEqualityFn(useShallowComparison) {
+  return useShallowComparison ? Object.is : deepEqual;
+}
+function createSignalStore(obj, equalityFn) {
+  if (obj === null || obj === undefined || typeof obj !== 'object') {
+    return signal(obj, {
+      equal: equalityFn
+    });
+  }
+  if (Array.isArray(obj)) {
+    return signal(obj, {
+      equal: equalityFn
+    });
+  }
+  if (isBuiltInObject(obj)) {
+    return signal(obj, {
+      equal: equalityFn
+    });
+  }
+  const store = {};
+  const processedObjects = new WeakSet();
+  if (processedObjects.has(obj)) {
+    console.warn(SIGNAL_TREE_MESSAGES.CIRCULAR_REF);
+    return signal(obj, {
+      equal: equalityFn
+    });
+  }
+  processedObjects.add(obj);
+  try {
+    for (const [key, value] of Object.entries(obj)) {
+      try {
+        if (typeof key === 'symbol') continue;
+        if (isEntityMapMarker(value)) {
+          store[key] = value;
+          continue;
+        }
+        if (isSignal(value)) {
+          store[key] = value;
+          continue;
+        }
+        if (value === null || value === undefined) {
+          store[key] = signal(value, {
+            equal: equalityFn
+          });
+        } else if (typeof value !== 'object') {
+          store[key] = signal(value, {
+            equal: equalityFn
+          });
+        } else if (Array.isArray(value) || isBuiltInObject(value)) {
+          store[key] = signal(value, {
+            equal: equalityFn
+          });
+        } else {
+          const branch = createSignalStore(value, equalityFn);
+          const callableBranch = makeNodeAccessor();
+          for (const branchKey in branch) {
+            if (Object.prototype.hasOwnProperty.call(branch, branchKey)) {
+              try {
+                Object.defineProperty(callableBranch, branchKey, {
+                  value: branch[branchKey],
+                  enumerable: true,
+                  configurable: true
+                });
+              } catch {}
+            }
+          }
+          store[key] = callableBranch;
+        }
+      } catch (error) {
+        console.warn(`${SIGNAL_TREE_MESSAGES.SIGNAL_CREATION_FAILED} "${key}":`, error);
+        store[key] = signal(value, {
+          equal: equalityFn
+        });
+      }
+    }
+    const symbols = Object.getOwnPropertySymbols(obj);
+    for (const sym of symbols) {
+      const value = obj[sym];
+      try {
+        if (isEntityMapMarker(value)) {
+          store[sym] = value;
+          continue;
+        }
+        if (isSignal(value)) {
+          store[sym] = value;
+        } else {
+          store[sym] = signal(value, {
+            equal: equalityFn
+          });
+        }
+      } catch (error) {
+        console.warn(SIGNAL_TREE_MESSAGES.SIGNAL_CREATION_FAILED, error);
+      }
+    }
+  } catch (error) {
+    throw new Error(`Failed to create signal store: ${error instanceof Error ? error.message : 'Unknown error'}`);
+  }
+  return store;
+}
+function isEntityMapMarker(value) {
+  return Boolean(value && typeof value === 'object' && value['__isEntityMap'] === true);
+}
+function enhanceTree(tree, config = {}) {
+  const isLazy = config.useLazySignals ?? shouldUseLazy(tree.state, config);
+  tree.with = (...enhancers) => {
+    if (enhancers.length === 0) {
+      return tree;
+    }
+    const coreCapabilities = new Set();
+    if (config.batchUpdates) coreCapabilities.add('batchUpdate');
+    if (config.useMemoization) coreCapabilities.add('memoize');
+    if (config.enableTimeTravel) coreCapabilities.add('undo');
+    if (config.enableDevTools) coreCapabilities.add('connectDevTools');
+    try {
+      for (const key of Object.keys(tree)) coreCapabilities.add(String(key));
+    } catch {}
+    const hasMetadata = enhancers.some(e => Boolean(e.metadata && (e.metadata.requires || e.metadata.provides)));
+    let orderedEnhancers = enhancers;
+    if (hasMetadata) {
+      try {
+        orderedEnhancers = resolveEnhancerOrder(enhancers, coreCapabilities, config.debugMode);
+      } catch (err) {
+        console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_ORDER_FAILED, err);
+      }
+    }
+    const provided = new Set(coreCapabilities);
+    let currentTree = tree;
+    for (let i = 0; i < orderedEnhancers.length; i++) {
+      const enhancer = orderedEnhancers[i];
+      if (typeof enhancer !== 'function') {
+        throw new Error(SIGNAL_TREE_MESSAGES.ENHANCER_NOT_FUNCTION.replace('%d', String(i)));
+      }
+      const reqs = enhancer.metadata?.requires ?? [];
+      for (const r of reqs) {
+        if (!(r in currentTree) && !provided.has(r)) {
+          const name = enhancer.metadata?.name ?? `enhancer#${i}`;
+          const msg = SIGNAL_TREE_MESSAGES.ENHANCER_REQUIREMENT_MISSING.replace('%s', name).replace('%s', r);
+          if (config.debugMode) {
+            throw new Error(msg);
+          } else {
+            console.warn(msg);
+          }
+        }
+      }
+      try {
+        const result = enhancer(currentTree);
+        if (result !== currentTree) currentTree = result;
+        const provs = enhancer.metadata?.provides ?? [];
+        for (const p of provs) provided.add(p);
+        if (config.debugMode && provs.length > 0) {
+          for (const p of provs) {
+            if (!(p in currentTree)) {
+              console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_PROVIDES_MISSING.replace('%s', enhancer.metadata?.name ?? String(i)).replace('%s', p));
+            }
+          }
+        }
+      } catch (error) {
+        const name = enhancer.metadata?.name || `enhancer at index ${i}`;
+        console.error(SIGNAL_TREE_MESSAGES.ENHANCER_FAILED.replace('%s', name), error);
+        if (config.debugMode) {
+          console.error('[SignalTree] Enhancer stack trace:', enhancer);
+          console.error('[SignalTree] Tree state at failure:', currentTree);
+        }
+        throw error;
+      }
+    }
+    return currentTree;
+  };
+  tree.destroy = () => {
+    try {
+      if (isLazy) {
+        const state = tree.state;
+        if (state && typeof state === 'object' && '__cleanup__' in state) {
+          const cleanup = state.__cleanup__;
+          if (typeof cleanup === 'function') {
+            cleanup();
+          }
+        }
+      }
+      if (config.debugMode) {
+        console.log(SIGNAL_TREE_MESSAGES.TREE_DESTROYED);
+      }
+    } catch (error) {
+      console.error(SIGNAL_TREE_MESSAGES.CLEANUP_ERROR, error);
+    }
+  };
+  addStubMethods(tree, config);
+  return tree;
+}
+function addStubMethods(tree, config) {
+  tree.batchUpdate = updater => {
+    console.warn(SIGNAL_TREE_MESSAGES.BATCH_NOT_ENABLED);
+    tree(current => {
+      const partial = updater(current);
+      return {
+        ...current,
+        ...partial
+      };
+    });
+  };
+  tree.memoize = (fn, cacheKey) => {
+    console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+    return computed(() => fn(tree()));
+  };
+  tree.memoizedUpdate = updater => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+    }
+    tree(current => ({
+      ...current,
+      ...updater(current)
+    }));
+  };
+  tree.clearMemoCache = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+    }
+  };
+  tree.getCacheStats = () => ({
+    size: 0,
+    hitRate: 0,
+    totalHits: 0,
+    totalMisses: 0,
+    keys: []
+  });
+  tree.effect = fn => {
+    try {
+      effect(() => fn(tree()));
+    } catch (error) {
+      if (config.debugMode) {
+        console.warn(SIGNAL_TREE_MESSAGES.EFFECT_NO_CONTEXT, error);
+      }
+    }
+  };
+  tree.subscribe = fn => {
+    try {
+      const destroyRef = inject(DestroyRef);
+      let isDestroyed = false;
+      const effectRef = effect(() => {
+        if (!isDestroyed) {
+          fn(tree());
+        }
+      });
+      const unsubscribe = () => {
+        isDestroyed = true;
+        effectRef.destroy();
+      };
+      destroyRef.onDestroy(unsubscribe);
+      return unsubscribe;
+    } catch (error) {
+      if (config.debugMode) {
+        console.warn(SIGNAL_TREE_MESSAGES.SUBSCRIBE_NO_CONTEXT, error);
+      }
+      throw error;
+    }
+  };
+  tree.optimize = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.OPTIMIZE_NOT_AVAILABLE);
+    }
+  };
+  tree.clearCache = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.CACHE_NOT_AVAILABLE);
+    }
+  };
+  tree.invalidatePattern = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.PERFORMANCE_NOT_ENABLED);
+    }
+    return 0;
+  };
+  const treeWithEngine = tree;
+  if (!treeWithEngine.updateEngine) {
+    treeWithEngine.updateEngine = new OptimizedUpdateEngine(tree);
+  }
+  tree.updateOptimized = (updates, options = {}) => {
+    const treeWithEngine = tree;
+    const engine = treeWithEngine.updateEngine;
+    if (!engine) {
+      if (config.debugMode) {
+        console.warn(SIGNAL_TREE_MESSAGES.UPDATE_OPTIMIZED_NOT_AVAILABLE);
+      }
+      tree(current => ({
+        ...current,
+        ...updates
+      }));
+      return {
+        changed: true,
+        duration: 0,
+        changedPaths: Object.keys(updates),
+        stats: undefined
+      };
+    }
+    return engine.update(tree(), updates, options);
+  };
+  tree.getMetrics = () => {
+    return {
+      updates: 0,
+      computations: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      averageUpdateTime: 0
+    };
+  };
+  tree.entities = () => {
+    console.warn('[@signaltree/core] tree.entities() is deprecated and will be removed in v6.0. ' + 'Use entityMap<E>() + withEntities() + tree.$.collectionName instead. ' + 'See https://signaltree.dev/docs/migration for migration guide.');
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.ENTITY_HELPERS_NOT_AVAILABLE);
+    }
+    return {};
+  };
+  tree.undo = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+    }
+  };
+  tree.redo = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+    }
+  };
+  tree.getHistory = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+    }
+    return [];
+  };
+  tree.resetHistory = () => {
+    if (config.debugMode) {
+      console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+    }
+  };
+}
+function create(obj, config = {}) {
+  if (obj === null || obj === undefined) {
+    throw new Error(SIGNAL_TREE_MESSAGES.NULL_OR_UNDEFINED);
+  }
+  validateTree(obj, config);
+  const estimatedSize = estimateObjectSize(obj);
+  const equalityFn = createEqualityFn(config.useShallowComparison ?? false);
+  if (Array.isArray(obj)) {
+    const signalState = signal(obj, {
+      equal: equalityFn
+    });
+    const tree = makeRootNodeAccessor(signalState, signalState);
+    Object.defineProperty(tree, 'state', {
+      value: signalState,
+      enumerable: false
+    });
+    Object.defineProperty(tree, '$', {
+      value: signalState,
+      enumerable: false
+    });
+    enhanceTree(tree, config);
+    return tree;
+  }
+  const useLazy = shouldUseLazy(obj, config, estimatedSize);
+  if (config.debugMode) {
+    console.log(SIGNAL_TREE_MESSAGES.STRATEGY_SELECTION.replace('%s', useLazy ? 'lazy' : 'eager').replace('%d', String(estimatedSize)));
+  }
+  let signalState;
+  let memoryManager;
+  try {
+    if (useLazy && typeof obj === 'object') {
+      memoryManager = new SignalMemoryManager();
+      signalState = createLazySignalTree(obj, equalityFn, '', memoryManager);
+    } else {
+      signalState = createSignalStore(obj, equalityFn);
+    }
+  } catch (error) {
+    if (useLazy) {
+      console.warn(SIGNAL_TREE_MESSAGES.LAZY_FALLBACK, error);
+      signalState = createSignalStore(obj, equalityFn);
+      memoryManager = undefined;
+    } else {
+      throw error;
+    }
+  }
+  const tree = function (arg) {
+    if (arguments.length === 0) {
+      return unwrap(signalState);
+    }
+    if (typeof arg === 'function') {
+      const updater = arg;
+      const currentValue = unwrap(signalState);
+      const newValue = updater(currentValue);
+      recursiveUpdate(signalState, newValue);
+    } else {
+      recursiveUpdate(signalState, arg);
+    }
+  };
+  Object.defineProperty(tree, NODE_ACCESSOR_SYMBOL, {
+    value: true,
+    enumerable: false
+  });
+  Object.defineProperty(tree, 'state', {
+    value: signalState,
+    enumerable: false
+  });
+  Object.defineProperty(tree, '$', {
+    value: signalState,
+    enumerable: false
+  });
+  if (memoryManager) {
+    Object.defineProperty(tree, 'dispose', {
+      value: () => {
+        memoryManager?.dispose();
+        const cleanup = signalState.__cleanup__;
+        if (typeof cleanup === 'function') {
+          cleanup();
+        }
+      },
+      enumerable: false,
+      writable: false
+    });
+  }
+  enhanceTree(tree, config);
+  for (const key in signalState) {
+    if (Object.prototype.hasOwnProperty.call(signalState, key)) {
+      if (!(key in tree)) {
+        try {
+          Object.defineProperty(tree, key, {
+            value: signalState[key],
+            enumerable: true,
+            configurable: true
+          });
+        } catch {}
+      }
+    }
+  }
+  return tree;
+}
+const presetConfigs = {
+  basic: {
+    useLazySignals: false,
+    debugMode: false
+  },
+  performance: {
+    useLazySignals: true,
+    batchUpdates: true,
+    useMemoization: true,
+    useShallowComparison: true
+  },
+  development: {
+    useLazySignals: false,
+    debugMode: true,
+    enableDevTools: true,
+    trackPerformance: true
+  },
+  production: {
+    useLazySignals: true,
+    batchUpdates: true,
+    useMemoization: true,
+    debugMode: false
+  }
+};
+function signalTree(obj, configOrPreset) {
+  if (typeof configOrPreset === 'string') {
+    const config = presetConfigs[configOrPreset];
+    if (!config) {
+      console.warn(SIGNAL_TREE_MESSAGES.PRESET_UNKNOWN.replace('%s', configOrPreset));
+      return create(obj, {});
+    }
+    return create(obj, config);
+  }
+  const config = configOrPreset || {};
+  return create(obj, config);
+}
+
+export { isNodeAccessor, signalTree };

package/dist/lib/types.js

@@ -0,0 +1,9 @@
+const ENHANCER_META = Symbol('signaltree:enhancer:meta');
+function entityMap(config) {
+  return {
+    __isEntityMap: true,
+    __entityMapConfig: config ?? {}
+  };
+}
+
+export { ENHANCER_META, entityMap };