@signaltree/core 5.1.1 → 5.1.3

package/README.md

@@ -81,6 +81,73 @@ Performance and bundle size vary by app shape, build tooling, device, and runtim
 - Use the **Benchmark Orchestrator** in the demo app to run calibrated, scenario-based benchmarks across supported libraries with **real-world frequency weighting**. It applies research-based multipliers derived from 40,000+ developer surveys and GitHub analysis, reports statistical summaries (median/p95/p99/stddev), alternates runs to reduce bias, and can export CSV/JSON. When available, memory usage is also reported.
 - Use the bundle analysis scripts in `scripts/` to measure your min+gz sizes. Sizes are approximate and depend on tree-shaking and configuration.
 
+## Best Practices (SignalTree-First)
+
+> 📖 **Full guide**: [Implementation Patterns](https://github.com/JBorgia/signaltree/blob/main/docs/IMPLEMENTATION_PATTERNS.md)
+
+Follow these principles for idiomatic SignalTree code:
+
+### 1. Expose signals directly (no computed wrappers)
+
+```typescript
+const tree = signalTree(initialState).with(withEntities());
+const $ = tree.$; // Shorthand for state access
+
+// ✅ SignalTree-first: Direct signal exposure
+return {
+  selectedUserId: $.selected.userId, // Direct from $ tree
+  loadingState: $.loading.state,
+  selectedUser, // Actual derived state (computed)
+};
+
+// ❌ Anti-pattern: Unnecessary computed wrappers
+return {
+  selectedUserId: computed(() => $.selected.userId()), // Adds indirection
+};
+```
+
+### 2. Use `ReturnType` inference (SignalTree-first)
+
+```typescript
+// Let SignalTree infer the type - no manual interface needed!
+import type { createUserTree } from './user.tree';
+export type UserTree = ReturnType<typeof createUserTree>;
+
+// Factory function - no explicit return type needed
+export function createUserTree() {
+  const tree = signalTree(initialState).with(withEntities());
+  return {
+    selectedUserId: tree.$.selected.userId, // Type inferred automatically
+    // ...
+  };
+}
+```
+
+### 3. Use `computed()` only for derived state
+
+```typescript
+// ✅ Correct: Derived from multiple signals
+const selectedUser = computed(() => {
+  const id = $.selected.userId();
+  return id ? $.users.byId(id)() : null;
+});
+
+// ❌ Wrong: Wrapping an existing signal
+const selectedUserId = computed(() => $.selected.userId()); // Unnecessary!
+```
+
+### 4. Use EntitySignal API directly
+
+```typescript
+// ✅ SignalTree-native
+const user = $.users.byId(123)(); // O(1) lookup
+const allUsers = $.users.all()(); // Get all
+$.users.setAll(usersFromApi); // Replace all
+
+// ❌ NgRx-style (avoid)
+const user = entityMap()[123]; // Requires intermediate object
+```
+
 ## Quick start
 
 ### Installation
@@ -552,22 +619,20 @@ const tree = signalTree({ count: 0 }).with(
 import { signalTree, withBatching, withMemoization, withEntities } from '@signaltree/core';
 
 const tree = signalTree({
-  products: [] as Product[],
+  products: entityMap<Product>(),
   ui: { loading: false },
-}).with(
-  withBatching(), // Batch updates for optimal rendering
-  withMemoization(), // Cache expensive computations
-  withEntities() // Efficient CRUD operations
-);
+})
+  .with(withEntities()) // Efficient CRUD operations (auto-detects entityMap)
+  .with(withBatching()); // Batch updates for optimal rendering
 
-// Now supports advanced operations
-tree.batchUpdate((state) => ({
-  products: [...state.products, newProduct],
-  ui: { loading: false },
-}));
+// Entity CRUD operations
+tree.$.products.addOne(newProduct);
+tree.$.products.setAll(productsFromApi);
 
-const products = tree.entities<Product>('products');
-products.selectBy((p) => p.category === 'electronics');
+// Entity queries
+const electronics = tree.$.products
+  .all()()
+  .filter((p) => p.category === 'electronics');
 ```
 
 **Full-Stack Application:**
@@ -644,17 +709,20 @@ const customTree = signalTree(state, TREE_PRESETS.DASHBOARD);
 SignalTree Core includes all enhancer functionality built-in. No separate packages needed:
 
 ```typescript
-import { signalTree, withEntities } from '@signaltree/core';
+import { signalTree, entityMap, withEntities } from '@signaltree/core';
 
