@signaltree/core 7.6.0 → 8.0.0

package/README.md

@@ -118,7 +118,7 @@ Performance and bundle size vary by app shape, build tooling, device, and runtim
 
 ## Best Practices (SignalTree-First)
 
-> 📖 **Full guide**: [Implementation Patterns](https://github.com/JBorgia/signaltree/blob/main/docs/IMPLEMENTATION_PATTERNS.md)
+> 📖 **Full guide**: [Architecture Guide](https://github.com/JBorgia/signaltree/blob/main/docs/architecture/signaltree-architecture-guide.md)
 
 Follow these principles for idiomatic SignalTree code:
 
@@ -164,7 +164,7 @@ export function createUserTree() {
 // ✅ Correct: Derived from multiple signals
 const selectedUser = computed(() => {
   const id = $.selected.userId();
-  return id ? $.users.byId(id)() : null;
+  return id ? $.users.byId(id)?.() ?? null : null;
 });
 
 // ❌ Wrong: Wrapping an existing signal
@@ -175,8 +175,8 @@ const selectedUserId = computed(() => $.selected.userId()); // Unnecessary!
 
 ```typescript
 // ✅ SignalTree-native
-const user = $.users.byId(123)(); // O(1) lookup
-const allUsers = $.users.all; // Get all
+const user = $.users.byId(123)?.(); // O(1) lookup
+const allUsers = $.users.all(); // Get all
 $.users.setAll(usersFromApi); // Replace all
 
 // ❌ NgRx-style (avoid)
@@ -650,7 +650,7 @@ All enhancers are exported directly from `@signaltree/core`:
 
 **Data Management:**
 
-- `entities()` - Advanced CRUD operations for collections
+- `entities()` - Legacy helper (not required when using `entityMap()` in v7)
 - `createAsyncOperation()` - Async operation management with loading/error states
 - `trackAsync()` - Track async operations in your state
 - `serialization()` - State persistence and SSR support
@@ -658,9 +658,15 @@ All enhancers are exported directly from `@signaltree/core`:
 
 **Development Tools:**
 
-- `devTools()` - Redux DevTools integration
+- `devTools()` - Redux DevTools auto-connect, path actions, and time-travel dispatch
 - `withTimeTravel()` - Undo/redo functionality
 
+**DevTools connection model**
+
+`devTools()` connects to the Redux DevTools browser extension via `window.__REDUX_DEVTOOLS_EXTENSION__.connect(...)`. That means **each SignalTree instance you enhance with `devTools()` will show up as its own DevTools “instance”.**
+
+If you want a single unified DevTools view, prefer a **single global tree** composed from domain slices, and apply `devTools()` once at the root. See the Architecture Guide (Category C: Feature-scoped / composed sub-trees) for patterns that keep code modular without fragmenting runtime state.
+
 **Presets:**
 
 - `createDevTree()` - Pre-configured development setup
@@ -691,14 +697,12 @@ const tree = signalTree({ count: 0 }).with(
 **Performance-Focused Stack:**
 
 ```typescript
-import { signalTree, batching, memoization, entities } from '@signaltree/core';
+import { signalTree, batching, memoization, entityMap } from '@signaltree/core';
 
 const tree = signalTree({
   products: entityMap<Product>(),
   ui: { loading: false },
-})
-  .with(entities()) // Efficient CRUD operations (auto-detects entityMap)
-  .with(batching()); // Batch updates for optimal rendering
+}).with(batching()); // Batch updates for optimal rendering
 
 // Entity CRUD operations
 tree.$.products.addOne(newProduct);
@@ -748,6 +752,8 @@ tree.undo(); // Revert changes
 
 #### Enhancer Metadata & Ordering
 
+Derived computed signals are preserved across `.with()` chaining, so enhancer composition does not recreate signal identities.
+
 Enhancers can declare metadata for automatic dependency resolution:
 
 ```typescript
@@ -782,20 +788,20 @@ const customTree = signalTree(state, TREE_PRESETS.DASHBOARD);
 SignalTree Core includes all enhancer functionality built-in. No separate packages needed:
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
 // Without entityMap - use manual array updates
 const basic = signalTree({ users: [] as User[] });
 basic.$.users.update((users) => [...users, newUser]);
 
-// With entityMap + entities - use entity helpers
+// With entityMap (v7+ auto-processed) - use entity helpers
 const enhanced = signalTree({
   users: entityMap<User>(),
-}).with(entities());
+});
 
 enhanced.$.users.addOne(newUser); // ✅ Advanced CRUD operations
-enhanced.$.users.byId(123)(); // ✅ O(1) lookups
-enhanced.$.users.all; // ✅ Get all as array
+enhanced.$.users.byId(123)?.(); // ✅ O(1) lookups
+enhanced.$.users.all(); // ✅ Get all as array
 ```
 
 Core includes several performance optimizations:
@@ -908,7 +914,7 @@ const tree = signalTree({ count: 0 }).with(withLogger());
 tree.log('Tree created');
 ```
 
-> 📖 **Full guide**: [Custom Markers & Enhancers](https://github.com/JBorgia/signaltree/blob/main/docs/custom-markers-enhancers.md)
+> 📖 **Full guide**: [Custom Markers & Enhancers](https://github.com/JBorgia/signaltree/blob/main/docs/guides/custom-markers-enhancers.md)
 >
 > 📱 **Interactive demo**: [Demo App](/custom-extensions)
 
@@ -1574,19 +1580,19 @@ const filteredProducts = computed(() => {
 ### Data Management Composition
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
-// Add data management capabilities (+2.77KB total)
+// Add data management capabilities (entityMap is auto-processed)
 const tree = signalTree({
   users: entityMap<User>(),
   posts: entityMap<Post>(),
   ui: { loading: false, error: null as string | null },
-}).with(entities());
+});
 
 // Advanced entity operations via tree.$ accessor
 tree.$.users.addOne(newUser);
-tree.$.users.selectBy((u) => u.active);
-tree.$.users.updateMany([{ id: '1', changes: { status: 'active' } }]);
+tree.$.users.where((u) => u.active); // Filtered signal
+tree.$.users.updateMany(['1'], { status: 'active' });
 
 // Entity helpers work with nested structures
 // Example: deeply nested entities in a domain-driven design pattern
@@ -1603,13 +1609,13 @@ const appTree = signalTree({
       reports: entityMap<Report>(),
     },
   },
-}).with(entities());
+});
 
 // Access nested entities using tree.$ accessor
-appTree.$.app.data.users.selectBy((u) => u.isAdmin); // Filtered signal
-appTree.$.app.data.products.selectTotal(); // Count signal
-appTree.$.admin.data.logs.all; // All items as array
-appTree.$.admin.data.reports.selectIds(); // ID array signal
+appTree.$.app.data.users.where((u) => u.isAdmin); // Filtered signal
+appTree.$.app.data.products.count(); // Count
+appTree.$.admin.data.logs.all(); // All items as array
+appTree.$.admin.data.reports.ids(); // ID array
 
 // For async operations, use manual async or async helpers
 async function fetchUsers() {
@@ -1628,7 +1634,7 @@ async function fetchUsers() {
 ### Full-Featured Development Composition
 
 ```typescript
-import { signalTree, batching, entities, serialization, withTimeTravel, devTools } from '@signaltree/core';
+import { signalTree, batching, serialization, withTimeTravel, devTools } from '@signaltree/core';
 
 // Full development stack (example)
 const tree = signalTree({
@@ -1639,7 +1645,6 @@ const tree = signalTree({
   },
 }).with(
   batching(), // Performance
-  entities(), // Data management
   // withAsync removed — use async helpers for API integration
   serialization({
     // State persistence
@@ -1653,7 +1658,9 @@ const tree = signalTree({
   devTools({
     // Debug tools (dev only)
     name: 'MyApp',
-    trace: true,
+    enableTimeTravel: true,
+    includePaths: ['app.*', 'ui.*'],
+    formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
   })
 );
 
@@ -1661,7 +1668,7 @@ const tree = signalTree({
 async function fetchUser(id: string) {
   return await api.getUser(id);
 }
-tree.$.app.data.users.byId(userId)(); // O(1) lookup
+tree.$.app.data.users.byId(userId)?.(); // O(1) lookup
 tree.undo(); // Time travel
 tree.save(); // Persistence
 ```
@@ -1669,12 +1676,11 @@ tree.save(); // Persistence
 ### Production-Ready Composition
 
 ```typescript
-import { signalTree, batching, entities, serialization } from '@signaltree/core';
+import { signalTree, batching, serialization } from '@signaltree/core';
 
 // Production build (no dev tools)
 const tree = signalTree(initialState).with(
   batching(), // Performance optimization
-  entities(), // Data management
   // withAsync removed — use async helpers for API integration
   serialization({
     // User preferences
@@ -1690,14 +1696,13 @@ const tree = signalTree(initialState).with(
 ### Conditional Enhancement
 
 ```typescript
-import { signalTree, batching, entities, devTools, withTimeTravel } from '@signaltree/core';
+import { signalTree, batching, devTools, withTimeTravel } from '@signaltree/core';
 
 const isDevelopment = process.env['NODE_ENV'] === 'development';
 
 // Conditional enhancement based on environment
 const tree = signalTree(state).with(
   batching(), // Always include performance
-  entities(), // Always include data management
   ...(isDevelopment
     ? [
         // Development-only features
@@ -1742,7 +1747,7 @@ const tree = signalTree(state);
 const tree2 = tree.with(batching());
 
 // Phase 3: Add data management for collections
-const tree3 = tree2.with(entities());
+const tree3 = tree2; // entityMap is auto-processed in v7
 
 // Phase 4: Add async for API integration
 // withAsync removed — no explicit async enhancer; use async helpers instead
@@ -1820,7 +1825,7 @@ For fair, reproducible measurements that reflect your app and hardware, use the
           {{ userTree.$.error() }}
           <button (click)="loadUsers()">Retry</button>
         </div>
-        } @else { @for (user of users.selectAll()(); track user.id) {
+        } @else { @for (user of users(); track user.id) {
         <div class="user-card">
           <h3>{{ user.name }}</h3>
           <p>{{ user.email }}</p>
@@ -1848,6 +1853,8 @@ class UserManagerComponent implements OnInit {
     form: { id: '', name: '', email: '' },
   });
 
+  readonly users = this.userTree.$.users;
+
   constructor(private userService: UserService) {}
 
   ngOnInit() {
@@ -2032,9 +2039,9 @@ tree.destroy(); // Cleanup resources
 
 // Entity helpers (when using entityMap + entities)
 // tree.$.users.addOne(user);    // Add single entity
-// tree.$.users.byId(id)();      // O(1) lookup by ID
-// tree.$.users.all;         // Get all as array
-// tree.$.users.selectBy(pred);  // Filtered signal
+// tree.$.users.byId(id)?.();      // O(1) lookup by ID
+// tree.$.users.all();             // Get all as array
+// tree.$.users.where(pred)();     // Filtered array
 ```
 
 ## Extending with enhancers
@@ -2054,8 +2061,8 @@ All enhancers are included in `@signaltree/core`:
 
 - **batching()** - Batch multiple updates for better performance
 - **memoization()** - Intelligent caching & performance optimization
-- **entities()** - Advanced entity management & CRUD operations
-- **devTools()** - Redux DevTools integration for debugging
+- **entities()** - Legacy helper (not required when using `entityMap()` in v7)
+- **devTools()** - Auto-connect, path actions, and time-travel dispatch
 - **withTimeTravel()** - Undo/redo functionality & state history
 - **serialization()** - State persistence & SSR support
 - **createDevTree()** - Pre-configured development setup
@@ -2210,11 +2217,11 @@ All enhancers are now consolidated in the core package. The following features a
 
 ### Advanced Features
 
-- **entities()** (+0.97KB gzipped) - Enhanced CRUD operations & entity management
+- **entities()** (+0.97KB gzipped) - Legacy helper (not required when using `entityMap()` in v7)
 
 ### Development Tools
 
-- **devTools()** (+2.49KB gzipped) - Development tools & Redux DevTools integration
+- **devTools()** (+2.49KB gzipped) - Auto-connect, path actions, and time-travel dispatch
 - **withTimeTravel()** (+1.75KB gzipped) - Undo/redo functionality & state history
 
 ### Integration & Convenience

package/dist/enhancers/devtools/devtools.js

@@ -216,7 +216,7 @@ function sanitizeState(value, options, depth = 0, seen = new WeakSet()) {
   if (typeof value === 'number' || typeof value === 'boolean') return value;
   if (typeof value === 'bigint') return `${value.toString()}n`;
   if (typeof value === 'symbol') return String(value);
-  if (typeof value === 'function') return '[Function]';
+  if (typeof value === 'function') return undefined;
   if (depth >= maxDepth) return '[MaxDepth]';
   if (value instanceof Date) return value.toISOString();
   if (value instanceof RegExp) return value.toString();
@@ -245,6 +245,7 @@ function sanitizeState(value, options, depth = 0, seen = new WeakSet()) {
     }
     const result = {};
     for (const [key, val] of Object.entries(obj)) {
+      if (typeof val === 'function') continue;
       result[key] = sanitizeState(val, options, depth + 1, seen);
     }
     return result;
@@ -299,6 +300,7 @@ function devTools(config = {}) {
       logger.logComposition(modules, 'with');
     };
     const activeProfiles = new Map();
+    let browserDevToolsConnection = null;
     let browserDevTools = null;
     let isConnected = false;
     let isApplyingExternalState = false;
@@ -374,7 +376,7 @@ function devTools(config = {}) {
         lastSnapshot = currentSnapshot;
         return;
       }
-      const effectiveAction = pendingExplicitAction ? pendingAction : formattedPaths.length === 1 ? buildAction(`SignalTree/${formattedPaths[0]}`, formattedPaths[0]) : formattedPaths.length > 1 ? buildAction('SignalTree/batch', formattedPaths) : buildAction('SignalTree/update');
+      const effectiveAction = pendingExplicitAction ? pendingAction : formattedPaths.length === 1 ? buildAction(`SignalTree/${formattedPaths[0]}`, formattedPaths[0]) : formattedPaths.length > 1 ? buildAction('SignalTree/update', formattedPaths) : buildAction('SignalTree/update');
       const actionMeta = {
         timestamp: Date.now(),
         ...(pendingSource && {
@@ -521,15 +523,20 @@ function devTools(config = {}) {
             skip: true
           }
         });
+        browserDevToolsConnection = connection;
         browserDevTools = {
           send: connection.send,
           subscribe: connection.subscribe
         };
         if (browserDevTools.subscribe && !unsubscribeDevTools) {
-          browserDevTools.subscribe(handleDevToolsMessage);
-          unsubscribeDevTools = () => {
-            browserDevTools?.subscribe?.(() => void 0);
-          };
+          const maybeUnsubscribe = browserDevTools.subscribe(handleDevToolsMessage);
+          if (typeof maybeUnsubscribe === 'function') {
+            unsubscribeDevTools = maybeUnsubscribe;
+          } else {
+            unsubscribeDevTools = () => {
+              browserDevTools?.subscribe?.(() => void 0);
+            };
+          }
         }
         const rawSnapshot = readSnapshot();
         const sanitized = buildSerializedState(rawSnapshot);
@@ -652,7 +659,17 @@ function devTools(config = {}) {
         initBrowserDevTools();
       },
       disconnectDevTools() {
+        try {
+          unsubscribeDevTools?.();
+        } catch {}
+        try {
+          browserDevToolsConnection?.unsubscribe?.();
+        } catch {}
+        try {
+          browserDevToolsConnection?.disconnect?.();
+        } catch {}
         browserDevTools = null;
+        browserDevToolsConnection = null;
         isConnected = false;
         if (unsubscribeNotifier) {
           unsubscribeNotifier();
@@ -662,10 +679,7 @@ function devTools(config = {}) {
           unsubscribeFlush();
           unsubscribeFlush = null;
         }
-        if (unsubscribeDevTools) {
-          unsubscribeDevTools();
-          unsubscribeDevTools = null;
-        }
+        unsubscribeDevTools = null;
         if (effectRef) {
           effectRef.destroy();
           effectRef = null;

package/dist/lib/utils.js

@@ -180,6 +180,8 @@ function unwrap(node) {
         } else {
           result[key] = unwrappedValue;
         }
+      } else if (typeof value === 'function') {
+        continue;
       } else if (typeof value === 'object' && value !== null && !Array.isArray(value) && !isBuiltInObject(value)) {
         result[key] = unwrap(value);
       } else {
@@ -212,6 +214,9 @@ function unwrap(node) {
       if (typeof v === 'function') continue;
     }
     const value = node[key];
+    if (typeof value === 'function' && !isNodeAccessor(value) && !isSignal(value)) {
+      continue;
+    }
     if (isNodeAccessor(value)) {
       const unwrappedValue = value();
       if (typeof unwrappedValue === 'object' && unwrappedValue !== null && !Array.isArray(unwrappedValue) && !isBuiltInObject(unwrappedValue)) {
@@ -235,6 +240,9 @@ function unwrap(node) {
   const symbols = Object.getOwnPropertySymbols(node);
   for (const sym of symbols) {
     const value = node[sym];
+    if (typeof value === 'function' && !isNodeAccessor(value) && !isSignal(value)) {
+      continue;
+    }
     if (isNodeAccessor(value)) {
       const unwrappedValue = value();
       if (typeof unwrappedValue === 'object' && unwrappedValue !== null && !Array.isArray(unwrappedValue) && !isBuiltInObject(unwrappedValue)) {
@@ -263,6 +271,12 @@ function snapshotState(state) {
 function applyState(stateNode, snapshot) {
   if (snapshot === null || snapshot === undefined) return;
   if (typeof snapshot !== 'object') return;
+  if (stateNode && typeof stateNode === 'object' && typeof stateNode.setAll === 'function' && snapshot && typeof snapshot === 'object' && Array.isArray(snapshot.all)) {
+    try {
+      stateNode.setAll(snapshot.all);
+      return;
+    } catch {}
+  }
   for (const key of Object.keys(snapshot)) {
     const val = snapshot[key];
     const target = stateNode[key];
@@ -288,6 +302,14 @@ function applyState(stateNode, snapshot) {
           target(val);
         } catch {}
       }
+    } else if (target && typeof target === 'object' && val && typeof val === 'object' && !Array.isArray(target) && !Array.isArray(val)) {
+      try {
+        applyState(target, val);
+      } catch {
+        try {
+          stateNode[key] = val;
+        } catch {}
+      }
     } else {
       try {
         stateNode[key] = val;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "7.6.0",
+  "version": "8.0.0",
   "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",

package/src/lib/utils.d.ts

@@ -1,5 +1,4 @@
 import { WritableSignal } from '@angular/core';
-import { deepEqual, isBuiltInObject, parsePath } from '@signaltree/shared';
 export { deepEqual };
 export { deepEqual as equal };
 export { isBuiltInObject };
@@ -11,6 +10,26 @@ export interface MemoryManager {
     dispose(): void;
 }
 import type { NodeAccessor, TreeNode } from './types';
+
+// Inlined from @signaltree/shared (internal package)
+declare function deepEqual<T>(a: T, b: T): boolean;
+declare function deepClone<T>(obj: T): T;
+declare function isBuiltInObject(value: unknown): boolean;
+declare function parsePath(path: string): string[];
+declare function matchPath(path: string[], pattern: string[]): boolean;
+declare function mergeDeep<T>(target: T, source: unknown): T;
+declare function snapshotsEqual<T>(a: T, b: T): boolean;
+declare function getChanges<T>(prev: T, next: T): unknown;
+declare class LRUCache<K, V> {
+  constructor(maxSize: number);
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  has(key: K): boolean;
+  delete(key: K): boolean;
+  clear(): void;
+  get size(): number;
+}
+declare const DEFAULT_PATH_CACHE_SIZE: number;
 export declare function isNodeAccessor(value: unknown): value is NodeAccessor<unknown>;
 export declare function isAnySignal(value: unknown): boolean;
 export declare function toWritableSignal<T>(node: NodeAccessor<T>, injector?: unknown): WritableSignal<T>;