@signaltree/core 6.3.0 → 6.4.0

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/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/signal-tree.js

@@ -1,5 +1,6 @@
 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';
@@ -275,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.3.0",
+  "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>>;