@signaltree/core 4.0.15 → 4.0.16

package/README.md

@@ -1457,20 +1457,44 @@ While `@signaltree/core` includes comprehensive built-in enhancers for most use
 
 ### 📝 @signaltree/ng-forms
 
-**Angular Reactive Forms integration for SignalTree**
+**Angular Forms integration for SignalTree (Angular 17+)**
 
-Seamlessly connect Angular Reactive Forms with your SignalTree state for two-way data binding, validation, and form control.
+Seamlessly connect Angular Forms with your SignalTree state for two-way data binding, validation, and form control.
 
 ```bash
 npm install @signaltree/ng-forms
 ```
 
 **Features:**
+
 - 🔗 Two-way binding between forms and SignalTree state
 - ✅ Built-in validation integration
 - 🎯 Type-safe form controls
 - 🔄 Automatic sync between form state and tree state
 - 📊 Form status tracking (valid, pristine, touched, etc.)
+- ⚡ Native Signal Forms support (Angular 20.3+)
+- 🔧 Legacy bridge for Angular 17-19 (deprecated, will be removed with Angular 21)
+
+**Signal Forms (Angular 20.3+ recommended)**
+
+Use Angular's Signal Forms `connect()` API directly with SignalTree:
+
+```ts
+import { toWritableSignal } from '@signaltree/core';
+
+const tree = signalTree({
+  user: { name: '', email: '' },
+});
+
+// Leaves are WritableSignal<T>
+nameControl.connect(tree.$.user.name);
+
+// Convert a slice to a WritableSignal<T>
+const userSignal = toWritableSignal(tree.$.user);
+userGroupControl.connect(userSignal);
+```
+
+The `@signaltree/ng-forms` package supports Angular 17+ and will prefer `connect()` when available (Angular 20.3+). Angular 17-19 uses a legacy bridge that will be deprecated when Angular 21 is released.
 
 **Quick Example:**
 
@@ -1479,7 +1503,7 @@ import { signalTree } from '@signaltree/core';
 import { bindFormToTree } from '@signaltree/ng-forms';
 
 const tree = signalTree({
-  user: { name: '', email: '', age: 0 }
+  user: { name: '', email: '', age: 0 },
 });
 
 @Component({
@@ -1489,13 +1513,13 @@ const tree = signalTree({
       <input formControlName="email" type="email" />
       <input formControlName="age" type="number" />
     </form>
-  `
+  `,
 })
 class UserFormComponent {
   form = new FormGroup({
     name: new FormControl(''),
     email: new FormControl(''),
-    age: new FormControl(0)
+    age: new FormControl(0),
   });
 
   constructor() {
@@ -1506,6 +1530,7 @@ class UserFormComponent {
 ```
 
 **When to use:**
+
 - Building forms with Angular Reactive Forms
 - Need validation integration
 - Two-way data binding between forms and state
@@ -1526,6 +1551,7 @@ npm install @signaltree/enterprise
 ```
 
 **Features:**
+
 - ⚡ PathIndex for O(k) lookup time regardless of tree size
 - 🗜️ Advanced memory optimization algorithms
 - 📊 Performance profiling and monitoring
@@ -1541,24 +1567,34 @@ import { withEnterpriseOptimizations } from '@signaltree/enterprise';
 const tree = signalTree({
   // Large application state with hundreds of signals
   modules: {
-    auth: { /* ... */ },
-    data: { /* ... */ },
-    ui: { /* ... */ },
+    auth: {
+      /* ... */
+    },
+    data: {
+      /* ... */
+    },
+    ui: {
+      /* ... */
+    },
     // ... many more modules
-  }
-}).with(withEnterpriseOptimizations({
-  enablePathIndex: true,
-  enableMemoryOptimizations: true,
-  enablePerformanceMonitoring: true
-}));
+  },
+}).with(
+  withEnterpriseOptimizations({
+    enablePathIndex: true,
+    enableMemoryOptimizations: true,
+    enablePerformanceMonitoring: true,
+  })
+);
 ```
 
 **Performance Benefits:**
+
 - **Constant-time lookups:** O(k) lookup where k is path depth, not total signal count
 - **Memory efficiency:** Up to 40% reduction in memory usage for large trees
 - **Faster updates:** Optimized update batching for high-frequency scenarios
 
 **When to use:**
+
 - Applications with 500+ signals
 - Complex nested state structures (10+ levels deep)
 - High-frequency state updates
@@ -1580,6 +1616,7 @@ npm install --save-dev @signaltree/guardrails
 ```
 
 **Features:**
+
 - 🔥 Hot-path detection - identifies frequently accessed signals
 - 💾 Memory leak detection - tracks signal cleanup issues
 - 📊 Performance budgets - enforces performance thresholds
@@ -1595,15 +1632,17 @@ import { withGuardrails } from '@signaltree/guardrails';
 
 const tree = signalTree({
   users: [] as User[],
-  posts: [] as Post[]
-}).with(withGuardrails({
-  hotPathThreshold: 100,        // Warn if signal accessed >100 times/sec
-  memoryLeakThreshold: 50,      // Warn if >50 uncleaned signals
-  budgets: {
-    updateTime: 16,             // Warn if updates take >16ms
-    signalCount: 1000           // Warn if >1000 signals created
-  }
-}));
+  posts: [] as Post[],
+}).with(
+  withGuardrails({
+    hotPathThreshold: 100, // Warn if signal accessed >100 times/sec
+    memoryLeakThreshold: 50, // Warn if >50 uncleaned signals
+    budgets: {
+      updateTime: 16, // Warn if updates take >16ms
+      signalCount: 1000, // Warn if >1000 signals created
+    },
+  })
+);
 
 // Development warnings will appear in console
 // Production builds get no-op functions (0 overhead)
