@signaltree/core 7.1.2 → 7.1.4

package/README.md

@@ -2,19 +2,34 @@
   <img src="https://raw.githubusercontent.com/JBorgia/signaltree/main/apps/demo/public/signaltree.svg" alt="SignalTree Logo" width="60" height="60" />
 </div>
 
-# SignalTree Core
+# SignalTree: Reactive JSON
 
-Foundation package for SignalTree. Provides recursive typing, deep nesting support, and strong performance.
+**JSON branches, reactive leaves.**
+
+> No actions. No reducers. No selectors.
 
 ## What is @signaltree/core?
 
-SignalTree Core is a lightweight package that provides:
+SignalTree treats application state as **reactive JSON** — a typed, dot-notation interface to plain JSON-like objects with fine-grained reactivity layered transparently on top.
+
+You don't model state as actions, reducers, selectors, or classes — you model it as **data**.
+
+### Core Philosophy
+
+| Principle                | What It Means                                                                |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| **State is Data**        | Your state shape looks like JSON. No ceremony, no abstractions.              |
+| **Dot-Notation Access**  | `tree.$.user.profile.name()` — fully type-safe, IDE-discoverable             |
+| **Invisible Reactivity** | You think in data paths, not subscriptions. Reactivity emerges naturally.    |
+| **Lazy by Design**       | Signals created only where accessed. Types do heavy lifting at compile time. |
+
+### Technical Features
 
 - Recursive typing with deep nesting and accurate type inference
 - Fast operations with sub‑millisecond measurements at 5–20+ levels
 - Strong TypeScript safety across nested structures
 - Memory efficiency via structural sharing and lazy signals
-- Small API surface with zero-cost abstractions
+- Small API surface with minimal runtime overhead
 - Compact bundle size suited for production
 
 ## Import guidance (tree-shaking)
@@ -110,7 +125,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 +150,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 +912,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:
+
+- **`derivedFrom<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 { derivedFrom } from '@signaltree/core';
+import type { AppTreeBase } from '../app-tree';
+
+// derivedFrom provides the type context for $ via curried syntax
+export const entityResolutionDerived = derivedFrom<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 { derivedFrom } from '@signaltree/core';
+import type { AppTreeWithTier1 } from '../app-tree';
+
+// This tier has access to $.selectedUser from Tier 1
+export const complexLogicDerived = derivedFrom<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
+}
+
+// ✅ derivedFrom provides the type context (curried syntax)
+export const myDerived = derivedFrom<AppTreeBase>()(($) => ({
+  foo: computed(() => $.bar()), // $ is properly typed
+}));
+```
+
+**Key point**: `derivedFrom` is **only needed for functions defined in separate files**. Inline functions automatically inherit types from the chain. Note the curried syntax: `derivedFrom<TreeType>()(fn)` - this allows TypeScript to infer the return type while you specify the tree type.
+
 ## Error handling examples
 
 ### Manual async error handling

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/core",
-  "version": "7.1.2",
-  "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
+  "version": "7.1.4",
+  "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,

package/dist/constants.js

@@ -1,6 +0,0 @@
-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-equal.js

@@ -1,41 +0,0 @@
-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/batching.js

