@signaltree/core 2.0.3 → 3.0.0

package/README.md

@@ -4,7 +4,7 @@ Foundation package for SignalTree. Provides recursive typing, deep nesting suppo
 
 ## What is @signaltree/core?
 
-SignalTree Core is a lightweight (about 7.20KB gzipped) package that provides:
+SignalTree Core is a lightweight package that provides:
 
 - Recursive typing with deep nesting and accurate type inference
 - Fast operations with sub‑millisecond measurements at 5–20+ levels
@@ -13,18 +13,42 @@ SignalTree Core is a lightweight (about 7.20KB gzipped) package that provides:
 - Small API surface with zero-cost abstractions
 - Compact bundle size suited for production
 
-### Depth performance (Sept 2025, averaged)
+### Callable leaf signals (DX sugar only)
 
-Indicative measurements across different depths:
+SignalTree provides TypeScript support for callable syntax on leaf signals as developer experience sugar:
 
-| Depth level | Avg time | Type safety | Range         |
-| ----------- | -------- | ----------- | ------------- |
-| 5 levels    | 0.061ms  | ✅          | 0.041–0.133ms |
-| 10 levels   | 0.109ms  | ✅          | 0.060–0.181ms |
-| 15 levels   | 0.098ms  | ✅          | 0.088–0.126ms |
-| 20+ levels  | 0.103ms  | ✅          | 0.100–0.106ms |
+```typescript
+// TypeScript accepts this syntax (with proper tooling):
+tree.$.name('Jane'); // Set value
+tree.$.count((n) => n + 1); // Update with function
+
+// At build time, transforms convert to:
+tree.$.name.set('Jane'); // Direct Angular signal API
+tree.$.count.update((n) => n + 1); // Direct Angular signal API
+
+// Reading always works directly:
+const name = tree.$.name(); // No transform needed
+```
+
+**Key Points:**
+
+- **Zero runtime overhead**: No Proxy wrappers or runtime hooks
+- **Build-time only**: AST transform converts callable syntax to direct `.set/.update` calls
+- **Optional**: Use `@signaltree/callable-syntax` transform or stick with direct `.set/.update`
+- **Type-safe**: Full TypeScript support via module augmentation
+
+**Function-valued leaves:**
+When a leaf stores a function as its value, use direct `.set(fn)` to assign. Callable `sig(fn)` is treated as an updater.
+
+**Setup:**
+Install `@signaltree/callable-syntax` and configure your build tool to apply the transform. Without the transform, use `.set/.update` directly.
+
+### Measuring performance and size
 
-Note: Results vary by environment; figures are averaged across multiple runs.
+Performance and bundle size vary by app shape, build tooling, device, and runtime. To get meaningful results for your environment:
+
+- Use the **Benchmark Orchestrator** in the demo app to run calibrated, scenario-based benchmarks across supported libraries with **real-world frequency weighting**. It applies research-based multipliers derived from 40,000+ developer surveys and GitHub analysis, reports statistical summaries (median/p95/p99/stddev), alternates runs to reduce bias, and can export CSV/JSON. When available, memory usage is also reported.
+- Use the bundle analysis scripts in `scripts/` to measure your min+gz sizes. Sizes are approximate and depend on tree-shaking and configuration.
 
 ## Quick start
 