@@ -1646,6 +1685,7 @@ if (leaks.length > 0) {
 In production builds, all guardrails functions become no-ops with zero runtime cost.
 
 **When to use:**
+
 - During active development
 - Performance optimization phase
 - Debugging state management issues
@@ -1667,6 +1707,7 @@ npm install --save-dev @signaltree/callable-syntax
 ```
 
 **Features:**
+
 - 🍬 Syntactic sugar for signal updates
 - ⚡ Zero runtime overhead (build-time transform)
 - ✅ Full TypeScript type safety
@@ -1677,11 +1718,11 @@ npm install --save-dev @signaltree/callable-syntax
 
 ```typescript
 // With callable-syntax transform
-tree.$.name('Jane');              // Transformed to: tree.$.name.set('Jane')
-tree.$.count((n) => n + 1);       // Transformed to: tree.$.count.update((n) => n + 1)
+tree.$.name('Jane'); // Transformed to: tree.$.name.set('Jane')
+tree.$.count((n) => n + 1); // Transformed to: tree.$.count.update((n) => n + 1)
 
 // Reading always works directly (no transform needed)
-const name = tree.$.name();       // Direct Angular signal API
+const name = tree.$.name(); // Direct Angular signal API
 ```
 
 **Setup (tsconfig.json):**
@@ -1689,9 +1730,7 @@ const name = tree.$.name();       // Direct Angular signal API
 ```json
 {
   "compilerOptions": {
-    "plugins": [
-      { "transform": "@signaltree/callable-syntax" }
-    ]
+    "plugins": [{ "transform": "@signaltree/callable-syntax" }]
   }
 }
 ```
@@ -1702,25 +1741,26 @@ const name = tree.$.name();       // Direct Angular signal API
 import { callableSyntaxTransform } from '@signaltree/callable-syntax/rollup';
 
 export default {
-  plugins: [
-    callableSyntaxTransform()
-  ]
+  plugins: [callableSyntaxTransform()],
 };
 ```
 
 **Important Notes:**
+
 - **Optional:** You can always use direct `.set(value)` or `.update(fn)` syntax
 - **Build-time only:** No runtime code is added to your bundle
 - **Function-valued leaves:** When storing functions, use `.set(fn)` directly
 - **Type-safe:** Full TypeScript support via module augmentation
 
 **When to use:**
+
 - Prefer shorter, more concise syntax
 - Team convention favors callable style
 - Migrating from other signal libraries with similar syntax
 - Want familiar DX without runtime overhead
 
 **When to skip:**
+
 - Team prefers explicit `.set/.update` syntax
 - Build pipeline doesn't support transformers
 - Storing functions as signal values (use direct `.set`)
@@ -1732,6 +1772,7 @@ export default {
 ## Package Selection Guide
 
 **Start with just `@signaltree/core`** - it includes comprehensive enhancers for most applications:
+
 - Performance optimization (batching, memoization)
 - Data management (entities, async operations)
 - Development tools (devtools, time-travel)
@@ -1739,12 +1780,12 @@ export default {
 
 **Add companion packages when you need:**
 
-| Package | When to Add | Bundle Impact |
-|---------|------------|---------------|
-| `@signaltree/ng-forms` | Angular Reactive Forms integration | ~10KB gzipped |
-| `@signaltree/enterprise` | 500+ signals, large-scale apps | ~8KB gzipped |
-| `@signaltree/guardrails` | Development performance monitoring | 0KB (dev-only) |
-| `@signaltree/callable-syntax` | Prefer callable syntax sugar | 0KB (build-time) |
+| Package                       | When to Add                        | Bundle Impact    |
+| ----------------------------- | ---------------------------------- | ---------------- |
+| `@signaltree/ng-forms`        | Angular Reactive Forms integration | ~10KB gzipped    |
+| `@signaltree/enterprise`      | 500+ signals, large-scale apps     | ~8KB gzipped     |
+| `@signaltree/guardrails`      | Development performance monitoring | 0KB (dev-only)   |
+| `@signaltree/callable-syntax` | Prefer callable syntax sugar       | 0KB (build-time) |
 
 **Typical Installation Patterns:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "4.0.15",
+  "version": "4.0.16",
   "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/dist/enhancers/batching/index.d.ts

@@ -1 +0,0 @@
-export * from './lib/batching';

package/dist/enhancers/batching/index.js

@@ -1 +0,0 @@
-export * from './lib/batching';

package/dist/enhancers/batching/jest.config.d.ts

@@ -1,15 +0,0 @@
-declare const _default: {
-    displayName: string;
-    preset: string;
-    setupFilesAfterEnv: string[];
-    coverageDirectory: string;
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': (string | {
-            tsconfig: string;
-            stringifyContentPathRegex: string;
-        })[];
-    };
-    transformIgnorePatterns: string[];
-    snapshotSerializers: string[];
-};
-export default _default;

