@signaltree/core 4.0.12 → 4.0.15

package/README.md

@@ -1451,6 +1451,318 @@ import {
 } from '@signaltree/core';
 ```
 
+## Companion Packages
+
+While `@signaltree/core` includes comprehensive built-in enhancers for most use cases, the SignalTree ecosystem also provides specialized companion packages for specific needs:
+
+### 📝 @signaltree/ng-forms
+
+**Angular Reactive Forms integration for SignalTree**
+
+Seamlessly connect Angular Reactive 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.)
+
+**Quick Example:**
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { bindFormToTree } from '@signaltree/ng-forms';
+
+const tree = signalTree({
+  user: { name: '', email: '', age: 0 }
+});
+
+@Component({
+  template: `
+    <form [formGroup]="form">
+      <input formControlName="name" />
+      <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)
+  });
+
+  constructor() {
+    // Automatically sync form with tree state
+    bindFormToTree(this.form, tree.$.user);
+  }
+}
+```
+
+**When to use:**
+- Building forms with Angular Reactive Forms
+- Need validation integration
+- Two-way data binding between forms and state
+- Complex form scenarios with nested form groups
+
+**Learn more:** [npm package](https://www.npmjs.com/package/@signaltree/ng-forms)
+
+---
+
+### 🏢 @signaltree/enterprise
+
+**Enterprise-scale optimizations for large applications**
+
+Advanced performance optimizations designed for applications with 500+ signals and complex state trees.
+
+```bash
+npm install @signaltree/enterprise
+```
+
+**Features:**
+- ⚡ PathIndex for O(k) lookup time regardless of tree size
+- 🗜️ Advanced memory optimization algorithms
+- 📊 Performance profiling and monitoring
+- 🔍 Efficient path-based signal resolution
+- 🎯 Optimized for large-scale applications
+
+**Quick Example:**
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withEnterpriseOptimizations } from '@signaltree/enterprise';
+
+const tree = signalTree({
+  // Large application state with hundreds of signals
+  modules: {
+    auth: { /* ... */ },
+    data: { /* ... */ },
+    ui: { /* ... */ },
+    // ... many more modules
+  }
+}).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
+- Enterprise-scale applications with performance requirements
+- Need detailed performance profiling
+
+**Learn more:** [npm package](https://www.npmjs.com/package/@signaltree/enterprise)
+
+---
+
+### 🛡️ @signaltree/guardrails
+
+**Development-only performance monitoring and debugging**
+
+Comprehensive development tools for detecting performance issues, memory leaks, and anti-patterns during development. **Zero production overhead** via conditional exports.
+
+```bash
+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
+- ⚠️ Anti-pattern warnings - detects common mistakes
+- 📈 Real-time performance metrics
+- 🎯 Zero production overhead (no-op in production builds)
+
+**Quick Example:**
+
+```typescript
+import { signalTree } from '@signaltree/core';
+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
+  }
+}));
+
+// Development warnings will appear in console
+// Production builds get no-op functions (0 overhead)
+```
+
+**Development Features:**
+
+```typescript
+import { getPerformanceMetrics, getHotPaths, checkMemoryLeaks } from '@signaltree/guardrails';
+
+// Get detailed performance metrics
+const metrics = getPerformanceMetrics();
+console.log('Update time:', metrics.avgUpdateTime);
+console.log('Signal count:', metrics.totalSignals);
+
+// Identify hot paths
+const hotPaths = getHotPaths();
+console.log('Most accessed signals:', hotPaths);
+
+// Check for memory leaks
+const leaks = checkMemoryLeaks();
+if (leaks.length > 0) {
+  console.warn('Potential memory leaks:', leaks);
+}
+```
+
+**Conditional Exports (Zero Production Overhead):**
+
+```json
+{
+  "exports": {
+    ".": {
+      "development": "./dist/index.js",
+      "production": "./dist/noop.js"
+    }
+  }
+}
+```
+
+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
+- Team onboarding and code reviews
+- CI/CD performance regression detection
+
+**Learn more:** [npm package](https://www.npmjs.com/package/@signaltree/guardrails)
+
+---
+
+### 🎯 @signaltree/callable-syntax
+
+**Build-time transform for callable signal syntax**
+
+A TypeScript transformer that enables callable syntax sugar for setting signal values. This is **purely a developer experience enhancement** with zero runtime overhead.
+
+```bash
+npm install --save-dev @signaltree/callable-syntax
+```
+
+**Features:**
+- 🍬 Syntactic sugar for signal updates
+- ⚡ Zero runtime overhead (build-time transform)
+- ✅ Full TypeScript type safety
+- 🔧 Works with any build tool (Rollup, Webpack, esbuild, etc.)
+- 📝 Optional - use direct `.set/.update` if preferred
+
+**Syntax Transformation:**
+
+```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)
+
+// Reading always works directly (no transform needed)
+const name = tree.$.name();       // Direct Angular signal API
+```
+
+**Setup (tsconfig.json):**
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "transform": "@signaltree/callable-syntax" }
+    ]
+  }
+}
+```
+
+**Setup (Rollup):**
+
+```javascript
+import { callableSyntaxTransform } from '@signaltree/callable-syntax/rollup';
+
+export default {
+  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`)
+
+**Learn more:** [npm package](https://www.npmjs.com/package/@signaltree/callable-syntax)
+
+---
+
+## 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)
+- State persistence (serialization)
+
+**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) |
+
+**Typical Installation Patterns:**
+
+```bash
+# Basic application
+npm install @signaltree/core
+
+# Application with forms
+npm install @signaltree/core @signaltree/ng-forms
+
+# Large enterprise application
+npm install @signaltree/core @signaltree/enterprise
+
+# Development with all tools
+npm install @signaltree/core @signaltree/enterprise @signaltree/ng-forms
+npm install --save-dev @signaltree/guardrails @signaltree/callable-syntax
+```
+
 ## Links
 
 - [SignalTree Documentation](https://signaltree.io)

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

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

package/dist/enhancers/batching/index.js

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

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,155 @@
+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

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

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

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

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

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

package/dist/enhancers/computed/index.js

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

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,19 @@
+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

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

package/dist/enhancers/devtools/index.js

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

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,21 @@
+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',
+    ],
+};