@@ -1,230 +0,0 @@
-import { copyTreeProperties } from '../utils/copy-tree-properties.js';
-
-function batching(config = {}) {
-  const enabled = config.enabled ?? true;
-  const notificationDelayMs = config.notificationDelayMs ?? 0;
-  return tree => {
-    if (!enabled) {
-      const passthrough = {
-        batch: fn => fn(),
-        coalesce: fn => fn(),
-        hasPendingNotifications: () => false,
-        flushNotifications: () => {}
-      };
-      const enhanced = tree;
-      Object.assign(enhanced, passthrough);
-      enhanced.batchUpdate = updater => {
-        if (typeof tree.batchUpdate === 'function') {
-          tree.batchUpdate(updater);
-        } else {
-          updater(tree());
-        }
-      };
-      return enhanced;
-    }
-    let notificationPending = false;
-    let notificationTimeoutId;
-    let inBatch = false;
-    let inCoalesce = false;
-    const coalescedUpdates = new Map();
-    const scheduleNotification = () => {
-      if (notificationPending) return;
-      notificationPending = true;
-      if (notificationDelayMs > 0) {
-        notificationTimeoutId = setTimeout(flushNotificationsInternal, notificationDelayMs);
-      } else {
-        queueMicrotask(flushNotificationsInternal);
-      }
-    };
-    const flushNotificationsInternal = () => {
-      if (!notificationPending) return;
-      notificationPending = false;
-      if (notificationTimeoutId !== undefined) {
-        clearTimeout(notificationTimeoutId);
-        notificationTimeoutId = undefined;
-      }
-      if (tree.__notifyChangeDetection) {
-        tree.__notifyChangeDetection();
-      }
-    };
-    const flushCoalescedUpdates = () => {
-      const updates = Array.from(coalescedUpdates.values());
-      coalescedUpdates.clear();
-      updates.forEach(fn => {
-        try {
-          fn();
-        } catch (e) {
-          console.error('[SignalTree] Error in coalesced update:', e);
-        }
-      });
-    };
-    const wrapSignalSetters = (node, path = '') => {
-      if (!node || typeof node !== 'object') return;
-      if (typeof node.set === 'function' && !node.__batchingWrapped) {
-        const originalSet = node.set.bind(node);
-        node.set = value => {
-          if (inCoalesce) {
-            coalescedUpdates.set(path, () => originalSet(value));
-          } else {
-            originalSet(value);
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        };
-        node.__batchingWrapped = true;
-      }
-      if (typeof node.update === 'function' && !node.__batchingUpdateWrapped) {
-        const originalUpdate = node.update.bind(node);
-        node.update = updater => {
-          if (inCoalesce) {
-            coalescedUpdates.set(`${path}:update:${Date.now()}`, () => originalUpdate(updater));
-          } else {
-            originalUpdate(updater);
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        };
-        node.__batchingUpdateWrapped = true;
-      }
-      for (const key of Object.keys(node)) {
-        if (key.startsWith('_') || key === 'set' || key === 'update') continue;
-        const child = node[key];
-        if (child && typeof child === 'object') {
-          wrapSignalSetters(child, path ? `${path}.${key}` : key);
-        }
-      }
-    };
-    if (tree.$) {
-      wrapSignalSetters(tree.$);
-    }
-    const batchingMethods = {
-      batch(fn) {
-        const wasBatching = inBatch;
-        inBatch = true;
-        try {
-          fn();
-        } finally {
-          inBatch = wasBatching;
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        }
-      },
-      coalesce(fn) {
-        const wasCoalescing = inCoalesce;
-        const wasBatching = inBatch;
-        inCoalesce = true;
-        inBatch = true;
-        try {
-          fn();
-        } finally {
-          inCoalesce = wasCoalescing;
-          inBatch = wasBatching;
-          if (!wasCoalescing) {
-            flushCoalescedUpdates();
-          }
-          if (!inBatch) {
-            scheduleNotification();
-          }
-        }
-      },
-      hasPendingNotifications() {
-        return notificationPending;
-      },
-      flushNotifications() {
-        flushNotificationsInternal();
-      }
-    };
-    const originalTreeCall = tree.bind(tree);
-    const enhancedTree = function (...args) {
-      if (args.length === 0) {
-        return originalTreeCall();
-      } else {
-        if (args.length === 1) {
-          const arg = args[0];
-          if (typeof arg === 'function') {
-            originalTreeCall(arg);
-          } else {
-            originalTreeCall(arg);
-          }
-        }
-        if (!inBatch) {
-          scheduleNotification();
-        }
-      }
-    };
-    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
-    Object.assign(enhancedTree, tree);
-    try {
-      copyTreeProperties(tree, enhancedTree);
-    } catch {}
-    Object.defineProperty(enhancedTree, 'with', {
-      value: function (enhancer) {
-        if (typeof enhancer !== 'function') {
-          throw new Error('Enhancer must be a function');
-        }
-        return enhancer(enhancedTree);
-      },
-      writable: false,
-      enumerable: false,
-      configurable: true
-    });
-    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
-      });
-    }
-    Object.assign(enhancedTree, batchingMethods);
-    enhancedTree.batchUpdate = updater => {
-      enhancedTree.batch(() => {
-        const current = originalTreeCall();
-        const updates = updater(current);
-        Object.entries(updates).forEach(([key, value]) => {
-          const property = enhancedTree.state[key];
-          if (property && typeof property.set === 'function') {
-            property.set(value);
-          } else if (typeof property === 'function') {
-            property(value);
-          }
-        });
-      });
-    };
-    return enhancedTree;
-  };
-}
-function highPerformanceBatching() {
-  return batching({
-    enabled: true,
-    notificationDelayMs: 0
-  });
-}
-function batchingWithConfig(config = {}) {
-  return batching(config);
-}
-function flushBatchedUpdates() {
-  console.warn('[SignalTree] flushBatchedUpdates() is deprecated. Use tree.flushNotifications() instead.');
-}
-function hasPendingUpdates() {
-  console.warn('[SignalTree] hasPendingUpdates() is deprecated. Use tree.hasPendingNotifications() instead.');
-  return false;
-}
-function getBatchQueueSize() {
-  console.warn('[SignalTree] getBatchQueueSize() is deprecated. Signal writes are now synchronous.');
-  return 0;
-}
-Object.assign((config = {}) => batching(config), {
-  highPerformance: highPerformanceBatching
-});
-
-export { batching, batchingWithConfig, flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, highPerformanceBatching };