package/dist/enhancers/batching/jest.config.js

@@ -1,21 +0,0 @@
-export default {
-    displayName: 'batching',
-    preset: '../../../../../jest.preset.js',
-    setupFilesAfterEnv: ['<rootDir>/test-setup.ts'],
-    coverageDirectory: '../../../../../coverage/packages/core/enhancers/batching',
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': [
-            'jest-preset-angular',
-            {
-                tsconfig: '<rootDir>/tsconfig.spec.json',
-                stringifyContentPathRegex: '\\.(html|svg)$',
-            },
-        ],
-    },
-    transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
-    snapshotSerializers: [
-        'jest-preset-angular/build/serializers/no-ng-attributes',
-        'jest-preset-angular/build/serializers/ng-snapshot',
-        'jest-preset-angular/build/serializers/html-comment',
-    ],
-};

package/dist/enhancers/batching/lib/batching.d.ts

@@ -1,16 +0,0 @@
-import type { SignalTree } from '../../../lib/types';
-interface BatchingConfig {
-    enabled?: boolean;
-    maxBatchSize?: number;
-    autoFlushDelay?: number;
-    batchTimeoutMs?: number;
-}
-interface BatchingSignalTree<T> extends SignalTree<T> {
-    batchUpdate(updater: (current: T) => Partial<T>): void;
-}
-export declare function withBatching<T>(config?: BatchingConfig): (tree: SignalTree<T>) => BatchingSignalTree<T>;
-export declare function withHighPerformanceBatching<T>(): (tree: SignalTree<T>) => BatchingSignalTree<T>;
-export declare function flushBatchedUpdates(): void;
-export declare function hasPendingUpdates(): boolean;
-export declare function getBatchQueueSize(): number;
-export {};

package/dist/enhancers/batching/lib/batching.js

