@signaltree/core 4.0.13 → 4.0.16

package/README.md

@@ -1451,6 +1451,359 @@ 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 Forms integration for SignalTree (Angular 17+)**
+
+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:**
+
+```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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "4.0.13",
+  "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,
@@ -56,13 +56,7 @@
   },
   "peerDependencies": {
     "@angular/core": "^20.3.0",
-    "jest-preset-angular": "*",
-    "@rollup/plugin-commonjs": "*",
-    "@rollup/plugin-node-resolve": "*",
-    "@rollup/plugin-typescript": "*",
-    "rollup": "*",
-    "rollup-plugin-dts": "*",
-    "tslib": "*"
+    "tslib": "^2.0.0"
   },
   "files": [
     "dist",