@signaltree/core 7.1.3 → 7.1.4

package/README.md

@@ -2,19 +2,34 @@
   <img src="https://raw.githubusercontent.com/JBorgia/signaltree/main/apps/demo/public/signaltree.svg" alt="SignalTree Logo" width="60" height="60" />
 </div>
 
-# SignalTree Core
+# SignalTree: Reactive JSON
 
-Foundation package for SignalTree. Provides recursive typing, deep nesting support, and strong performance.
+**JSON branches, reactive leaves.**
+
+> No actions. No reducers. No selectors.
 
 ## What is @signaltree/core?
 
-SignalTree Core is a lightweight package that provides:
+SignalTree treats application state as **reactive JSON** — a typed, dot-notation interface to plain JSON-like objects with fine-grained reactivity layered transparently on top.
+
+You don't model state as actions, reducers, selectors, or classes — you model it as **data**.
+
+### Core Philosophy
+
+| Principle                | What It Means                                                                |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| **State is Data**        | Your state shape looks like JSON. No ceremony, no abstractions.              |
+| **Dot-Notation Access**  | `tree.$.user.profile.name()` — fully type-safe, IDE-discoverable             |
+| **Invisible Reactivity** | You think in data paths, not subscriptions. Reactivity emerges naturally.    |
+| **Lazy by Design**       | Signals created only where accessed. Types do heavy lifting at compile time. |
+
+### Technical Features
 
 - Recursive typing with deep nesting and accurate type inference
 - Fast operations with sub‑millisecond measurements at 5–20+ levels
 - Strong TypeScript safety across nested structures
 - Memory efficiency via structural sharing and lazy signals
-- Small API surface with zero-cost abstractions
+- Small API surface with minimal runtime overhead
 - Compact bundle size suited for production
 
 ## Import guidance (tree-shaking)
@@ -936,7 +951,7 @@ For larger applications, you may want to organize derived tiers into separate fi
 
 SignalTree provides two utilities for external derived functions:
 
-- **`externalDerived<TTree>()`** - Curried helper function that provides type context for your derived function
+- **`derivedFrom<TTree>()`** - Curried helper function that provides type context for your derived function
 - **`WithDerived<TTree, TDerivedFn>`** - Type utility to build intermediate tree types
 
 ```typescript
@@ -967,11 +982,11 @@ export function createAppTree() {
 ```typescript
 // derived/tier-entity-resolution.ts
 import { computed } from '@angular/core';
-import { externalDerived } from '@signaltree/core';
+import { derivedFrom } from '@signaltree/core';
 import type { AppTreeBase } from '../app-tree';
 
