@signaltree/core 7.1.2 → 7.1.3

package/README.md

@@ -110,7 +110,7 @@ Follow these principles for idiomatic SignalTree code:
 ### 1. Expose signals directly (no computed wrappers)
 
 ```typescript
-const tree = signalTree(initialState).with(entities());
+const tree = signalTree(initialState); // No .with(entities()) needed in v7+ (deprecated in v6, removed in v7)
 const $ = tree.$; // Shorthand for state access
 
 // ✅ SignalTree-first: Direct signal exposure
@@ -135,7 +135,7 @@ export type UserTree = ReturnType<typeof createUserTree>;
 
 // Factory function - no explicit return type needed
 export function createUserTree() {
-  const tree = signalTree(initialState).with(entities());
+  const tree = signalTree(initialState); // entities() not needed in v7+
   return {
     selectedUserId: tree.$.selected.userId, // Type inferred automatically
     // ...
@@ -897,6 +897,123 @@ tree.log('Tree created');
 >
 > 📱 **Interactive demo**: [Demo App](/custom-extensions)
 
+### 8) Derived State Tiers
+
+SignalTree supports **derived state** via the `.derived()` method, which allows you to add computed signals that build on base state or previous derived tiers.
+
+#### Basic Usage (Inline Derived)
+
+When derived functions are defined inline, TypeScript automatically infers all types:
+
+```typescript
+import { signalTree, entityMap } from '@signaltree/core';
+import { computed } from '@angular/core';
+
+const tree = signalTree({
+  users: entityMap<User, number>(),
+  selectedUserId: null as number | null,
+})
+  .derived(($) => ({
+    // Tier 1: Entity resolution
+    selectedUser: computed(() => {
+      const id = $.selectedUserId();
+      return id != null ? $.users.byId(id)?.() ?? null : null;
+    }),
+  }))
+  .derived(($) => ({
+    // Tier 2: Complex logic (can access $.selectedUser from Tier 1)
+    isAdmin: computed(() => $.selectedUser()?.role === 'admin'),
+  }));
+
+// Usage
+tree.$.selectedUser(); // User | null (computed signal)
+tree.$.isAdmin(); // boolean (computed signal)
+```
+
+#### External Derived Functions (Modular Architecture)
+
+For larger applications, you may want to organize derived tiers into separate files. **This requires explicit typing** because TypeScript cannot infer types across file boundaries.
+
+SignalTree provides two utilities for external derived functions:
+
+- **`externalDerived<TTree>()`** - Curried helper function that provides type context for your derived function
+- **`WithDerived<TTree, TDerivedFn>`** - Type utility to build intermediate tree types
+
+```typescript
+// app-tree.ts
+import { signalTree, entityMap, WithDerived } from '@signaltree/core';
+import { entityResolutionDerived } from './derived/tier-entity-resolution';
+import { complexLogicDerived } from './derived/tier-complex-logic';
+
+// Define base tree type
+export type AppTreeBase = ReturnType<typeof signalTree<ReturnType<typeof createBaseState>>>;
+
+// Build intermediate types using WithDerived
+export type AppTreeWithTier1 = WithDerived<AppTreeBase, typeof entityResolutionDerived>;
+export type AppTreeWithTier2 = WithDerived<AppTreeWithTier1, typeof complexLogicDerived>;
+
+function createBaseState() {
+  return {
+    users: entityMap<User, number>(),
+    selectedUserId: null as number | null,
+  };
+}
+
+export function createAppTree() {
+  return signalTree(createBaseState()).derived(entityResolutionDerived).derived(complexLogicDerived);
+}
+```
+
+```typescript
+// derived/tier-entity-resolution.ts
+import { computed } from '@angular/core';
+import { externalDerived } from '@signaltree/core';
+import type { AppTreeBase } from '../app-tree';
+
+// externalDerived provides the type context for $ via curried syntax
+export const entityResolutionDerived = externalDerived<AppTreeBase>()(($) => ({
+  selectedUser: computed(() => {
+    const id = $.selectedUserId();
+    return id != null ? $.users.byId(id)?.() ?? null : null;
+  }),
+}));
+```
+
+```typescript
+// derived/tier-complex-logic.ts
+import { computed } from '@angular/core';
+import { externalDerived } from '@signaltree/core';
+import type { AppTreeWithTier1 } from '../app-tree';
+
+// This tier has access to $.selectedUser from Tier 1
+export const complexLogicDerived = externalDerived<AppTreeWithTier1>()(($) => ({
+  isAdmin: computed(() => $.selectedUser()?.role === 'admin'),
+  displayName: computed(() => {
+    const user = $.selectedUser();
+    return user ? `${user.firstName} ${user.lastName}` : 'No user selected';
+  }),
+}));
+```
+
+#### Why External Functions Need Typing
+
+When a function is defined in a separate file, TypeScript analyzes it **in isolation** before knowing how it will be used. The type inference happens at the **definition site**, not the **call site**:
+
+```typescript
+// ❌ TypeScript can't infer $ - this file is compiled before app-tree.ts uses it
+export function myDerived($) {
+  // $ is 'any'
+  return { foo: computed(() => $.bar()) }; // Error: $ has no properties
+}
+
+// ✅ externalDerived provides the type context (curried syntax)
+export const myDerived = externalDerived<AppTreeBase>()(($) => ({
+  foo: computed(() => $.bar()), // $ is properly typed
+}));
+```
+
+**Key point**: `externalDerived` is **only needed for functions defined in separate files**. Inline functions automatically inherit types from the chain. Note the curried syntax: `externalDerived<TreeType>()(fn)` - this allows TypeScript to infer the return type while you specify the tree type.
+
 ## Error handling examples
 
 ### Manual async error handling

package/dist/enhancers/entities/entities.js

@@ -1,24 +1,7 @@
 function entities(config = {}) {
-  if (typeof ngDevMode === 'undefined' || ngDevMode) {
-    console.warn('SignalTree: entities() enhancer is deprecated in v7. ' + 'EntityMap markers are now automatically processed. ' + 'Remove .with(entities()) from your code. ' + 'This enhancer will be removed in v8.');
-  }
-  const {
-    enabled = true
-  } = config;
-  return tree => {
-    tree.__entitiesEnabled = true;
-    return tree;
-  };
+  throw new Error('entities() has been removed. Remove `.with(entities())` from your code; v7+ auto-processes EntityMap markers.');
 }
-function enableEntities() {
-  return entities();
-}
-function highPerformanceEntities() {
-  return entities();
-}
-Object.assign(entities, {
-  highPerformance: highPerformanceEntities,
-  enable: enableEntities
-});
+const enableEntities = entities;
+const highPerformanceEntities = entities;
 
 export { enableEntities, entities, highPerformanceEntities };

package/dist/index.js

@@ -1,5 +1,6 @@
 export { signalTree } from './lib/signal-tree.js';
 export { ENHANCER_META } from './lib/types.js';
+export { externalDerived } from './lib/internals/derived-types.js';
 export { isDerivedMarker } from './lib/markers/derived.js';
 export { LoadingState, isStatusMarker, status } from './lib/markers/status.js';
 export { isStoredMarker, stored } from './lib/markers/stored.js';

package/dist/lib/internals/derived-types.js

@@ -0,0 +1,5 @@
+function externalDerived() {
+  return fn => fn;
+}
+
+export { externalDerived };

package/dist/lib/presets.js

@@ -2,19 +2,18 @@ import { signalTree } from './signal-tree.js';
 import { effects } from '../enhancers/effects/effects.js';
 import { batching } from '../enhancers/batching/batching.js';
 import { memoization } from '../enhancers/memoization/memoization.js';
-import { entities } from '../enhancers/entities/entities.js';
 import { timeTravel } from '../enhancers/time-travel/time-travel.js';
 import { devTools } from '../enhancers/devtools/devtools.js';
 
 function createDevTree(initialState, config = {}) {
   if (arguments.length === 0) {
-    const enhancer = tree => tree.with(effects()).with(batching()).with(memoization()).with(entities()).with(timeTravel()).with(devTools());
+    const enhancer = tree => tree.with(effects()).with(batching()).with(memoization()).with(timeTravel()).with(devTools());
     return {
       enhancer
     };
   }
   const base = signalTree(initialState, config);
-  const enhanced = base.with(effects()).with(batching(config.batching)).with(memoization(config.memoization)).with(entities()).with(timeTravel(config.timeTravel)).with(devTools(config.devTools));
+  const enhanced = base.with(effects()).with(batching(config.batching)).with(memoization(config.memoization)).with(timeTravel(config.timeTravel)).with(devTools(config.devTools));
   return enhanced;
 }
 

package/package.json

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

package/src/enhancers/entities/entities.d.ts

@@ -1,11 +1,7 @@
-import type { ISignalTree, EntitiesEnabled } from '../../lib/types';
 export interface EntitiesEnhancerConfig {
     enabled?: boolean;
 }
-export declare function entities(config?: EntitiesEnhancerConfig): <T>(tree: ISignalTree<T>) => ISignalTree<T> & EntitiesEnabled;
-export declare function enableEntities(): <T>(tree: ISignalTree<T>) => ISignalTree<T> & EntitiesEnabled;
-export declare function highPerformanceEntities(): <T>(tree: ISignalTree<T>) => ISignalTree<T> & EntitiesEnabled;
-export declare const withEntities: typeof entities & {
-    highPerformance: typeof highPerformanceEntities;
-    enable: typeof enableEntities;
-};
+export declare function entities(config?: EntitiesEnhancerConfig): void;
+export declare const enableEntities: typeof entities;
+export declare const highPerformanceEntities: typeof entities;
+export declare const withEntities: typeof entities;

package/src/index.d.ts

@@ -1,7 +1,8 @@
 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 { ProcessDerived, DeepMergeTree, DerivedFactory, WithDerived, } from './lib/internals/derived-types';
+export { externalDerived } from './lib/internals/derived-types';
 export type { SignalTreeBuilder } from './lib/internals/builder-types';
 export { isDerivedMarker, type DerivedMarker, type DerivedType, } from './lib/markers/derived';
 export { status, isStatusMarker, LoadingState, type StatusMarker, type StatusSignal, type StatusConfig, } from './lib/markers/status';

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

@@ -8,3 +8,11 @@ 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;
+export type WithDerived<TTree extends {
+    $: object;
+}, TDerivedFn extends ($: TTree['$']) => object> = TTree & {
+    $: TTree['$'] & ReturnType<TDerivedFn>;
+};
+export declare function externalDerived<TTree extends {
+    $: object;
+}>(): <TReturn extends object>(fn: ($: TTree['$']) => TReturn) => ($: any) => TReturn;