@signaltree/core 6.2.4 → 6.4.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/index.js

@@ -1,5 +1,6 @@
 export { signalTree } from './lib/signal-tree.js';
 export { ENHANCER_META, entityMap } from './lib/types.js';
+export { derived, isDerivedMarker } from './lib/markers/derived.js';
 export { composeEnhancers, createLazySignalTree, isAnySignal, isNodeAccessor, toWritableSignal } from './lib/utils.js';
 export { createEditSession } from './lib/edit-session.js';
 export { getPathNotifier } from './lib/path-notifier.js';

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/internals/merge-derived.js

@@ -0,0 +1,59 @@
+import { computed, isSignal } from '@angular/core';
+import { isDerivedMarker } from '../markers/derived.js';
+
+function isSignalLike(value) {
+  return isSignal(value);
+}
+function ensurePathAndGetTarget($, path) {
+  if (!path) return $;
+  const parts = path.split('.');
+  let current = $;
+  for (const part of parts) {
+    if (!(part in current)) {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+  return current;
+}
+function mergeDerivedState($, derivedDef, path = '') {
+  if (!derivedDef || typeof derivedDef !== 'object') {
+    return;
+  }
+  for (const [key, value] of Object.entries(derivedDef)) {
+    const currentPath = path ? `${path}.${key}` : key;
+    if (isDerivedMarker(value)) {
+      const target = ensurePathAndGetTarget($, path);
+      if (key in target && isSignalLike(target[key])) {
+        if (typeof ngDevMode === 'undefined' || ngDevMode) {
+          console.warn(`SignalTree: Derived "${currentPath}" overwrites source signal. ` + `Consider using a different key to avoid confusion.`);
+        }
+      }
+      target[key] = computed(value.factory);
+    } else if (isSignalLike(value)) {
+      const target = ensurePathAndGetTarget($, path);
+      if (key in target && isSignalLike(target[key])) {
+        if (typeof ngDevMode === 'undefined' || ngDevMode) {
+          console.warn(`SignalTree: Derived signal "${currentPath}" overwrites source signal. ` + `Consider using a different key to avoid confusion.`);
+        }
+      }
+      target[key] = value;
+    } else if (typeof value === 'object' && value !== null) {
+      const target = ensurePathAndGetTarget($, path);
+      if (!(key in target)) {
+        target[key] = {};
+      } else if (isSignalLike(target[key])) {
+        throw new Error(`SignalTree: Cannot merge derived object into "${currentPath}" ` + `because source is a signal. Either make source an object or use a different key.`);
+      }
+      mergeDerivedState($, value, currentPath);
+    }
+  }
+}
+function applyDerivedFactories($, factories) {
+  for (const factory of factories) {
+    const derivedDef = factory($);
+    mergeDerivedState($, derivedDef);
+  }
+}
+
+export { applyDerivedFactories, mergeDerivedState };

package/dist/lib/markers/derived.js

@@ -0,0 +1,12 @@
+const DERIVED_MARKER = Symbol.for('signaltree:derived');
+function derived(factory) {
+  return {
+    [DERIVED_MARKER]: true,
+    factory
+  };
+}
+function isDerivedMarker(value) {
+  return value !== null && typeof value === 'object' && DERIVED_MARKER in value && value[DERIVED_MARKER] === true;
+}
+
+export { derived, isDerivedMarker };

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,8 @@
 import { signal, isSignal } from '@angular/core';
 import { SIGNAL_TREE_MESSAGES, SIGNAL_TREE_CONSTANTS } from './constants.js';
+import { applyDerivedFactories } from './internals/merge-derived.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 +174,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();
@@ -271,8 +276,112 @@ function create(initialState, config) {
   }
   return tree;
 }
-function signalTree(initialState, config = {}) {
-  return create(initialState, config);
+function signalTree(initialState, configOrDerived) {
+  const isFactory = typeof configOrDerived === 'function';
+  const config = isFactory ? {} : configOrDerived ?? {};
+  const baseTree = create(initialState, config);
+  const builder = createBuilder(baseTree);
+  if (isFactory) {
+    return builder.derived(configOrDerived);
+  }
+  return builder;
+}
+function createBuilder(baseTree) {
+  const derivedQueue = [];
+  let isFinalized = false;
+  const finalize = () => {
+    if (isFinalized) return;
+    isFinalized = true;
+    if (derivedQueue.length > 0) {
+      applyDerivedFactories(baseTree.$, derivedQueue);
+    }
+  };
+  const builder = function (arg) {
+    if (arguments.length === 0) {
+      return baseTree();
+    }
+    return baseTree(arg);
+  };
+  builder[NODE_ACCESSOR_SYMBOL] = true;
+  Object.defineProperty(builder, 'state', {
+    get() {
+      finalize();
+      return baseTree.state;
+    },
+    enumerable: false,
+    configurable: true
+  });
+  Object.defineProperty(builder, '$', {
+    get() {
+      finalize();
+      return baseTree.$;
+    },
+    enumerable: false,
+    configurable: true
+  });
+  Object.defineProperty(builder, 'with', {
+    value: function (enhancer) {
+      const enhanced = baseTree.with(enhancer);
+      const newBuilder = createBuilder(enhanced);
+      for (const key of Object.keys(enhanced)) {
+        if (key !== '$' && key !== 'state' && key !== 'with' && key !== 'bind' && key !== 'destroy' && key !== 'derived') {
+          try {
+            newBuilder[key] = enhanced[key];
+          } catch {}
+        }
+      }
+      for (const factory of derivedQueue) {
+        newBuilder.derived(factory);
+      }
+      return newBuilder;
+    },
+    enumerable: false,
+    writable: false,
+    configurable: true
+  });
+  if (typeof baseTree.bind === 'function') {
+    Object.defineProperty(builder, 'bind', {
+      value: baseTree.bind.bind(baseTree),
+      enumerable: false,
+      writable: false,
+      configurable: true
+    });
+  } else {
+    Object.defineProperty(builder, 'bind', {
+      value: () => builder,
+      enumerable: false,
+      writable: false,
+      configurable: true
+    });
+  }
+  if (typeof baseTree.destroy === 'function') {
+    Object.defineProperty(builder, 'destroy', {
+      value: baseTree.destroy.bind(baseTree),
+      enumerable: false,
+      writable: true,
+      configurable: true
+    });
+  } else {
+    Object.defineProperty(builder, 'destroy', {
+      value: () => {},
+      enumerable: false,
+      writable: true,
+      configurable: true
+    });
+  }
+  Object.defineProperty(builder, 'derived', {
+    value: function (factory) {
+      if (isFinalized) {
+        throw new Error('SignalTree: Cannot add derived() after tree.$ has been accessed. ' + 'Chain all .derived() calls before accessing $.');
+      }
+      derivedQueue.push(factory);
+      return builder;
+    },
+    enumerable: false,
+    writable: false,
+    configurable: true
+  });
+  return builder;
 }
 
 export { isNodeAccessor, signalTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "6.2.4",
+  "version": "6.4.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,

package/src/index.d.ts

@@ -1,6 +1,9 @@
 export { signalTree } from './lib/signal-tree';
 export type { ISignalTree, SignalTree, SignalTreeBase, FullSignalTree, ProdSignalTree, TreeNode, CallableWritableSignal, AccessibleNode, NodeAccessor, Primitive, NotFn, TreeConfig, TreePreset, Enhancer, EnhancerMeta, EnhancerWithMeta, EntitySignal, EntityMapMarker, EntityConfig, MutationOptions, AddOptions, AddManyOptions, TimeTravelEntry, TimeTravelMethods, } from './lib/types';
 export { entityMap } from './lib/types';
+export type { ProcessDerived, DeepMergeTree, DerivedFactory, } from './lib/internals/derived-types';
+export type { SignalTreeBuilder } from './lib/internals/builder-types';
+export { derived, isDerivedMarker, type DerivedMarker, type DerivedType, } from './lib/markers/derived';
 export { equal, deepEqual, isNodeAccessor, isAnySignal, toWritableSignal, parsePath, composeEnhancers, isBuiltInObject, createLazySignalTree, } from './lib/utils';
 export { createEditSession, type EditSession, type UndoRedoHistory, } from './lib/edit-session';
 export { getPathNotifier } from './lib/path-notifier';

package/src/lib/internals/builder-types.d.ts

@@ -0,0 +1,13 @@
+import type { ProcessDerived } from './derived-types';
+import type { ISignalTree, TreeNode } from '../types';
+export interface SignalTreeBuilder<TSource, TAccum = TreeNode<TSource>> {
+    (): TSource;
+    (value: TSource): void;
+    (updater: (current: TSource) => TSource): void;
+    readonly $: TAccum;
+    readonly state: TAccum;
+    with<TAdded>(enhancer: (tree: ISignalTree<TSource>) => ISignalTree<TSource> & TAdded): SignalTreeBuilder<TSource, TAccum> & TAdded;
+    bind(thisArg?: unknown): (value?: TSource) => TSource | void;
+    destroy(): void;
+    derived<TDerived extends object>(factory: ($: TAccum) => TDerived): SignalTreeBuilder<TSource, TAccum & ProcessDerived<TDerived>>;
+}

package/src/lib/internals/derived-types.d.ts

@@ -0,0 +1,10 @@
+import { Signal } from '@angular/core';
+import type { DerivedMarker } from '../markers/derived';
+import type { TreeNode } from '../types';
+export type ProcessDerived<T> = T extends DerivedMarker<infer R> ? Signal<R> : T extends Signal<infer S> ? Signal<S> : T extends object ? {
+    [P in keyof T]: ProcessDerived<T[P]>;
+} : never;
+export type DeepMergeTree<TSource, TDerived> = {
+    [K in keyof TSource | keyof TDerived]: K extends keyof TSource ? K extends keyof TDerived ? TSource[K] extends object ? TDerived[K] extends object ? TDerived[K] extends DerivedMarker<infer R> ? Signal<R> : TSource[K] & DeepMergeTree<TSource[K], ProcessDerived<TDerived[K]>> : TSource[K] : ProcessDerived<TDerived[K]> : TSource[K] : K extends keyof TDerived ? ProcessDerived<TDerived[K]> : never;
+};
+export type DerivedFactory<TSource, TDerived> = ($: TreeNode<TSource>) => TDerived;

package/src/lib/internals/merge-derived.d.ts

@@ -0,0 +1,4 @@
+type AnyRecord = Record<string, unknown>;
+export declare function mergeDerivedState($: AnyRecord, derivedDef: unknown, path?: string): void;
+export declare function applyDerivedFactories($: AnyRecord, factories: Array<($: AnyRecord) => object>): void;
+export {};

package/src/lib/markers/derived.d.ts

@@ -0,0 +1,10 @@
+declare const DERIVED_MARKER: unique symbol;
+export interface DerivedMarker<T> {
+    readonly [DERIVED_MARKER]: true;
+    readonly factory: () => T;
+    readonly __type?: T;
+}
+export type DerivedType<T> = T extends DerivedMarker<infer R> ? R : never;
+export declare function derived<T>(factory: () => T): DerivedMarker<T>;
+export declare function isDerivedMarker(value: unknown): value is DerivedMarker<unknown>;
+export {};

package/src/lib/markers/index.d.ts

@@ -0,0 +1 @@
+export { derived, isDerivedMarker, getDerivedMarkerSymbol, type DerivedMarker, type DerivedType, } from './derived';

package/src/lib/signal-tree.d.ts

@@ -1,3 +1,6 @@
-import type { TreeConfig, NodeAccessor, ISignalTree } from './types';
+import { SignalTreeBuilder } from './internals/builder-types';
+import { ProcessDerived } from './internals/derived-types';
+import type { TreeNode, TreeConfig, NodeAccessor } from './types';
 export declare function isNodeAccessor(value: unknown): value is NodeAccessor<unknown>;
-export declare function signalTree<T extends object>(initialState: T, config?: TreeConfig): ISignalTree<T>;
+export declare function signalTree<T extends object, TDerived extends object>(initialState: T, derivedFactory: ($: TreeNode<T>) => TDerived): SignalTreeBuilder<T, TreeNode<T> & ProcessDerived<TDerived>>;
+export declare function signalTree<T extends object>(initialState: T, config?: TreeConfig): SignalTreeBuilder<T, TreeNode<T>>;