-// externalDerived provides the type context for $ via curried syntax
-export const entityResolutionDerived = externalDerived<AppTreeBase>()(($) => ({
+// derivedFrom provides the type context for $ via curried syntax
+export const entityResolutionDerived = derivedFrom<AppTreeBase>()(($) => ({
   selectedUser: computed(() => {
     const id = $.selectedUserId();
     return id != null ? $.users.byId(id)?.() ?? null : null;
@@ -982,11 +997,11 @@ export const entityResolutionDerived = externalDerived<AppTreeBase>()(($) => ({
 ```typescript
 // derived/tier-complex-logic.ts
 import { computed } from '@angular/core';
-import { externalDerived } from '@signaltree/core';
+import { derivedFrom } from '@signaltree/core';
 import type { AppTreeWithTier1 } from '../app-tree';
 
 // This tier has access to $.selectedUser from Tier 1
-export const complexLogicDerived = externalDerived<AppTreeWithTier1>()(($) => ({
+export const complexLogicDerived = derivedFrom<AppTreeWithTier1>()(($) => ({
   isAdmin: computed(() => $.selectedUser()?.role === 'admin'),
   displayName: computed(() => {
     const user = $.selectedUser();
@@ -1006,13 +1021,13 @@ export function myDerived($) {
   return { foo: computed(() => $.bar()) }; // Error: $ has no properties
 }
 
-// ✅ externalDerived provides the type context (curried syntax)
-export const myDerived = externalDerived<AppTreeBase>()(($) => ({
+// ✅ derivedFrom provides the type context (curried syntax)
+export const myDerived = derivedFrom<AppTreeBase>()(($) => ({
   foo: computed(() => $.bar()), // $ is properly typed
 }));
 ```
 
-**Key point**: `externalDerived` is **only needed for functions defined in separate files**. Inline functions automatically inherit types from the chain. Note the curried syntax: `externalDerived<TreeType>()(fn)` - this allows TypeScript to infer the return type while you specify the tree type.
+**Key point**: `derivedFrom` is **only needed for functions defined in separate files**. Inline functions automatically inherit types from the chain. Note the curried syntax: `derivedFrom<TreeType>()(fn)` - this allows TypeScript to infer the return type while you specify the tree type.
 
 ## Error handling examples
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/core",
-  "version": "7.1.3",
-  "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
+  "version": "7.1.4",
+  "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,

package/dist/constants.js

@@ -1,6 +0,0 @@
-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-equal.js

@@ -1,41 +0,0 @@
-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/batching.js

@@ -1,230 +0,0 @@
-import { copyTreeProperties } from '../utils/copy-tree-properties.js';
-
-function batching(config = {}) {
-  const enabled = config.enabled ?? true;
-  const notificationDelayMs = config.notificationDelayMs ?? 0;
-  return tree => {
-    if (!enabled) {
-      const passthrough = {
-        batch: fn => fn(),
-        coalesce: fn => fn(),
-        hasPendingNotifications: () => false,
-        flushNotifications: () => {}
-      };
-      const enhanced = tree;
-      Object.assign(enhanced, passthrough);
-      enhanced.batchUpdate = updater => {
-        if (typeof tree.batchUpdate === 'function') {
-          tree.batchUpdate(updater);
-        } else {
-          updater(tree());
-        }
-      };
-      return enhanced;
-    }
-    let notificationPending = false;
-    let notificationTimeoutId;
-    let inBatch = false;
-    let inCoalesce = false;
-    const coalescedUpdates = new Map();
-    const scheduleNotification = () => {
-      if (notificationPending) return;
-      notificationPending = true;
-      if (notificationDelayMs > 0) {
-        notificationTimeoutId = setTimeout(flushNotificationsInternal, notificationDelayMs);
-      } else {
-        queueMicrotask(flushNotificationsInternal);
-      }
-    };
-    const flushNotificationsInternal = () => {
-      if (!notificationPending) return;
-      notificationPending = false;
-      if (notificationTimeoutId !== undefined) {
-        clearTimeout(notificationTimeoutId);
-        notificationTimeoutId = undefined;
-      }
-      if (tree.__notifyChangeDetection) {
-        tree.__notifyChangeDetection();
-      }
-    };
-    const flushCoalescedUpdates = () => {
-      const updates = Array.from(coalescedUpdates.values());
-      coalescedUpdates.clear();
-      updates.forEach(fn => {
-        try {
-          fn();
-        } catch (e) {
-          console.error('[SignalTree] Error in coalesced update:', e);
-        }
-      });
-    };
-    const wrapSignalSetters = (node, path = '') => {
-      if (!node || typeof node !== 'object') return;
-      if (typeof node.set === 'function' && !node.__batchingWrapped) {
-        const originalSet = node.set.bind(node);
-        node.set = value => {
-          if (inCoalesce) {
-            coalescedUpdates.set(path, () => originalSet(value));
-          } else {
-            originalSet(value);
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        };
-        node.__batchingWrapped = true;
-      }
-      if (typeof node.update === 'function' && !node.__batchingUpdateWrapped) {
-        const originalUpdate = node.update.bind(node);
-        node.update = updater => {
-          if (inCoalesce) {
-            coalescedUpdates.set(`${path}:update:${Date.now()}`, () => originalUpdate(updater));
-          } else {
-            originalUpdate(updater);
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        };
-        node.__batchingUpdateWrapped = true;
-      }
-      for (const key of Object.keys(node)) {
-        if (key.startsWith('_') || key === 'set' || key === 'update') continue;
-        const child = node[key];
-        if (child && typeof child === 'object') {
-          wrapSignalSetters(child, path ? `${path}.${key}` : key);
-        }
-      }
-    };
-    if (tree.$) {
-      wrapSignalSetters(tree.$);
-    }
-    const batchingMethods = {
-      batch(fn) {
-        const wasBatching = inBatch;
-        inBatch = true;
-        try {
-          fn();
-        } finally {
-          inBatch = wasBatching;
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        }
-      },
-      coalesce(fn) {
-        const wasCoalescing = inCoalesce;
-        const wasBatching = inBatch;
-        inCoalesce = true;
-        inBatch = true;
-        try {
-          fn();
-        } finally {
-          inCoalesce = wasCoalescing;
-          inBatch = wasBatching;
-          if (!wasCoalescing) {
-            flushCoalescedUpdates();
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        }
-      },
-      hasPendingNotifications() {
-        return notificationPending;
-      },
-      flushNotifications() {
-        flushNotificationsInternal();
-      }
-    };
-    const originalTreeCall = tree.bind(tree);
-    const enhancedTree = function (...args) {
-      if (args.length === 0) {
-        return originalTreeCall();
-      } else {
-        if (args.length === 1) {
-          const arg = args[0];
-          if (typeof arg === 'function') {
-            originalTreeCall(arg);
-          } else {
-            originalTreeCall(arg);
-          }
-        }
-        if (!inBatch) {
-          scheduleNotification();
-        }
-      }
-    };
-    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
-    Object.assign(enhancedTree, tree);
-    try {
-      copyTreeProperties(tree, enhancedTree);
-    } catch {}
-    Object.defineProperty(enhancedTree, 'with', {
-      value: function (enhancer) {
-        if (typeof enhancer !== 'function') {
-          throw new Error('Enhancer must be a function');
-        }
-        return enhancer(enhancedTree);
-      },
-      writable: false,
-      enumerable: false,
-      configurable: true
-    });
-    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
-      });
-    }
-    Object.assign(enhancedTree, batchingMethods);
-    enhancedTree.batchUpdate = updater => {
-      enhancedTree.batch(() => {
-        const current = originalTreeCall();
-        const updates = updater(current);
-        Object.entries(updates).forEach(([key, value]) => {
-          const property = enhancedTree.state[key];
-          if (property && typeof property.set === 'function') {
-            property.set(value);
-          } else if (typeof property === 'function') {
-            property(value);
-          }
-        });
-      });
-    };
-    return enhancedTree;
-  };
-}
-function highPerformanceBatching() {
-  return batching({
-    enabled: true,
-    notificationDelayMs: 0
-  });
-}
-function batchingWithConfig(config = {}) {
-  return batching(config);
-}
-function flushBatchedUpdates() {
-  console.warn('[SignalTree] flushBatchedUpdates() is deprecated. Use tree.flushNotifications() instead.');
-}
-function hasPendingUpdates() {
-  console.warn('[SignalTree] hasPendingUpdates() is deprecated. Use tree.hasPendingNotifications() instead.');
-  return false;
-}
-function getBatchQueueSize() {
-  console.warn('[SignalTree] getBatchQueueSize() is deprecated. Signal writes are now synchronous.');
-  return 0;
-}
-Object.assign((config = {}) => batching(config), {
-  highPerformance: highPerformanceBatching
-});
-
-export { batching, batchingWithConfig, flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, highPerformanceBatching };

package/dist/enhancers/devtools/devtools.js

@@ -1,318 +0,0 @@
-import { signal } from '@angular/core';
-import { copyTreeProperties } from '../utils/copy-tree-properties.js';
-
-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 createNoopLogger() {
-  return {
-    logComposition: () => {},
-    logMethodExecution: () => {},
-    logStateChange: () => {},
-    logPerformanceWarning: () => {},
-    exportLogs: () => []
-  };
-}
-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 devTools(config = {}) {
-  const {
-    enabled = true,
-    treeName = 'SignalTree',
-    name,
-    enableBrowserDevTools = true,
-    enableLogging = true,
-    performanceThreshold = 16
-  } = config;
-  const displayName = name ?? treeName;
-  return tree => {
-    if (!enabled) {
-      const noopMethods = {
-        connectDevTools() {},
-        disconnectDevTools() {}
-      };
-      return Object.assign(tree, noopMethods);
-    }
-    const activityTracker = createActivityTracker();
-    const logger = enableLogging ? createCompositionLogger() : createNoopLogger();
-    const metrics = createModularMetrics();
-    const compositionHistory = [];
-    const activeProfiles = new Map();
-    let browserDevTools = null;
-    const initBrowserDevTools = () => {
-      if (!enableBrowserDevTools || typeof window === 'undefined' || !('__REDUX_DEVTOOLS_EXTENSION__' in window)) {
-        return;
-      }
-      try {
-        const devToolsExt = window['__REDUX_DEVTOOLS_EXTENSION__'];
-        const connection = devToolsExt.connect({
-          name: displayName,
-          features: {
-            dispatch: true,
-            jump: true,
-            skip: true
-          }
-        });
-        browserDevTools = {
-          send: connection.send
-        };
-        browserDevTools.send('@@INIT', tree());
-        console.log(`🔗 Connected to Redux DevTools as "${displayName}"`);
-      } catch (e) {
-        console.warn('[SignalTree] Failed to connect to Redux DevTools:', e);
-      }
-    };
-    const originalTreeCall = tree.bind(tree);
-    const enhancedTree = function (...args) {
-      if (args.length === 0) {
-        return originalTreeCall();
-      }
-      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));
-    copyTreeProperties(tree, enhancedTree);
-    Object.defineProperty(enhancedTree, 'with', {
-      value: function (enhancer) {
-        if (typeof enhancer !== 'function') {
-          throw new Error('Enhancer must be a function');
-        }
-        return enhancer(enhancedTree);
-      },
-      writable: false,
-      enumerable: false,
-      configurable: true
-    });
-    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]
-      })
-    };
-    const methods = {
-      connectDevTools() {
-        initBrowserDevTools();
-      },
-      disconnectDevTools() {
-        browserDevTools = null;
-      }
-    };
-    enhancedTree['__devTools'] = devToolsInterface;
-    return Object.assign(enhancedTree, methods);
-  };
-}
-function enableDevTools(treeName = 'SignalTree') {
-  return devTools({
-    treeName,
-    enabled: true
-  });
-}
-function fullDevTools(treeName = 'SignalTree') {
-  return devTools({
-    treeName,
-    enabled: true,
-    enableBrowserDevTools: true,
-    enableLogging: true,
-    performanceThreshold: 10
-  });
-}
-function productionDevTools() {
-  return devTools({
-    enabled: true,
-    enableBrowserDevTools: false,
-    enableLogging: false,
-    performanceThreshold: 50
-  });
-}
-Object.assign(devTools, {
-  production: productionDevTools,
-  full: fullDevTools,
-  enable: enableDevTools
-});
-
-export { devTools, enableDevTools, fullDevTools, productionDevTools };