@signaltree/core 6.2.4 → 6.3.0

package/README.md

@@ -148,6 +148,46 @@ $.users.setAll(usersFromApi); // Replace all
 const user = entityMap()[123]; // Requires intermediate object
 ```
 
+### Notification Batching
+
+SignalTree automatically batches _notification delivery_ to subscribers and change detection to the end of the current microtask. This prevents render thrashing when multiple values are updated together and preserves immediate read-after-write semantics (values update synchronously, notifications are deferred).
+
+**Example**
+
+```typescript
+// Multiple updates in the same microtask are coalesced into a single notification
+tree.$.form.name.set('Alice');
+tree.$.form.email.set('alice@example.com');
+tree.$.form.submitted.set(true);
+// → Subscribers are notified once at the end of the microtask with final values
+```
+
+**Testing**
+
+When tests need synchronous notification delivery, use `flushSync()`:
+
+```typescript
+import { getPathNotifier } from '@signaltree/core';
+
+it('updates state', () => {
+  tree.$.count.set(5);
+  getPathNotifier().flushSync();
+  expect(subscriber).toHaveBeenCalledWith(5, 0);
+});
+```
+
+Alternatively, await a microtask (`await Promise.resolve()`) to allow the automatic flush to occur.
+
+**Opting out**
+
+To disable automatic microtask batching for a specific tree instance:
+
+```typescript
+const tree = signalTree(initialState, { batching: false });
+```
+
+Use this only for rare cases that truly require synchronous notifications (most apps should keep batching enabled).
+
 ## Quick start
 
 ### Installation

package/dist/enhancers/time-travel/time-travel.js

@@ -1,5 +1,5 @@
 import { snapshotState } from '../../lib/utils.js';
-import { deepClone, deepEqual } from './utils.js';
+import { deepEqual, deepClone } from './utils.js';
 
 class TimeTravelManager {
   tree;
@@ -24,7 +24,7 @@ class TimeTravelManager {
     };
     this.addEntry('INIT', this.tree());
   }
-  addEntry(action, state, payload) {
+  addEntry(action, state, payload, provisional = false) {
     if (this.currentIndex < this.history.length - 1) {
       this.history = this.history.slice(0, this.currentIndex + 1);
     }
@@ -43,6 +43,12 @@ class TimeTravelManager {
         payload
       })
     };
+    if (provisional) entry.__provisional = true;
+    const last = this.history[this.history.length - 1];
+    if (last && deepEqual(last.state, entry.state)) {
+      if (last.__provisional) delete last.__provisional;
+      return;
+    }
     this.history.push(entry);
     this.currentIndex = this.history.length - 1;
     if (this.history.length > this.maxHistorySize) {
@@ -59,6 +65,20 @@ class TimeTravelManager {
     this.restoreState(entry.state);
     return true;
   }
+  finalizeProvisional(state) {
+    const last = this.history[this.history.length - 1];
+    if (last && last.__provisional) {
+      if (deepEqual(last.state, state)) {
+        delete last.__provisional;
+        return;
+      }
+      last.state = deepClone(state);
+      last.timestamp = Date.now();
+      delete last.__provisional;
+      return;
+    }
+    this.addEntry('update', state);
+  }
   redo() {
     if (!this.canRedo()) {
       return false;
@@ -143,6 +163,22 @@ function timeTravel(config = {}) {
         isRestoring = false;
       }
     });
+    try {
+      const req = globalThis['require'];
+      if (typeof req === 'function') {
+        const {
+          getPathNotifier
+        } = req('../../lib/path-notifier');
+        const notifier = getPathNotifier();
+        if (notifier && typeof notifier.onFlush === 'function') {
+          notifier.onFlush(() => {
+            if (isRestoring) return;
+            const afterState = originalTreeCall();
+            timeTravelManager.addEntry('batch', afterState);
+          });
+        }
+      }
+    } catch {}
     const enhancedTree = function (...args) {
       if (args.length === 0) {
         return originalTreeCall();

package/dist/lib/entity-signal.js

@@ -42,6 +42,8 @@ function createEntitySignal(config, pathNotifier, basePath) {
     }
     return node;
   }
+  const whereCache = new WeakMap();
+  const findCache = new WeakMap();
   const api = {
     byId(id) {
       const entity = storage.get(id);
@@ -74,10 +76,18 @@ function createEntitySignal(config, pathNotifier, basePath) {
       return computed(() => countSignal() === 0);
     },
     where(predicate) {
-      return computed(() => allSignal().filter(predicate));
+      const cached = whereCache.get(predicate);
+      if (cached) return cached;
+      const s = computed(() => allSignal().filter(predicate));
+      whereCache.set(predicate, s);
+      return s;
     },
     find(predicate) {
-      return computed(() => allSignal().find(predicate));
+      const cached = findCache.get(predicate);
+      if (cached) return cached;
+      const s = computed(() => allSignal().find(predicate));
+      findCache.set(predicate, s);
+      return s;
     },
     addOne(entity, opts) {
       const id = opts?.selectId?.(entity) ?? selectId(entity);

package/dist/lib/path-notifier.js

@@ -1,6 +1,20 @@
 class PathNotifier {
   subscribers = new Map();
   interceptors = new Map();
+  batchingEnabled = true;
+  pendingFlush = false;
+  pending = new Map();
+  firstValues = new Map();
+  flushCallbacks = new Set();
+  constructor(options) {
+    if (options && options.batching === false) this.batchingEnabled = false;
+  }
+  setBatchingEnabled(enabled) {
+    this.batchingEnabled = enabled;
+  }
+  isBatchingEnabled() {
+    return this.batchingEnabled;
+  }
   subscribe(pattern, handler) {
     if (!this.subscribers.has(pattern)) {
       this.subscribers.set(pattern, new Set());
@@ -34,6 +48,26 @@ class PathNotifier {
     };
   }
   notify(path, value, prev) {
+    if (!this.batchingEnabled) {
+      return this._runNotify(path, value, prev);
+    }
+    if (!this.pending.has(path)) {
+      this.firstValues.set(path, prev);
+    }
+    this.pending.set(path, {
+      newValue: value,
+      oldValue: this.firstValues.get(path)
+    });
+    if (!this.pendingFlush) {
+      this.pendingFlush = true;
+      queueMicrotask(() => this.flush());
+    }
+    return {
+      blocked: false,
+      value
+    };
+  }
+  _runNotify(path, value, prev) {
     let blocked = false;
     let transformed = value;
     for (const [pattern, interceptorSet] of this.interceptors) {
@@ -67,6 +101,41 @@ class PathNotifier {
       value: transformed
     };
   }
+  flush() {
+    const toNotify = new Map(this.pending);
+    this.pending.clear();
+    this.firstValues.clear();
+    this.pendingFlush = false;
+    for (const [path, {
+      newValue,
+      oldValue
+    }] of toNotify) {
+      if (newValue === oldValue) continue;
+      const res = this._runNotify(path, newValue, oldValue);
+      if (res.blocked) ;
+    }
+    for (const cb of Array.from(this.flushCallbacks)) {
+      try {
+        cb();
+      } catch {}
+    }
+  }
+  flushSync() {
+    while (this.pending.size > 0 || this.pendingFlush) {
+      if (this.pendingFlush && this.pending.size === 0) {
+        this.pendingFlush = false;
+        break;
+      }
+      this.flush();
+    }
+  }
+  onFlush(callback) {
+    this.flushCallbacks.add(callback);
+    return () => this.flushCallbacks.delete(callback);
+  }
+  hasPending() {
+    return this.pending.size > 0;
+  }
   matches(pattern, path) {
     if (pattern === '**') return true;
     if (pattern === path) return true;
@@ -79,6 +148,9 @@ class PathNotifier {
   clear() {
     this.subscribers.clear();
     this.interceptors.clear();
+    this.pending.clear();
+    this.firstValues.clear();
+    this.pendingFlush = false;
   }
   getSubscriberCount() {
     let count = 0;

package/dist/lib/signal-tree.js

@@ -1,6 +1,7 @@
 import { signal, isSignal } from '@angular/core';
 import { SIGNAL_TREE_MESSAGES, SIGNAL_TREE_CONSTANTS } from './constants.js';
 import { SignalMemoryManager } from './memory/memory-manager.js';
+import { getPathNotifier } from './path-notifier.js';
 import { SecurityValidator } from './security/security-validator.js';
 import { createLazySignalTree, unwrap } from './utils.js';
 import { deepEqual } from '../deep-equal.js';
@@ -172,6 +173,9 @@ function create(initialState, config) {
   const useLazy = shouldUseLazy(initialState, config, estimatedSize);
   let signalState;
   let memoryManager;
+  try {
+    getPathNotifier().setBatchingEnabled(Boolean(config.batchUpdates !== false));
+  } catch {}
   if (useLazy && typeof initialState === 'object') {
     try {
       memoryManager = new SignalMemoryManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "6.2.4",
+  "version": "6.3.0",
   "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
   "type": "module",
   "sideEffects": false,