@@ -1,155 +0,0 @@
-import { parsePath } from '@signaltree/shared';
-import { isNodeAccessor } from '../../../lib/utils';
-let updateQueue = [];
-let isUpdating = false;
-let flushTimeoutId;
-let currentBatchingConfig = {};
-function addToQueue(update, config = currentBatchingConfig) {
-    const maxSize = config.maxBatchSize ?? 100;
-    if (update.path) {
-        updateQueue = updateQueue.filter((existing) => existing.path !== update.path);
-    }
-    updateQueue.push(update);
-    if (updateQueue.length > maxSize) {
-        flushUpdates();
-        return true;
-    }
-    scheduleFlush(config);
-    return false;
-}
-function scheduleFlush(config) {
-    if (flushTimeoutId !== undefined) {
-        clearTimeout(flushTimeoutId);
-    }
-    const delay = config.autoFlushDelay ?? 16;
-    flushTimeoutId = setTimeout(() => {
-        flushUpdates();
-    }, delay);
-}
-function flushUpdates() {
-    if (isUpdating)
-        return;
-    let queue;
-    do {
-        if (updateQueue.length === 0)
-            return;
-        isUpdating = true;
-        queue = updateQueue;
-        updateQueue = [];
-        if (flushTimeoutId !== undefined) {
-            clearTimeout(flushTimeoutId);
-            flushTimeoutId = undefined;
-        }
-        queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
-        try {
-            queue.forEach(({ fn }) => fn());
-        }
-        finally {
-            isUpdating = false;
-        }
-    } while (updateQueue.length > 0);
-}
-function batchUpdates(fn, path) {
-    const startTime = performance.now();
-    const depth = path ? parsePath(path).length : 0;
-    const update = { fn, startTime, depth, path };
-    const wasFlushed = addToQueue(update, currentBatchingConfig);
-    if (!wasFlushed) {
-        const isTimedOut = currentBatchingConfig.batchTimeoutMs &&
-            updateQueue.length > 0 &&
-            startTime - updateQueue[0].startTime >=
-                currentBatchingConfig.batchTimeoutMs;
-        if (isTimedOut) {
-            flushUpdates();
-        }
-        else if (!isUpdating && updateQueue.length > 0) {
-            queueMicrotask(() => {
-                flushUpdates();
-            });
-        }
-    }
-}
-export function withBatching(config = {}) {
-    const { enabled = true } = config;
-    currentBatchingConfig = { ...currentBatchingConfig, ...config };
-    return (tree) => {
-        if (!enabled) {
-            return tree;
-        }
-        const originalTreeCall = tree.bind(tree);
-        const enhancedTree = function (...args) {
-            if (args.length === 0) {
-                return originalTreeCall();
-            }
-            else {
-                batchUpdates(() => {
-                    if (args.length === 1) {
-                        const arg = args[0];
-                        if (typeof arg === 'function') {
-                            originalTreeCall(arg);
-                        }
-                        else {
-                            originalTreeCall(arg);
-                        }
-                    }
-                });
-            }
-        };
-        Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
-        Object.assign(enhancedTree, tree);
-        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,
-            });
-        }
-        enhancedTree.batchUpdate = (updater) => {
-            batchUpdates(() => {
-                const current = originalTreeCall();
-                const updates = updater(current);
-                Object.entries(updates).forEach(([key, value]) => {
-                    const property = enhancedTree.state[key];
-                    if (property && 'set' in property) {
-                        property.set(value);
-                    }
-                    else if (isNodeAccessor(property)) {
-                        property(value);
-                    }
-                });
-            });
-        };
-        return enhancedTree;
-    };
-}
-export function withHighPerformanceBatching() {
-    return withBatching({
-        enabled: true,
-        maxBatchSize: 200,
-        batchTimeoutMs: 0,
-    });
-}
-export function flushBatchedUpdates() {
-    if (updateQueue.length > 0) {
-        const queue = updateQueue.slice();
-        updateQueue = [];
-        isUpdating = false;
-        queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
-        queue.forEach(({ fn }) => {
-            fn();
-        });
-    }
-}
-export function hasPendingUpdates() {
-    return updateQueue.length > 0;
-}
-export function getBatchQueueSize() {
-    return updateQueue.length;
-}

package/dist/enhancers/batching/test-setup.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/enhancers/batching/test-setup.js

@@ -1,5 +0,0 @@
-import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
-setupZoneTestEnv({
-    errorOnUnknownElements: true,
-    errorOnUnknownProperties: true,
-});

package/dist/enhancers/computed/index.d.ts

@@ -1 +0,0 @@
-export * from './lib/computed';

package/dist/enhancers/computed/index.js

@@ -1 +0,0 @@
-export * from './lib/computed';