@@ -58,7 +82,6 @@ const tree = signalTree({
                               tests: {
                                 extreme: {
                                   depth: 15,
-                                  performance: 0.098, // ms (averaged)
                                   typeInference: true,
                                 },
                               },
@@ -79,9 +102,8 @@ const tree = signalTree({
 });
 
 // Type inference at deep nesting levels
-const performance = tree.$.enterprise.divisions.technology.departments.engineering.teams.frontend.projects.signaltree.releases.v1.features.recursiveTyping.validation.tests.extreme.performance();
-
-console.log(`Performance: ${performance}ms`); // ~0.098ms (averaged)
+const depth = tree.$.enterprise.divisions.technology.departments.engineering.teams.frontend.projects.signaltree.releases.v1.features.recursiveTyping.validation.tests.extreme.depth();
+console.log(`Depth: ${depth}`);
 
 // Type-safe updates at unlimited depth
 tree.$.enterprise.divisions.technology.departments.engineering.teams.frontend.projects.signaltree.releases.v1.features.recursiveTyping.validation.tests.extreme.depth(25); // Perfect type safety!
@@ -159,6 +181,99 @@ effect(() => {
 });
 ```
 
+### Reactive computations with computed()
+
+SignalTree works seamlessly with Angular's `computed()` for creating efficient reactive computations. These computations automatically update when their dependencies change and are memoized for optimal performance.
+
+```typescript
+import { computed, effect } from '@angular/core';
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({
+  users: [
+    { id: '1', name: 'Alice', active: true, role: 'admin' },
+    { id: '2', name: 'Bob', active: false, role: 'user' },
+    { id: '3', name: 'Charlie', active: true, role: 'user' },
+  ],
+  filters: {
+    showActive: true,
+    role: 'all' as 'all' | 'admin' | 'user',
+  },
+});
+
+// Basic computed - automatically memoized
+const userCount = computed(() => tree.$.users().length);
+
+// Complex filtering computation
+const filteredUsers = computed(() => {
+  const users = tree.$.users();
+  const filters = tree.$.filters();
+
+  return users.filter((user) => {
+    if (filters.showActive && !user.active) return false;
+    if (filters.role !== 'all' && user.role !== filters.role) return false;
+    return true;
+  });
+});
+
+// Derived computation from other computed values
+const activeAdminCount = computed(() => filteredUsers().filter((user) => user.role === 'admin' && user.active).length);
+
+// Performance-critical computation with complex logic
+const userStatistics = computed(() => {
+  const users = tree.$.users();
+
+  return {
+    total: users.length,
+    active: users.filter((u) => u.active).length,
+    admins: users.filter((u) => u.role === 'admin').length,
+    averageNameLength: users.reduce((acc, u) => acc + u.name.length, 0) / users.length,
+  };
+});
+
+// Dynamic computed functions (factory pattern)
+const userById = (id: string) => computed(() => tree.$.users().find((user) => user.id === id));
+
+// Usage in effects
+effect(() => {
+  console.log(`Filtered users: ${filteredUsers().length}`);
+  console.log(`Statistics:`, userStatistics());
+});
+
+// Best Practices:
+// 1. Use computed() for derived state that depends on signals
+// 2. Keep computations pure - no side effects
+// 3. Leverage automatic memoization for expensive operations
+// 4. Chain computed values for complex transformations
+// 5. Use factory functions for parameterized computations
+```
+
+### Performance optimization with memoization
+
+When combined with `@signaltree/memoization`, computed values become even more powerful:
+
+```typescript
+import { withMemoization } from '@signaltree/memoization';
+
+const tree = signalTree({
+  items: Array.from({ length: 10000 }, (_, i) => ({
+    id: i,
+    value: Math.random(),
+    category: `cat-${i % 10}`,
+  })),
+}).with(withMemoization());
+
+// Expensive computation - automatically cached by memoization enhancer
+const expensiveComputation = computed(() => {
+  return tree.$.items()
+    .filter((item) => item.value > 0.5)
+    .reduce((acc, item) => acc + Math.sin(item.value * Math.PI), 0);
+});
+
+// The computation only runs when tree.$.items() actually changes
+// Subsequent calls return cached result
+```
+
 ### Advanced usage (full state tree)
 
 ```typescript
@@ -300,7 +415,7 @@ const activeUsers = computed(() => tree.$.users().filter((user) => user.active))
 
 ### 4) Manual async state management
 
-Core provides basic state updates - async helpers require `@signaltree/async`:
+Core provides basic state updates - async helpers are now provided via `@signaltree/middleware` helpers:
 
 ```typescript
 const tree = signalTree({
@@ -353,25 +468,25 @@ SignalTree Core provides the foundation, but its real power comes from composabl
 
 **Performance Enhancers:**
 
-- `@signaltree/batching` (+1.27KB) - Batch updates for 455.8x performance improvement
-- `@signaltree/memoization` (+1.80KB) - Intelligent caching with 197.9x speedup
+- `@signaltree/batching` - Batch updates to reduce recomputation and rendering
+- `@signaltree/memoization` - Intelligent caching for expensive computations
 
 **Data Management:**
 
-- `@signaltree/entities` (+0.97KB) - Advanced CRUD operations for collections
-- `@signaltree/async` (+1.80KB) - Async actions with loading states
-- `@signaltree/serialization` (+4.62KB) - State persistence and SSR support
+- `@signaltree/entities` - Advanced CRUD operations for collections
+- Async helpers are provided via `@signaltree/middleware` (createAsyncOperation / trackAsync)
+- `@signaltree/serialization` - State persistence and SSR support
 
 **Development Tools:**
 
-- `@signaltree/devtools` (+2.49KB) - Redux DevTools integration
-- `@signaltree/time-travel` (+1.75KB) - Undo/redo functionality
+- `@signaltree/devtools` - Redux DevTools integration
+- `@signaltree/time-travel` - Undo/redo functionality
 
 **Integration:**
 
-- `@signaltree/ng-forms` (+3.38KB) - Angular Forms integration
-- `@signaltree/middleware` (+1.38KB) - State interceptors and logging
-- `@signaltree/presets` (+0.84KB) - Pre-configured common patterns
+- `@signaltree/ng-forms` - Angular Forms integration
+- `@signaltree/middleware` - State interceptors and logging
+- `@signaltree/presets` - Pre-configured common patterns
 
 #### Composition Patterns
 
@@ -418,7 +533,6 @@ products.selectBy((p) => p.category === 'electronics');
 **Full-Stack Application:**
 
 ```typescript
-import { withAsync } from '@signaltree/async';
 import { withSerialization } from '@signaltree/serialization';
 import { withTimeTravel } from '@signaltree/time-travel';
 
@@ -426,7 +540,7 @@ const tree = signalTree({
   user: null as User | null,
   preferences: { theme: 'light' },
 }).with(
-  withAsync(), // API integration
+  // withAsync removed — API integration patterns are now covered by middleware helpers
   withSerialization({
     // Auto-save to localStorage
     autoSave: true,
@@ -642,7 +756,7 @@ SignalTree Core is designed for modular composition. Start minimal and add featu
 ```typescript
 import { signalTree } from '@signaltree/core';
 
-// Core provides the foundation (7.25KB)
+// Core provides the foundation
 const tree = signalTree({
   users: [] as User[],
   ui: { loading: false },
@@ -661,13 +775,13 @@ import { signalTree } from '@signaltree/core';
 import { withBatching } from '@signaltree/batching';
 import { withMemoization } from '@signaltree/memoization';
 
-// Add performance optimizations (+3.07KB total)
+// Add performance optimizations
 const tree = signalTree({
   products: [] as Product[],
   filters: { category: '', search: '' },
 }).with(
-  withBatching(), // 455.8x performance gain for multiple updates
-  withMemoization() // 197.9x speedup for expensive computations
+  withBatching(), // Batch updates for optimal rendering
+  withMemoization() // Cache expensive computations
 );
 
 // Now supports batched updates
@@ -689,7 +803,6 @@ const filteredProducts = computed(() => {
 ```typescript
 import { signalTree } from '@signaltree/core';
 import { withEntities } from '@signaltree/entities';
-import { withAsync } from '@signaltree/async';
 
 // Add data management capabilities (+2.77KB total)
 const tree = signalTree({
@@ -697,8 +810,7 @@ const tree = signalTree({
   posts: [] as Post[],
   ui: { loading: false, error: null },
 }).with(
-  withEntities(), // Advanced CRUD operations
-  withAsync() // Async state management
+  withEntities() // Advanced CRUD operations
 );
 
 // Advanced entity operations
@@ -721,12 +833,11 @@ const fetchUsers = tree.asyncAction(async () => api.getUsers(), {
 import { signalTree } from '@signaltree/core';
 import { withBatching } from '@signaltree/batching';
 import { withEntities } from '@signaltree/entities';
-import { withAsync } from '@signaltree/async';
 import { withSerialization } from '@signaltree/serialization';
 import { withTimeTravel } from '@signaltree/time-travel';
 import { withDevtools } from '@signaltree/devtools';
 
-// Full development stack (~22KB total)
+// Full development stack (example)
 const tree = signalTree({
   app: {
     user: null as User | null,
@@ -736,7 +847,7 @@ const tree = signalTree({
 }).with(
   withBatching(), // Performance
   withEntities(), // Data management
-  withAsync(), // API calls
+  // withAsync removed — use middleware helpers for API integration
   withSerialization({
     // State persistence
     autoSave: true,
@@ -766,14 +877,13 @@ tree.save(); // Persistence
 import { signalTree } from '@signaltree/core';
 import { withBatching } from '@signaltree/batching';
 import { withEntities } from '@signaltree/entities';
-import { withAsync } from '@signaltree/async';
 import { withSerialization } from '@signaltree/serialization';
 
 // Production build (no dev tools)
 const tree = signalTree(initialState).with(
   withBatching(), // Performance optimization
   withEntities(), // Data management
-  withAsync(), // API integration
+  // withAsync removed — use middleware helpers for API integration
   withSerialization({
     // User preferences
     autoSave: true,
@@ -829,16 +939,9 @@ const dashboardTree = dashboardPreset({
 // Includes: batching, memoization, devtools
 ```
 
-### Bundle Size Planning
+### Measuring bundle size
 
-| Composition Strategy     | Bundle Size | Use Case                       |
-| ------------------------ | ----------- | ------------------------------ |
-| Core only                | 7.25KB      | Simple state, prototypes       |
-| + Batching + Memoization | 10.32KB     | Performance-critical apps      |
-| + Entities + Async       | 13.09KB     | Data-driven applications       |
-| + Serialization          | 17.71KB     | Persistent state, SSR          |
-| + DevTools + TimeTravel  | 21.95KB     | Development (disabled in prod) |
-| Full ecosystem           | 27.55KB     | Feature-rich applications      |
+Bundle sizes depend on your build, tree-shaking, and which enhancers you include. Use the scripts in `scripts/` to analyze min+gz for your configuration.
 
 ### Migration Strategy
 
@@ -855,7 +958,7 @@ const tree2 = tree.with(withBatching());
 const tree3 = tree2.with(withEntities());
 
 // Phase 4: Add async for API integration
-const tree4 = tree3.with(withAsync());
+// withAsync removed — no explicit async enhancer; use middleware helpers instead
 
 // Each phase is fully functional and production-ready
 ```
@@ -910,71 +1013,9 @@ class AppStateService {
 }
 ```
 
-## Performance benchmarks
-
-> Sub‑millisecond operations across common core functions
-
-### Recursive depth scaling (illustrative)
+## Measuring performance
 
-| **Depth Level**            | **Execution Time** | **Scaling Factor** | **Type Inference** | **Memory Usage** |
-| -------------------------- | ------------------ | ------------------ | ------------------ | ---------------- |
-| **Basic (5 levels)**       | 0.012ms            | 1.0x (baseline)    | ✅ Perfect         | ~1.1MB           |
-| **Medium (10 levels)**     | 0.015ms            | 1.25x              | ✅ Perfect         | ~1.2MB           |
-| **Extreme (15 levels)**    | **0.021ms**        | **1.75x**          | ✅ Perfect         | ~1.3MB           |
-| **Unlimited (20+ levels)** | 0.023ms            | 1.92x              | ✅ Perfect         | ~1.4MB           |
-
-Note: Scaling depends on state shape and hardware.
-
-### Example operation timings
-
-| Operation                   | SignalTree Core | Notes            |
-| --------------------------- | --------------- | ---------------- |
-| Tree initialization (small) | **0.031ms**     | 27 nodes         |
-| Tree initialization (large) | **0.745ms**     | 341 nodes        |
-| Single update               | **0.188ms**     | Property update  |
-| Nested update (5 levels)    | **0.188ms**     | Deep tree update |
-| Computation (cached)        | **0.094ms**     | Memoized result  |
-| Memory per 1K entities      | **1.2MB**       | Measured usage   |
-
-### Feature impact
-
-| Feature             | SignalTree Core    | With Extensions        | Notes                  |
-| ------------------- | ------------------ | ---------------------- | ---------------------- |
-| Batching efficiency | Standard           | **455.8x improvement** | vs non-batched         |
-| Memoization speedup | Basic              | **197.9x speedup**     | vs non-memoized        |
-| Memory efficiency   | **Optimized**      | **Further optimized**  | Lazy signals + cleanup |
-| Bundle impact       | **7.25KB gzipped** | **+20KB max**          | Tree-shakeable         |
-
-### Developer experience (core)
-
-| Metric                  | SignalTree Core | Traditional State Mgmt | **Improvement** |
-| ----------------------- | --------------- | ---------------------- | --------------- |
-| Lines of code (counter) | **4 lines**     | 18-32 lines            | **68-88% less** |
-| Files required          | **1 file**      | 3-4 files              | **75% fewer**   |
-| Setup complexity        | **Minimal**     | Complex                | **Simplified**  |
-| API surface             | **Small**       | Large                  | **Focused**     |
-
-### Memory usage comparison
-
-| Operation                | SignalTree Core | NgRx   | Akita  | Native Signals |
-| ------------------------ | --------------- | ------ | ------ | -------------- |
-| 1K entities              | 1.2MB           | 4.2MB  | 3.5MB  | 2.3MB          |
-| 10K entities             | 8.1MB           | 28.5MB | 22.1MB | 15.2MB         |
-| Deep nesting (10 levels) | 145KB           | 890KB  | 720KB  | 340KB          |
-
-### TypeScript inference speed
-
-```typescript
-// SignalTree: Instant inference
-const tree = signalTree({
-  deeply: { nested: { state: { with: { types: 'instant' } } } }
-});
-tree.$.deeply.nested.state.with.types.set('updated'); // ✅ <1ms
-
-// Manual typing required with other solutions
-interface State { deeply: { nested: { state: { with: { types: string } } } } }
-const store: Store<State> = ...; // Requires manual interface definition
-```
+For fair, reproducible measurements that reflect your app and hardware, use the **Benchmark Orchestrator** in the demo. It calibrates runs per scenario and library, applies **real-world frequency weighting** based on research analysis, reports robust statistics, and supports CSV/JSON export. Avoid copying fixed numbers from docs; results vary.
 
 ## Example
 
@@ -1204,7 +1245,7 @@ tree.destroy(); // Cleanup resources
 
 // Extended features (require additional packages)
 tree.entities<T>(key); // Entity helpers (requires @signaltree/entities)
-tree.asyncAction(fn, config?); // Async actions (requires @signaltree/async)
+// tree.asyncAction(fn, config?) example removed — use middleware helpers instead
 tree.asyncAction(fn, config?); // Create async action
 ```
 
@@ -1224,16 +1265,16 @@ const tree = signalTree(initialState).with(withBatching(), withMemoization(), wi
 
 ### Available extensions
 
-- **@signaltree/batching** (+1.27KB gzipped) - Batch multiple updates
-- **@signaltree/memoization** (+1.80KB gzipped) - Intelligent caching & performance
-- **@signaltree/middleware** (+1.38KB gzipped) - Middleware system & taps
-- **@signaltree/async** (+1.80KB gzipped) - Advanced async actions & states
-- **@signaltree/entities** (+929B gzipped) - Advanced entity management
-- **@signaltree/devtools** (+2.49KB gzipped) - Redux DevTools integration
-- **@signaltree/time-travel** (+1.75KB gzipped) - Undo/redo functionality
-- **@signaltree/ng-forms** (+3.38KB gzipped) - Complete Angular forms integration
-- **@signaltree/serialization** (+4.62KB gzipped) - State persistence & SSR support
-- **@signaltree/presets** (+0.84KB gzipped) - Environment-based configurations
+- **@signaltree/batching** - Batch multiple updates
+- **@signaltree/memoization** - Intelligent caching & performance
+- **@signaltree/middleware** - Middleware system & taps
+- Async helpers moved to `@signaltree/middleware` - advanced async operations & loading states
+- **@signaltree/entities** - Advanced entity management
+- **@signaltree/devtools** - Redux DevTools integration
+- **@signaltree/time-travel** - Undo/redo functionality
+- **@signaltree/ng-forms** - Complete Angular forms integration
+- **@signaltree/serialization** - State persistence & SSR support
+- **@signaltree/presets** - Environment-based configurations
 
 ## When to use core only
 
@@ -1284,7 +1325,7 @@ async loadUsers() {
   }
 }
 
-// Or use async actions with @signaltree/async
+// Or use middleware helpers for async actions (createAsyncOperation / trackAsync)
 loadUsers = tree.asyncAction(() => api.getUsers(), {
   onSuccess: (users) => ({ users }),
 });
@@ -1367,23 +1408,23 @@ Extend the core with optional feature packages:
 ### Performance & Optimization
 
 - **[@signaltree/batching](../batching)** (+1.27KB gzipped) - Batch multiple updates for better performance
-- **[@signaltree/memoization](../memoization)** (+1.80KB gzipped) - Intelligent caching & performance optimization
+- **[@signaltree/memoization](../memoization)** (+2.33KB gzipped) - Intelligent caching & performance optimization
 
 ### Advanced Features
 
-- **[@signaltree/middleware](../middleware)** (+1.2KB gzipped) - Middleware system & state interceptors
-- **[@signaltree/async](../async)** (+1.7KB gzipped) - Advanced async operations & loading states
-- **[@signaltree/entities](../entities)** (+929B gzipped) - Enhanced CRUD operations & entity management
+- **[@signaltree/middleware](../middleware)** (+1.89KB gzipped) - Middleware system & state interceptors
+- Async helpers moved to middleware package (see `packages/middleware`)
+- **[@signaltree/entities](../entities)** (+0.97KB gzipped) - Enhanced CRUD operations & entity management
 
 ### Development Tools
 
-- **[@signaltree/devtools](../devtools)** (+2.3KB gzipped) - Development tools & Redux DevTools integration
-- **[@signaltree/time-travel](../time-travel)** (+1.5KB gzipped) - Undo/redo functionality & state history
+- **[@signaltree/devtools](../devtools)** (+2.49KB gzipped) - Development tools & Redux DevTools integration
+- **[@signaltree/time-travel](../time-travel)** (+1.75KB gzipped) - Undo/redo functionality & state history
 
 ### Integration & Convenience
 
-- **[@signaltree/presets](../presets)** (+0.8KB gzipped) - Pre-configured setups for common patterns
-- **[@signaltree/ng-forms](../ng-forms)** (+3.4KB gzipped) - Complete Angular Forms integration
+- **[@signaltree/presets](../presets)** (+0.84KB gzipped) - Pre-configured setups for common patterns
+- **[@signaltree/ng-forms](../ng-forms)** (+3.38KB gzipped) - Complete Angular Forms integration
 
 ### Quick Start with Extensions
 
@@ -1395,7 +1436,7 @@ npm install @signaltree/core @signaltree/batching @signaltree/memoization
 npm install @signaltree/core @signaltree/batching @signaltree/memoization @signaltree/devtools @signaltree/time-travel
 
 # All packages (full-featured)
-npm install @signaltree/core @signaltree/batching @signaltree/memoization @signaltree/middleware @signaltree/async @signaltree/entities @signaltree/devtools @signaltree/time-travel @signaltree/presets @signaltree/ng-forms
+npm install @signaltree/core @signaltree/batching @signaltree/memoization @signaltree/middleware @signaltree/entities @signaltree/devtools @signaltree/time-travel @signaltree/presets @signaltree/ng-forms
 ```
 
 ## Links

package/fesm2022/signaltree-core.mjs

@@ -1116,5 +1116,5 @@ function applyEnhancer(tree, enhancer) {
     return enhancer(tree);
 }
 
-export { ENHANCER_META, SIGNAL_TREE_CONSTANTS, SIGNAL_TREE_MESSAGES, composeEnhancers, createEnhancer, createLazySignalTree, deepEqual, equal, isAnySignal, isBuiltInObject, isNodeAccessor$1 as isNodeAccessor, parsePath, resolveEnhancerOrder, signalTree, unwrap };
+export { ENHANCER_META, SIGNAL_TREE_CONSTANTS, SIGNAL_TREE_MESSAGES, composeEnhancers, createEnhancer, createLazySignalTree, deepEqual, equal, isAnySignal, isBuiltInObject, isNodeAccessor$1 as isNodeAccessor, parsePath, resolveEnhancerOrder, signalTree };
 //# sourceMappingURL=signaltree-core.mjs.map