@signaltree/enterprise 4.0.6 → 4.0.9

package/LICENSE

@@ -0,0 +1,54 @@
+BUSINESS SOURCE LICENSE 1.1
+
+Copyright (c) 2025 Jonathan D Borgia
+
+This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
+
+1. Definitions
+
+"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
+
+"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
+
+"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
+
+"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
+
+2. License Grant
+
+Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
+
+3. Commercial Use
+
+You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
+
+4. Limitations and Conditions
+
+a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
+
+b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
+
+c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
+
+5. Disclaimer and Limitation of Liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
+
+6. Change License
+
+On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
+
+7. Governing Law
+
+This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
+
+8. Accepting this License
+
+You accept this License by copying, modifying, or distributing the Software or any portion thereof.
+
+---
+
+LICENSE NOTE
+
+- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
+  or standard modifications for your own applications.

package/README.md

@@ -0,0 +1,203 @@
+# @signaltree/enterprise
+
+Enterprise-grade optimizations for SignalTree. Designed for large-scale applications with 500+ signals and high-frequency bulk updates.
+
+## Features
+
+- **Diff-based updates** - Only update signals that actually changed
+- **Bulk operation optimization** - 2-5x faster for large state updates
+- **Advanced change tracking** - Detailed statistics and monitoring
+- **Path indexing** - Optimized signal lookup for large trees
+- **Lazy initialization** - Zero overhead until first use
+
+## Installation
+
+```bash
+npm install @signaltree/core @signaltree/enterprise
+```
+
+## Quick Start
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withEnterprise } from '@signaltree/enterprise';
+
+const tree = signalTree(largeState).with(withEnterprise());
+
+// Use optimized bulk updates
+const result = tree.updateOptimized(newData, {
+  ignoreArrayOrder: true,
+  maxDepth: 10,
+});
+
+console.log(result.stats);
+// { totalChanges: 45, adds: 10, updates: 30, deletes: 5 }
+```
+
+## When to Use
+
+### ✅ Use @signaltree/enterprise when:
+
+- You have 500+ signals in your state tree
+- Bulk updates happen at high frequency (60Hz+)
+- You need real-time dashboards or data feeds
+- You're building enterprise-scale applications
+- You need detailed update monitoring and statistics
+
+### ❌ Skip @signaltree/enterprise when:
+
+- Small to medium apps (<100 signals)
+- Infrequent state updates
+- Startup/prototype projects
+- Bundle size is critical (adds +2.4KB gzipped)
+
+## API
+
+### `withEnterprise()`
+
+Enhancer that adds enterprise optimizations to a SignalTree.
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withEnterprise } from '@signaltree/enterprise';
+
+const tree = signalTree(initialState).with(withEnterprise());
+```
+
+### `tree.updateOptimized(updates, options?)`
+
+Performs optimized bulk updates using diff-based change detection.
+
+**Parameters:**
+
+- `updates: Partial<T>` - The new state values
+- `options?: UpdateOptions` - Configuration options
+
+**Options:**
+
+```typescript
+{
+  maxDepth?: number;              // Maximum depth to traverse (default: 100)
+  ignoreArrayOrder?: boolean;     // Ignore array element order (default: false)
+  equalityFn?: (a, b) => boolean; // Custom equality function
+  autoBatch?: boolean;            // Automatically batch updates (default: true)
+  batchSize?: number;             // Patches per batch (default: 10)
+}
+```
+
+**Returns:**
+
+```typescript
+{
+  changed: boolean; // Whether any changes were made
+  stats: {
+    totalChanges: number; // Total number of changes
+    adds: number; // New properties added
+    updates: number; // Properties updated
+    deletes: number; // Properties deleted
+  }
+}
+```
+
+### `tree.getPathIndex()`
+
+Get the PathIndex for debugging/monitoring. Returns `null` if `updateOptimized` hasn't been called yet (lazy initialization).
+
+```typescript
+const index = tree.getPathIndex();
+if (index) {
+  console.log('Path index active');
+}
+```
+
+## Examples
+
+### Real-time Dashboard
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withEnterprise } from '@signaltree/enterprise';
+
+interface DashboardState {
+  metrics: Record<string, number>;
+  alerts: Alert[];
+  users: User[];
+  // ... hundreds more properties
+}
+
+const dashboard = signalTree<DashboardState>(initialState).with(withEnterprise());
+
+// High-frequency updates from WebSocket
+socket.on('metrics', (newMetrics) => {
+  const result = dashboard.updateOptimized({ metrics: newMetrics }, { ignoreArrayOrder: true });
+
+  console.log(`Updated ${result.stats.updates} metrics`);
+});
+```
+
+### Data Grid with Bulk Operations
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withEnterprise } from '@signaltree/enterprise';
+
+const grid = signalTree({
+  rows: [] as GridRow[],
+  columns: [] as GridColumn[],
+  filters: {} as FilterState,
+  selection: new Set<string>(),
+}).with(withEnterprise());
+
+// Bulk update from API
+async function loadData() {
+  const data = await fetchGridData();
+
+  const result = grid.updateOptimized(data, {
+    maxDepth: 5,
+    autoBatch: true,
+  });
+
+  console.log(`Loaded ${result.stats.adds} rows in bulk`);
+}
+```
+
+### Custom Equality for Complex Objects
+
+```typescript
+const tree = signalTree(complexState).with(withEnterprise());
+
+tree.updateOptimized(newState, {
+  equalityFn: (a, b) => {
+    // Custom deep equality for specific object types
+    if (a instanceof Date && b instanceof Date) {
+      return a.getTime() === b.getTime();
+    }
+    return a === b;
+  },
+});
+```
+
+## Performance
+
+**Bundle Size:**
+
+- Adds +2.4KB gzipped to your bundle
+- Zero overhead until first `updateOptimized()` call (lazy initialization)
+
+**Performance Gains:**
+
+- 2-5x faster for bulk updates on large state trees
+- Scales efficiently with tree depth and complexity
+- Minimal memory overhead with path indexing
+
+## License
+
+Business Source License 1.1 (BSL-1.1) - See [LICENSE](../../LICENSE) for details.
+
+Converts to MIT license on the Change Date specified in the license.
+
+## Related Packages
+
+- [@signaltree/core](../core) - Core SignalTree functionality
+- [@signaltree/ng-forms](../ng-forms) - Angular forms integration
+- [@signaltree/callable-syntax](../callable-syntax) - Callable syntax transform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/enterprise",
-  "version": "4.0.6",
+  "version": "4.0.9",
   "description": "Enterprise-grade optimizations for SignalTree. Provides diff-based updates, bulk operation optimization, and advanced change tracking for large-scale applications.",
   "type": "module",
   "sideEffects": false,

