@signaltree/core 4.0.16 → 4.1.0

package/README.md

@@ -17,6 +17,33 @@ SignalTree Core is a lightweight package that provides:
 - Small API surface with zero-cost abstractions
 - Compact bundle size suited for production
 
+## Import guidance (tree-shaking)
+
+Modern bundlers (webpack 5+, esbuild, Rollup, Vite) **automatically tree-shake barrel imports** from `@signaltree/core`. Both import styles produce identical bundle sizes:
+
+```ts
+// ✅ Recommended: Simple and clean
+import { signalTree, withBatching } from '@signaltree/core';
+
+// ✅ Also fine: Explicit subpath (same bundle size)
+import { signalTree } from '@signaltree/core';
+import { withBatching } from '@signaltree/core/enhancers/batching';
+```
+
+**Measured impact** (with modern bundlers):
+
+- Core only: ~8.5 KB gzipped
+- Core + batching: ~9.3 KB gzipped (barrel vs subpath: identical)
+- Unused enhancers: **automatically excluded** by tree-shaking
+
+**When to use subpath imports:**
+
+- Older bundlers (webpack <5) with poor tree-shaking
+- Explicit control over what gets included
+- Personal/team preference for clarity
+
+This repo's ESLint rule is **disabled by default** since testing confirms effective tree-shaking with barrel imports.
+
 ### Callable leaf signals (DX sugar only)
 
 SignalTree provides TypeScript support for callable syntax on leaf signals as developer experience sugar:

package/dist/constants.js

@@ -0,0 +1,6 @@
+const SHARED_DEFAULTS = Object.freeze({
+  PATH_CACHE_SIZE: 1000
+});
+const DEFAULT_PATH_CACHE_SIZE = SHARED_DEFAULTS.PATH_CACHE_SIZE;
+
+export { DEFAULT_PATH_CACHE_SIZE, SHARED_DEFAULTS };

package/dist/deep-clone.js

@@ -0,0 +1,80 @@
+const globalStructuredClone = typeof globalThis === 'object' && globalThis !== null ? globalThis.structuredClone : undefined;
+function deepClone(value) {
+  if (globalStructuredClone) {
+    try {
+      return globalStructuredClone(value);
+    } catch (_a) {}
+  }
+  return cloneValue(value, new WeakMap());
+}
+function cloneValue(value, seen) {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (typeof value === 'function') {
+    return value;
+  }
+  const existing = seen.get(value);
+  if (existing) {
+    return existing;
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  if (value instanceof RegExp) {
+    return new RegExp(value.source, value.flags);
+  }
+  if (value instanceof Map) {
+    const result = new Map();
+    seen.set(value, result);
+    for (const [key, entryValue] of value) {
+      result.set(cloneValue(key, seen), cloneValue(entryValue, seen));
+    }
+    return result;
+  }
+  if (value instanceof Set) {
+    const result = new Set();
+    seen.set(value, result);
+    for (const entry of value) {
+      result.add(cloneValue(entry, seen));
+    }
+    return result;
+  }
+  if (Array.isArray(value)) {
+    const result = new Array(value.length);
+    seen.set(value, result);
+    for (let i = 0; i < value.length; i++) {
+      result[i] = cloneValue(value[i], seen);
+    }
+    return result;
+  }
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof DataView) {
+      const bufferClone = cloneValue(value.buffer, seen);
+      return new DataView(bufferClone, value.byteOffset, value.byteLength);
+    }
+    const viewWithSlice = value;
+    if (typeof viewWithSlice.slice === 'function') {
+      return viewWithSlice.slice();
+    }
+    const bufferClone = cloneValue(value.buffer, seen);
+    return new value.constructor(bufferClone, value.byteOffset, value.length);
+  }
+  if (value instanceof ArrayBuffer) {
+    return value.slice(0);
+  }
+  const proto = Object.getPrototypeOf(value);
+  const result = proto ? Object.create(proto) : {};
+  seen.set(value, result);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) continue;
+    if ('value' in descriptor) {
+      descriptor.value = cloneValue(descriptor.value, seen);
+    }
+    Object.defineProperty(result, key, descriptor);
+  }
+  return result;
+}
+
+export { deepClone };