package/dist/enhancers/computed/jest.config.d.ts

@@ -1,15 +0,0 @@
-declare const _default: {
-    displayName: string;
-    preset: string;
-    setupFilesAfterEnv: string[];
-    coverageDirectory: string;
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': (string | {
-            tsconfig: string;
-            stringifyContentPathRegex: string;
-        })[];
-    };
-    transformIgnorePatterns: string[];
-    snapshotSerializers: string[];
-};
-export default _default;

package/dist/enhancers/computed/jest.config.js

@@ -1,21 +0,0 @@
-export default {
-    displayName: 'computed',
-    preset: '../../../jest.preset.js',
-    setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
-    coverageDirectory: '../../../coverage/packages/core/enhancers/computed',
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': [
-            'jest-preset-angular',
-            {
-                tsconfig: '<rootDir>/tsconfig.spec.json',
-                stringifyContentPathRegex: '\\.(html|svg)$',
-            },
-        ],
-    },
-    transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
-    snapshotSerializers: [
-        'jest-preset-angular/build/serializers/no-ng-attributes',
-        'jest-preset-angular/build/serializers/ng-snapshot',
-        'jest-preset-angular/build/serializers/html-comment',
-    ],
-};

package/dist/enhancers/computed/lib/computed.d.ts

@@ -1,12 +0,0 @@
-import { Signal } from '@angular/core';
-import type { TreeNode, SignalTree } from '../../../lib/types';
-export interface ComputedConfig {
-    lazy?: boolean;
-    memoize?: boolean;
-}
-export type ComputedSignal<T> = Signal<T>;
-export interface ComputedSignalTree<T extends Record<string, unknown>> extends SignalTree<T> {
-    computed<U>(computeFn: (tree: TreeNode<T>) => U): ComputedSignal<U>;
-}
-export declare function computedEnhancer(_config?: ComputedConfig): import("../../../lib/types").EnhancerWithMeta<SignalTree<Record<string, unknown>>, ComputedSignalTree<Record<string, unknown>>>;
-export declare function createComputed<T>(dependencies: readonly Signal<unknown>[], computeFn: () => T): ComputedSignal<T>;

package/dist/enhancers/computed/lib/computed.js

@@ -1,19 +0,0 @@
-import { computed } from '@angular/core';
-import { createEnhancer } from '../..';
-export function computedEnhancer(_config = {}) {
-    void _config;
-    return createEnhancer({
-        name: 'computed',
-        provides: ['computed'],
-        requires: [],
-    }, (tree) => {
-        const computedTree = tree;
-        computedTree.computed = function (computeFn) {
-            return computed(() => computeFn(tree.state));
-        };
-        return computedTree;
-    });
-}
-export function createComputed(dependencies, computeFn) {
-    return computed(computeFn);
-}

package/dist/enhancers/devtools/index.d.ts

@@ -1 +0,0 @@
-export * from './lib/devtools';

package/dist/enhancers/devtools/index.js

@@ -1 +0,0 @@
-export * from './lib/devtools';

package/dist/enhancers/devtools/jest.config.d.ts

@@ -1,15 +0,0 @@
-declare const _default: {
-    displayName: string;
-    preset: string;
-    setupFilesAfterEnv: string[];
-    coverageDirectory: string;
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': (string | {
-            tsconfig: string;
-            stringifyContentPathRegex: string;
-        })[];
-    };
-    transformIgnorePatterns: string[];
-    snapshotSerializers: string[];
-};
-export default _default;

package/dist/enhancers/devtools/jest.config.js

@@ -1,21 +0,0 @@
-export default {
-    displayName: 'devtools',
-    preset: '../../../jest.preset.js',
-    setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
-    coverageDirectory: '../../../coverage/packages/core/enhancers/devtools',
-    transform: {
-        '^.+\\.(ts|mjs|js|html)$': [
-            'jest-preset-angular',
-            {
-                tsconfig: '<rootDir>/tsconfig.spec.json',
-                stringifyContentPathRegex: '\\.(html|svg)$',
-            },
-        ],
-    },
-    transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
-    snapshotSerializers: [
-        'jest-preset-angular/build/serializers/no-ng-attributes',
-        'jest-preset-angular/build/serializers/ng-snapshot',
-        'jest-preset-angular/build/serializers/html-comment',
-    ],
-};