package/src/lib/diff-engine.spec.ts

@@ -0,0 +1,384 @@
+import { ChangeType, DiffEngine } from './diff-engine';
+
+describe('DiffEngine', () => {
+  let engine: DiffEngine;
+
+  beforeEach(() => {
+    engine = new DiffEngine();
+  });
+
+  describe('primitive values', () => {
+    it('should detect primitive changes', () => {
+      const current = { value: 42 };
+      const updates = { value: 43 };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes).toHaveLength(1);
+      expect(diff.changes[0]).toEqual({
+        type: ChangeType.UPDATE,
+        path: ['value'],
+        value: 43,
+        oldValue: 42,
+      });
+    });
+
+    it('should detect no changes when values are equal', () => {
+      const current = { value: 42 };
+      const updates = { value: 42 };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(false);
+      expect(diff.changes).toHaveLength(0);
+    });
+
+    it('should detect additions', () => {
+      const current = {};
+      const updates = { newField: 'hello' };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes[0].type).toBe(ChangeType.ADD);
+      expect(diff.changes[0].value).toBe('hello');
+    });
+
+    it('should detect null values correctly', () => {
+      const current = { value: null };
+      const updates = { value: 'not null' };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes[0].oldValue).toBeNull();
+      expect(diff.changes[0].value).toBe('not null');
+    });
+  });
+
+  describe('nested objects', () => {
+    it('should detect deep changes', () => {
+      const current = {
+        user: {
+          profile: {
+            name: 'Alice',
+            age: 30,
+          },
+        },
+      };
+
+      const updates = {
+        user: {
+          profile: {
+            name: 'Alice',
+            age: 31, // Changed
+          },
+        },
+      };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes).toHaveLength(1);
+      expect(diff.changes[0]).toEqual({
+        type: ChangeType.UPDATE,
+        path: ['user', 'profile', 'age'],
+        value: 31,
+        oldValue: 30,
+      });
+    });
+
+    it('should detect multiple changes', () => {
+      const current = {
+        name: 'Alice',
+        age: 30,
+        city: 'NYC',
+      };
+
+      const updates = {
+        name: 'Alice',
+        age: 31, // Changed
+        city: 'SF', // Changed
+      };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes).toHaveLength(2);
+
+      const paths = diff.changes.map((c) => c.path.join('.'));
+      expect(paths).toContain('age');
+      expect(paths).toContain('city');
+    });
+
+    it('should handle partial updates', () => {
+      const current = {
+        user: {
+          name: 'Alice',
+          age: 30,
+          email: 'alice@example.com',
+        },
+      };
+
+      const updates = {
+        user: {
+          age: 31, // Only updating age
+        },
+      };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes).toHaveLength(1);
+      expect(diff.changes[0].path).toEqual(['user', 'age']);
+    });
+  });
+
+  describe('arrays', () => {
+    it('should detect array element changes (ordered)', () => {
+      const current = { items: [1, 2, 3] };
+      const updates = { items: [1, 4, 3] }; // Changed index 1
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes).toHaveLength(1);
+      expect(diff.changes[0]).toEqual({
+        type: ChangeType.UPDATE,
+        path: ['items', 1],
+        value: 4,
+        oldValue: 2,
+      });
+    });
+
+    it('should detect array additions', () => {
+      const current = { items: [1, 2] };
+      const updates = { items: [1, 2, 3] }; // Added element
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      const addition = diff.changes.find((c) => c.type === ChangeType.ADD);
+      expect(addition).toBeDefined();
+      expect(addition?.path).toEqual(['items', 2]);
+      expect(addition?.value).toBe(3);
+    });
+
+    it('should handle empty arrays', () => {
+      const current = { items: [] };
+      const updates = { items: [1] };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes[0].type).toBe(ChangeType.ADD);
+    });
+
+    it('should handle nested arrays', () => {
+      const current = {
+        matrix: [
+          [1, 2],
+          [3, 4],
+        ],
+      };
+
+      const updates = {
+        matrix: [
+          [1, 2],
+          [3, 5], // Changed [1][1]
+        ],
+      };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes[0].path).toEqual(['matrix', 1, 1]);
+      expect(diff.changes[0].value).toBe(5);
+    });
+  });
+
+  describe('type changes', () => {
+    it('should detect object to primitive as update', () => {
+      const current = { value: { nested: 'object' } };
+      const updates = { value: 'string' }; // Type changed
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      // Nested object to primitive is UPDATE, not REPLACE
+      expect(diff.changes[0].type).toBe(ChangeType.UPDATE);
+      expect(diff.changes[0].path).toEqual(['value']);
+    });
+
+    it('should replace object with array', () => {
+      const current = { data: { a: 1 } };
+      const updates = { data: [1, 2, 3] };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.changes[0].type).toBe(ChangeType.REPLACE);
+    });
+
+    it('should replace array with object', () => {
+      const current = { data: [1, 2, 3] };
+      const updates = { data: { a: 1 } };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.changes[0].type).toBe(ChangeType.REPLACE);
+    });
+  });
+
+  describe('options', () => {
+    it('should respect maxDepth option', () => {
+      const current = {
+        level1: {
+          level2: {
+            level3: {
+              level4: {
+                deep: 'value',
+              },
+            },
+          },
+        },
+      };
+
+      const updates = {
+        level1: {
+          level2: {
+            level3: {
+              level4: {
+                deep: 'changed',
+              },
+            },
+          },
+        },
+      };
+
+      const diff = engine.diff(current, updates, { maxDepth: 2 });
+
+      // Should stop at depth 2, so level3+ changes won't be detected
+      expect(diff.changes).toHaveLength(0);
+    });
+
+    it('should detect deletions when enabled', () => {
+      const current = { a: 1, b: 2, c: 3 };
+      const updates = { a: 1, b: 2 }; // 'c' deleted
+
+      const diff = engine.diff(current, updates, { detectDeletions: true });
+
+      const deletion = diff.changes.find((c) => c.type === ChangeType.DELETE);
+      expect(deletion).toBeDefined();
+      expect(deletion?.path).toEqual(['c']);
+      expect(deletion?.oldValue).toBe(3);
+    });
+
+    it('should not detect deletions by default', () => {
+      const current = { a: 1, b: 2 };
+      const updates = { a: 1 }; // 'b' deleted
+
+      const diff = engine.diff(current, updates);
+
+      const deletion = diff.changes.find((c) => c.type === ChangeType.DELETE);
+      expect(deletion).toBeUndefined();
+    });
+
+    it('should use custom equality function', () => {
+      const current = { value: '42' };
+      const updates = { value: 42 }; // Different type, same value
+
+      // Default behavior - detects change
+      const diff1 = engine.diff(current, updates);
+      expect(diff1.hasChanges).toBe(true);
+
+      // Custom equality - coerce types
+      const diff2 = engine.diff(current, updates, {
+        equalityFn: (a, b) => String(a) === String(b),
+      });
+      expect(diff2.hasChanges).toBe(false);
+    });
+
+    it('should handle ignoreArrayOrder option', () => {
+      const current = { items: [1, 2, 3] };
+      const updates = { items: [3, 2, 1] }; // Same values, different order
+
+      // With ignoreArrayOrder, should detect no changes
+      const diff = engine.diff(current, updates, { ignoreArrayOrder: true });
+
+      expect(diff.hasChanges).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle circular references', () => {
+      interface Circular {
+        a: number;
+        self?: Circular;
+      }
+      const circular: Circular = { a: 1 };
+      circular.self = circular;
+
+      const updates = { a: 2, self: circular };
+
+      // Should not throw or hang
+      expect(() => {
+        engine.diff(circular, updates);
+      }).not.toThrow();
+    });
+
+    it('should handle undefined values', () => {
+      const current = { value: undefined };
+      const updates = { value: 'defined' };
+
+      const diff = engine.diff(current, updates);
+
+      expect(diff.hasChanges).toBe(true);
+      expect(diff.changes[0].oldValue).toBeUndefined();
+    });
+  });
+
+  describe('performance', () => {
+    it('should handle large objects efficiently', () => {
+      const current = {
+        items: Array.from({ length: 1000 }, (_, i) => ({
+          id: i,
+          value: i,
+        })),
+      };
+
+      const updates = {
+        items: Array.from({ length: 1000 }, (_, i) => ({
+          id: i,
+          value: i === 500 ? 999 : i, // Only change one item
+        })),
+      };
+
+      const start = performance.now();
+      const diff = engine.diff(current, updates);
+      const duration = performance.now() - start;
+
+      // Should detect only the one change
+      expect(diff.changes).toHaveLength(1);
+      expect(diff.changes[0].path).toEqual(['items', 500, 'value']);
+
+      // Should be reasonably fast
+      expect(duration).toBeLessThan(100); // < 100ms for 1000 items
+    });
+
+    it('should skip dangerous keys during diff', () => {
+      const current = {};
+      const updates = {
+        __proto__: { polluted: true },
+        safe: 'value',
+      };
+
+      const diff = engine.diff(current, updates, {
+        keyValidator: (key) => !['__proto__', 'constructor'].includes(key),
+      });
+
+      expect(diff.changes.map((c) => c.path[0])).not.toContain('__proto__');
+      expect(diff.changes.map((c) => c.path[0])).toContain('safe');
+    });
+  });
+});