package/dist/deep-equal.js

@@ -0,0 +1,41 @@
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  const typeA = typeof a;
+  const typeB = typeof b;
+  if (typeA !== typeB) return false;
+  if (typeA !== 'object') return false;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+  if (a instanceof RegExp && b instanceof RegExp) {
+    return a.source === b.source && a.flags === b.flags;
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a) {
+      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
+    }
+    return true;
+  }
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const value of a) {
+      if (!b.has(value)) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (Array.isArray(b)) return false;
+  const objA = a;
+  const objB = b;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(key => key in objB && deepEqual(objA[key], objB[key]));
+}
+
+export { deepEqual };

package/dist/enhancers/batching/lib/batching.js

@@ -0,0 +1,161 @@
+import { isNodeAccessor } from '../../../lib/utils.js';
+
+let updateQueue = [];
+let isUpdating = false;
+let flushTimeoutId;
+let currentBatchingConfig = {};
+function addToQueue(update, config = currentBatchingConfig) {
+  const maxSize = config.maxBatchSize ?? 100;
+  if (update.path) {
+    updateQueue = updateQueue.filter(existing => existing.path !== update.path);
+  }
+  updateQueue.push(update);
+  if (updateQueue.length > maxSize) {
+    flushUpdates();
+    return true;
+  }
+  scheduleFlush(config);
+  return false;
+}
+function scheduleFlush(config) {
+  if (flushTimeoutId !== undefined) {
+    clearTimeout(flushTimeoutId);
+  }
+  const delay = config.autoFlushDelay ?? 16;
+  flushTimeoutId = setTimeout(() => {
+    flushUpdates();
+  }, delay);
+}
+function flushUpdates() {
+  if (isUpdating) return;
+  let queue;
+  do {
+    if (updateQueue.length === 0) return;
+    isUpdating = true;
+    queue = updateQueue;
+    updateQueue = [];
+    if (flushTimeoutId !== undefined) {
+      clearTimeout(flushTimeoutId);
+      flushTimeoutId = undefined;
+    }
+    queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+    try {
+      queue.forEach(({
+        fn
+      }) => fn());
+    } finally {
+      isUpdating = false;
+    }
+  } while (updateQueue.length > 0);
+}
+function batchUpdates(fn, path) {
+  const startTime = performance.now();
+  const depth = 0;
+  const update = {
+    fn,
+    startTime,
+    depth,
+    path
+  };
+  const wasFlushed = addToQueue(update, currentBatchingConfig);
+  if (!wasFlushed) {
+    const isTimedOut = currentBatchingConfig.batchTimeoutMs && updateQueue.length > 0 && startTime - updateQueue[0].startTime >= currentBatchingConfig.batchTimeoutMs;
+    if (isTimedOut) {
+      flushUpdates();
+    } else if (!isUpdating && updateQueue.length > 0) {
+      queueMicrotask(() => {
+        flushUpdates();
+      });
+    }
+  }
+}
+function withBatching(config = {}) {
+  const {
+    enabled = true
+  } = config;
+  currentBatchingConfig = {
+    ...currentBatchingConfig,
+    ...config
+  };
+  return tree => {
+    if (!enabled) {
+      return tree;
+    }
+    const originalTreeCall = tree.bind(tree);
+    const enhancedTree = function (...args) {
+      if (args.length === 0) {
+        return originalTreeCall();
+      } else {
+        batchUpdates(() => {
+          if (args.length === 1) {
+            const arg = args[0];
+            if (typeof arg === 'function') {
+              originalTreeCall(arg);
+            } else {
+              originalTreeCall(arg);
+            }
+          }
+        });
+      }
+    };
+    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+    Object.assign(enhancedTree, tree);
+    if ('state' in tree) {
+      Object.defineProperty(enhancedTree, 'state', {
+        value: tree.state,
+        enumerable: false,
+        configurable: true
+      });
+    }
+    if ('$' in tree) {
+      Object.defineProperty(enhancedTree, '$', {
+        value: tree['$'],
+        enumerable: false,
+        configurable: true
+      });
+    }
+    enhancedTree.batchUpdate = updater => {
+      batchUpdates(() => {
+        const current = originalTreeCall();
+        const updates = updater(current);
+        Object.entries(updates).forEach(([key, value]) => {
+          const property = enhancedTree.state[key];
+          if (property && 'set' in property) {
+            property.set(value);
+          } else if (isNodeAccessor(property)) {
+            property(value);
+          }
+        });
+      });
+    };
+    return enhancedTree;
+  };
+}
+function withHighPerformanceBatching() {
+  return withBatching({
+    enabled: true,
+    maxBatchSize: 200,
+    batchTimeoutMs: 0
+  });
+}
+function flushBatchedUpdates() {
+  if (updateQueue.length > 0) {
+    const queue = updateQueue.slice();
+    updateQueue = [];
+    isUpdating = false;
+    queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+    queue.forEach(({
+      fn
+    }) => {
+      fn();
+    });
+  }
+}
+function hasPendingUpdates() {
+  return updateQueue.length > 0;
+}
+function getBatchQueueSize() {
+  return updateQueue.length;
+}
+
+export { flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, withBatching, withHighPerformanceBatching };