-const tree = signalTree({ users: [] as User[] });
+// Without entityMap - use manual array updates
+const basic = signalTree({ users: [] as User[] });
+basic.$.users.update((users) => [...users, newUser]);
 
-// Without enhancer - use manual CRUD
-tree.$.users.update((users) => [...users, newUser]);
+// With entityMap + withEntities - use entity helpers
+const enhanced = signalTree({
+  users: entityMap<User>(),
+}).with(withEntities());
 
-// With enhancer - use entity helpers
-const enhanced = tree.with(withEntities());
-const users = enhanced.entities<User>('users');
-users.add(newUser); // ✅ Advanced CRUD operations
+enhanced.$.users.addOne(newUser); // ✅ Advanced CRUD operations
+enhanced.$.users.byId(123)(); // ✅ O(1) lookups
+enhanced.$.users.all()(); // ✅ Get all as array
 ```
 
 Core includes several performance optimizations:
@@ -843,58 +911,49 @@ const filteredProducts = computed(() => {
 ### Data Management Composition
 
 ```typescript
-import { signalTree, withEntities } from '@signaltree/core';
+import { signalTree, entityMap, withEntities } from '@signaltree/core';
 
 // Add data management capabilities (+2.77KB total)
 const tree = signalTree({
-  users: [] as User[],
-  posts: [] as Post[],
-  ui: { loading: false, error: null },
-}).with(
-  withEntities() // Advanced CRUD operations
-);
+  users: entityMap<User>(),
+  posts: entityMap<Post>(),
+  ui: { loading: false, error: null as string | null },
+}).with(withEntities());
 
-// Advanced entity operations
-const users = tree.entities<User>('users');
-users.add(newUser);
-users.selectBy((u) => u.active);
-users.updateMany([{ id: '1', changes: { status: 'active' } }]);
+// Advanced entity operations via tree.$ accessor
+tree.$.users.addOne(newUser);
+tree.$.users.selectBy((u) => u.active);
+tree.$.users.updateMany([{ id: '1', changes: { status: 'active' } }]);
 
-// Entity helpers support nested paths for organized state structures
+// Entity helpers work with nested structures
 // Example: deeply nested entities in a domain-driven design pattern
 const appTree = signalTree({
   app: {
     data: {
-      users: [] as User[],
-      products: [] as Product[],
+      users: entityMap<User>(),
+      products: entityMap<Product>(),
     },
   },
   admin: {
     data: {
-      logs: [] as AuditLog[],
-      reports: [] as Report[],
+      logs: entityMap<AuditLog>(),
+      reports: entityMap<Report>(),
     },
   },
-});
+}).with(withEntities());
 
-// Access deeply nested entities using dot notation
-const appUsers = appTree.entities<User>('app.data.users');
-const appProducts = appTree.entities<Product>('app.data.products');
-const adminLogs = appTree.entities<AuditLog>('admin.data.logs');
-const adminReports = appTree.entities<Report>('admin.data.reports');
-
-// All entity methods work seamlessly with nested paths
-appUsers.selectBy((u) => u.isAdmin); // Filtered signal
-appProducts.selectTotal(); // Count signal
-adminLogs.selectAll(); // All items signal
-adminReports.selectIds(); // ID array signal
+// 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
 
 // For async operations, use manual async or async helpers
 async function fetchUsers() {
   tree.$.ui.loading.set(true);
   try {
     const users = await api.getUsers();
-    tree.$.users.set(users);
+    tree.$.users.setAll(users);
   } catch (error) {
     tree.$.ui.error.set(error.message);
   } finally {
@@ -936,10 +995,10 @@ const tree = signalTree({
 );
 
 // Rich feature set available
-const users = tree.entities<User>('app.data.users');
 async function fetchUser(id: string) {
   return await api.getUser(id);
 }
+tree.$.app.data.users.byId(userId)(); // O(1) lookup
 tree.undo(); // Time travel
 tree.save(); // Persistence
 ```
@@ -1308,9 +1367,11 @@ tree.effect(fn); // Create reactive effects
 tree.subscribe(fn); // Manual subscriptions
 tree.destroy(); // Cleanup resources
 
-// Extended features (built into @signaltree/core)
-tree.entities<T>(key); // Entity helpers (use withEntities enhancer)
-// For async operations, use manual async or async helpers like createAsyncOperation or trackAsync
+// Entity helpers (when using entityMap + withEntities)
+// 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
 ```
 
 ## Extending with enhancers

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 };