package/dist/enhancers/computed/lib/computed.js

@@ -0,0 +1,21 @@
+import { computed } from '@angular/core';
+import { createEnhancer } from '../../index.js';
+
+function computedEnhancer(_config = {}) {
+  return createEnhancer({
+    name: 'computed',
+    provides: ['computed'],
+    requires: []
+  }, tree => {
+    const computedTree = tree;
+    computedTree.computed = function (computeFn) {
+      return computed(() => computeFn(tree.state));
+    };
+    return computedTree;
+  });
+}
+function createComputed(dependencies, computeFn) {
+  return computed(computeFn);
+}
+
+export { computedEnhancer, createComputed };

package/dist/enhancers/devtools/lib/devtools.js

@@ -0,0 +1,321 @@
+import { signal } from '@angular/core';
+
+function createActivityTracker() {
+  const modules = new Map();
+  return {
+    trackMethodCall: (module, method, duration) => {
+      const existing = modules.get(module);
+      if (existing) {
+        existing.lastActivity = new Date();
+        existing.operationCount++;
+        existing.averageExecutionTime = (existing.averageExecutionTime * (existing.operationCount - 1) + duration) / existing.operationCount;
+      } else {
+        modules.set(module, {
+          name: module,
+          methods: [method],
+          addedAt: new Date(),
+          lastActivity: new Date(),
+          operationCount: 1,
+          averageExecutionTime: duration,
+          errorCount: 0
+        });
+      }
+    },
+    trackError: (module, error, context) => {
+      const existing = modules.get(module);
+      if (existing) {
+        existing.errorCount++;
+      }
+      console.error(`❌ [${module}] Error${context ? ` in ${context}` : ''}:`, error);
+    },
+    getModuleActivity: module => modules.get(module),
+    getAllModules: () => Array.from(modules.values())
+  };
+}
+function createCompositionLogger() {
+  const logs = [];
+  const addLog = (module, type, data) => {
+    logs.push({
+      timestamp: new Date(),
+      module,
+      type,
+      data
+    });
+    if (logs.length > 1000) {
+      logs.splice(0, logs.length - 1000);
+    }
+  };
+  return {
+    logComposition: (modules, action) => {
+      addLog('core', 'composition', {
+        modules,
+        action
+      });
+      console.log(`🔗 Composition ${action}:`, modules.join(' → '));
+    },
+    logMethodExecution: (module, method, args, result) => {
+      addLog(module, 'method', {
+        method,
+        args,
+        result
+      });
+      console.debug(`🔧 [${module}] ${method}`, {
+        args,
+        result
+      });
+    },
+    logStateChange: (module, path, oldValue, newValue) => {
+      addLog(module, 'state', {
+        path,
+        oldValue,
+        newValue
+      });
+      console.debug(`📝 [${module}] State change at ${path}:`, {
+        from: oldValue,
+        to: newValue
+      });
+    },
+    logPerformanceWarning: (module, operation, duration, threshold) => {
+      addLog(module, 'performance', {
+        operation,
+        duration,
+        threshold
+      });
+      console.warn(`⚠️ [${module}] Slow ${operation}: ${duration.toFixed(2)}ms (threshold: ${threshold}ms)`);
+    },
+    exportLogs: () => [...logs]
+  };
+}
+function createModularMetrics() {
+  const metricsSignal = signal({
+    totalUpdates: 0,
+    moduleUpdates: {},
+    modulePerformance: {},
+    compositionChain: [],
+    signalGrowth: {},
+    memoryDelta: {},
+    moduleCacheStats: {}
+  });
+  return {
+    signal: metricsSignal.asReadonly(),
+    updateMetrics: updates => {
+      metricsSignal.update(current => ({
+        ...current,
+        ...updates
+      }));
+    },
+    trackModuleUpdate: (module, duration) => {
+      metricsSignal.update(current => ({
+        ...current,
+        totalUpdates: current.totalUpdates + 1,
+        moduleUpdates: {
+          ...current.moduleUpdates,
+          [module]: (current.moduleUpdates[module] || 0) + 1
+        },
+        modulePerformance: {
+          ...current.modulePerformance,
+          [module]: duration
+        }
+      }));
+    }
+  };
+}
+function withDevTools(config = {}) {
+  const {
+    enabled = true,
+    treeName = 'ModularSignalTree',
+    enableBrowserDevTools = true,
+    enableLogging = true,
+    performanceThreshold = 16
+  } = config;
+  return tree => {
+    if (!enabled) {
+      const createNoopInterface = () => ({
+        activityTracker: {
+          trackMethodCall: () => undefined,
+          trackError: () => undefined,
+          getModuleActivity: () => undefined,
+          getAllModules: () => []
+        },
+        logger: {
+          logComposition: () => undefined,
+          logMethodExecution: () => undefined,
+          logStateChange: () => undefined,
+          logPerformanceWarning: () => undefined,
+          exportLogs: () => []
+        },
+        metrics: signal({
+          totalUpdates: 0,
+          moduleUpdates: {},
+          modulePerformance: {},
+          compositionChain: [],
+          signalGrowth: {},
+          memoryDelta: {},
+          moduleCacheStats: {}
+        }).asReadonly(),
+        trackComposition: () => undefined,
+        startModuleProfiling: () => '',
+        endModuleProfiling: () => undefined,
+        connectDevTools: () => undefined,
+        exportDebugSession: () => ({
+          metrics: {
+            totalUpdates: 0,
+            moduleUpdates: {},
+            modulePerformance: {},
+            compositionChain: [],
+            signalGrowth: {},
+            memoryDelta: {},
+            moduleCacheStats: {}
+          },
+          modules: [],
+          logs: [],
+          compositionHistory: []
+        })
+      });
+      return Object.assign(tree, {
+        __devTools: createNoopInterface()
+      });
+    }
+    const activityTracker = createActivityTracker();
+    const logger = enableLogging ? createCompositionLogger() : {
+      logComposition: () => undefined,
+      logMethodExecution: () => undefined,
+      logStateChange: () => undefined,
+      logPerformanceWarning: () => undefined,
+      exportLogs: () => []
+    };
+    const metrics = createModularMetrics();
+    const compositionHistory = [];
+    const activeProfiles = new Map();
+    let browserDevTools = null;
+    if (enableBrowserDevTools && typeof window !== 'undefined' && '__REDUX_DEVTOOLS_EXTENSION__' in window) {
+      const devToolsExt = window['__REDUX_DEVTOOLS_EXTENSION__'];
+      const connection = devToolsExt.connect({
+        name: treeName,
+        features: {
+          dispatch: true,
+          jump: true,
+          skip: true
+        }
+      });
+      browserDevTools = {
+        send: connection.send
+      };
+    }
+    const originalTreeCall = tree.bind(tree);
+    const enhancedTree = function (...args) {
+      if (args.length === 0) {
+        return originalTreeCall();
+      } else {
+        const startTime = performance.now();
+        let result;
+        if (args.length === 1) {
+          const arg = args[0];
+          if (typeof arg === 'function') {
+            result = originalTreeCall(arg);
+          } else {
+            result = originalTreeCall(arg);
+          }
+        }
+        const duration = performance.now() - startTime;
+        const newState = originalTreeCall();
+        metrics.trackModuleUpdate('core', duration);
+        if (duration > performanceThreshold) {
+          logger.logPerformanceWarning('core', 'update', duration, performanceThreshold);
+        }
+        if (browserDevTools) {
+          browserDevTools.send('UPDATE', newState);
+        }
+        return result;
+      }
+    };
+    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+    Object.assign(enhancedTree, tree);
+    if ('state' in tree) {
+      Object.defineProperty(enhancedTree, 'state', {
+        value: tree.state,
+        enumerable: false,
+        configurable: true
+      });
+    }
+    if ('$' in tree) {
+      Object.defineProperty(enhancedTree, '$', {
+        value: tree['$'],
+        enumerable: false,
+        configurable: true
+      });
+    }
+    const devToolsInterface = {
+      activityTracker,
+      logger,
+      metrics: metrics.signal,
+      trackComposition: modules => {
+        compositionHistory.push({
+          timestamp: new Date(),
+          chain: [...modules]
+        });
+        metrics.updateMetrics({
+          compositionChain: modules
+        });
+        logger.logComposition(modules, 'with');
+      },
+      startModuleProfiling: module => {
+        const profileId = `${module}_${Date.now()}`;
+        activeProfiles.set(profileId, {
+          module,
+          operation: 'profile',
+          startTime: performance.now()
+        });
+        return profileId;
+      },
+      endModuleProfiling: profileId => {
+        const profile = activeProfiles.get(profileId);
+        if (profile) {
+          const duration = performance.now() - profile.startTime;
+          activityTracker.trackMethodCall(profile.module, profile.operation, duration);
+          activeProfiles.delete(profileId);
+        }
+      },
+      connectDevTools: name => {
+        if (browserDevTools) {
+          browserDevTools.send('@@INIT', originalTreeCall());
+          console.log(`🔗 Connected to Redux DevTools as "${name}"`);
+        }
+      },
+      exportDebugSession: () => ({
+        metrics: metrics.signal(),
+        modules: activityTracker.getAllModules(),
+        logs: logger.exportLogs(),
+        compositionHistory: [...compositionHistory]
+      })
+    };
+    return Object.assign(enhancedTree, {
+      __devTools: devToolsInterface
+    });
+  };
+}
+function enableDevTools(treeName = 'SignalTree') {
+  return withDevTools({
+    treeName,
+    enabled: true
+  });
+}
+function withFullDevTools(treeName = 'SignalTree') {
+  return withDevTools({
+    treeName,
+    enabled: true,
+    enableBrowserDevTools: true,
+    enableLogging: true,
+    performanceThreshold: 10
+  });
+}
+function withProductionDevTools() {
+  return withDevTools({
+    enabled: true,
+    enableBrowserDevTools: false,
+    enableLogging: false,
+    performanceThreshold: 50
+  });
+}
+
+export { enableDevTools, withDevTools, withFullDevTools, withProductionDevTools };