@signaltree/enterprise 4.0.7 → 4.0.9

package/src/lib/diff-engine.ts

@@ -0,0 +1,351 @@
+/**
+ * DiffEngine - Efficient change detection for tree updates
+ * @packageDocumentation
+ */
+
+import type { Path } from './path-index';
+
+/**
+ * Type of change detected
+ */
+export enum ChangeType {
+  ADD = 'add',
+  UPDATE = 'update',
+  DELETE = 'delete',
+  REPLACE = 'replace',
+}
+
+/**
+ * A detected change
+ */
+export interface Change {
+  /** Type of change */
+  type: ChangeType;
+
+  /** Path to the changed value */
+  path: Path;
+
+  /** New value */
+  value?: unknown;
+
+  /** Old value (for updates/deletes) */
+  oldValue?: unknown;
+}
+
+/**
+ * Diff result
+ */
+export interface Diff {
+  /** List of changes */
+  changes: Change[];
+
+  /** Whether any changes were detected */
+  hasChanges: boolean;
+}
+
+/**
+ * Configuration for diff operation
+ */
+export interface DiffOptions {
+  /** Maximum depth to traverse */
+  maxDepth?: number;
+
+  /** Whether to detect deletions */
+  detectDeletions?: boolean;
+
+  /** Whether to ignore array order */
+  ignoreArrayOrder?: boolean;
+
+  /** Custom equality function */
+  equalityFn?: (a: unknown, b: unknown) => boolean;
+
+  /** Optional key validator for security (e.g., to prevent prototype pollution) */
+  keyValidator?: (key: string) => boolean;
+}
+
+/**
+ * Internal resolved options with required fields
+ */
+type ResolvedDiffOptions = Required<Omit<DiffOptions, 'keyValidator'>> & {
+  keyValidator?: (key: string) => boolean;
+};
+
+/**
+ * DiffEngine
+ *
+ * Efficiently detects changes between two objects to minimize unnecessary updates.
+ *
+ * Features:
+ * - Deep object comparison
+ * - Circular reference detection
+ * - Configurable equality checking
+ * - Array diffing (ordered and unordered)
+ * - Path tracking for precise updates
+ *
+ * @example
+ * ```ts
+ * const engine = new DiffEngine();
+ *
+ * const current = { user: { name: 'Alice', age: 30 } };
+ * const updates = { user: { name: 'Alice', age: 31 } };
+ *
+ * const diff = engine.diff(current, updates);
+ *
+ * console.log(diff.changes);
+ * // [{ type: 'update', path: ['user', 'age'], value: 31, oldValue: 30 }]
+ * ```
+ */
+export class DiffEngine {
+  private defaultOptions: ResolvedDiffOptions = {
+    maxDepth: 100,
+    detectDeletions: false,
+    ignoreArrayOrder: false,
+    equalityFn: (a, b) => a === b,
+    keyValidator: undefined,
+  };
+
+  /**
+   * Diff two objects and return changes
+   *
+   * @param current - Current state
+   * @param updates - Updated state
+   * @param options - Diff options
+   * @returns Diff result with all changes
+   */
+  diff(current: unknown, updates: unknown, options: DiffOptions = {}): Diff {
+    const opts = { ...this.defaultOptions, ...options };
+    const changes: Change[] = [];
+    const visited = new WeakSet();
+
+    this.traverse(current, updates, [], changes, visited, opts, 0);
+
+    return {
+      changes,
+      hasChanges: changes.length > 0,
+    };
+  }
+
+  /**
+   * Traverse and compare objects recursively
+   */
+  private traverse(
+    curr: unknown,
+    upd: unknown,
+    path: Path,
+    changes: Change[],
+    visited: WeakSet<object>,
+    opts: ResolvedDiffOptions,
+    depth: number
+  ): void {
+    // Depth limit
+    if (depth > opts.maxDepth) {
+      return;
+    }
+
+    // Handle primitives
+    if (typeof upd !== 'object' || upd === null) {
+      if (!opts.equalityFn(curr, upd)) {
+        changes.push({
+          type: curr === undefined ? ChangeType.ADD : ChangeType.UPDATE,
+          path: [...path],
+          value: upd,
+          oldValue: curr,
+        });
+      }
+      return;
+    }
+
+    // Circular reference detection
+    if (visited.has(upd)) {
+      return;
+    }
+    visited.add(upd);
+
+    // Handle arrays
+    if (Array.isArray(upd)) {
+      this.diffArrays(curr, upd, path, changes, visited, opts, depth);
+      return;
+    }
+
+    // Handle objects
+    if (!curr || typeof curr !== 'object' || Array.isArray(curr)) {
+      // Type mismatch - replace entire subtree
+      changes.push({
+        type: ChangeType.REPLACE,
+        path: [...path],
+        value: upd,
+        oldValue: curr,
+      });
+      return;
+    }
+
+    // Diff object properties
+    const currObj = curr as Record<string, unknown>;
+    const updObj = upd as Record<string, unknown>;
+
+    for (const key in updObj) {
+      if (Object.prototype.hasOwnProperty.call(updObj, key)) {
+        // Validate key for security (e.g., prevent prototype pollution)
+        if (opts.keyValidator && !opts.keyValidator(key)) {
+          // Skip dangerous keys silently
+          continue;
+        }
+
+        this.traverse(
+          currObj[key],
+          updObj[key],
+          [...path, key],
+          changes,
+          visited,
+          opts,
+          depth + 1
+        );
+      }
+    }
+
+    // Check for deletions if enabled
+    if (opts.detectDeletions) {
+      for (const key in currObj) {
+        if (
+          Object.prototype.hasOwnProperty.call(currObj, key) &&
+          !(key in updObj)
+        ) {
+          changes.push({
+            type: ChangeType.DELETE,
+            path: [...path, key],
+            oldValue: currObj[key],
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Diff arrays
+   */
+  private diffArrays(
+    curr: unknown,
+    upd: unknown[],
+    path: Path,
+    changes: Change[],
+    visited: WeakSet<object>,
+    opts: ResolvedDiffOptions,
+    depth: number
+  ): void {
+    if (!Array.isArray(curr)) {
+      // Not an array - replace
+      changes.push({
+        type: ChangeType.REPLACE,
+        path: [...path],
+        value: upd,
+        oldValue: curr,
+      });
+      return;
+    }
+
+    if (opts.ignoreArrayOrder) {
+      this.diffArraysUnordered(curr, upd, path, changes, opts);
+    } else {
+      this.diffArraysOrdered(curr, upd, path, changes, visited, opts, depth);
+    }
+  }
+
+  /**
+   * Diff arrays in order (index-based)
+   */
+  private diffArraysOrdered(
+    curr: unknown[],
+    upd: unknown[],
+    path: Path,
+    changes: Change[],
+    visited: WeakSet<object>,
+    opts: ResolvedDiffOptions,
+    depth: number
+  ): void {
+    // Check each index
+    const maxLength = Math.max(curr.length, upd.length);
+
+    for (let i = 0; i < maxLength; i++) {
+      if (i >= upd.length) {
+        // Deletion (if enabled)
+        if (opts.detectDeletions) {
+          changes.push({
+            type: ChangeType.DELETE,
+            path: [...path, i],
+            oldValue: curr[i],
+          });
+        }
+      } else if (i >= curr.length) {
+        // Addition
+        changes.push({
+          type: ChangeType.ADD,
+          path: [...path, i],
+          value: upd[i],
+        });
+      } else {
+        // Potential update
+        this.traverse(
+          curr[i],
+          upd[i],
+          [...path, i],
+          changes,
+          visited,
+          opts,
+          depth + 1
+        );
+      }
+    }
+  }
+
+  /**
+   * Diff arrays ignoring order (value-based)
+   */
+  private diffArraysUnordered(
+    curr: unknown[],
+    upd: unknown[],
+    path: Path,
+    changes: Change[],
+    opts: ResolvedDiffOptions
+  ): void {
+    // Build value sets
+    const currSet = new Set(curr.map((v) => this.stringify(v)));
+    const updSet = new Set(upd.map((v) => this.stringify(v)));
+
+    // Find additions
+    upd.forEach((value, index) => {
+      const str = this.stringify(value);
+      if (!currSet.has(str)) {
+        changes.push({
+          type: ChangeType.ADD,
+          path: [...path, index],
+          value,
+        });
+      }
+    });
+
+    // Find deletions (if enabled)
+    if (opts.detectDeletions) {
+      curr.forEach((value, index) => {
+        const str = this.stringify(value);
+        if (!updSet.has(str)) {
+          changes.push({
+            type: ChangeType.DELETE,
+            path: [...path, index],
+            oldValue: value,
+          });
+        }
+      });
+    }
+  }
+
+  /**
+   * Stringify value for set comparison
+   */
+  private stringify(value: unknown): string {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+}

package/src/lib/enterprise-enhancer.ts

@@ -0,0 +1,136 @@
+import { PathIndex } from './path-index';
+import { OptimizedUpdateEngine, UpdateResult } from './update-engine';
+
+import type { Signal } from '@angular/core';
+import type { Enhancer } from '@signaltree/core';
+/**
+ * Enterprise-grade optimizations for large-scale applications.
+ *
+ * **Includes:**
+ * - Diff-based updates (only update changed signals)
+ * - Bulk operation optimization (2-5x faster)
+ * - Advanced change tracking
+ * - Update statistics and monitoring
+ *
+ * **Use when:**
+ * - 500+ signals in state tree
+ * - Bulk updates at high frequency (60Hz+)
+ * - Real-time dashboards or data feeds
+ * - Enterprise-scale applications
+ *
+ * **Skip when:**
+ * - Small to medium apps (<100 signals)
+ * - Infrequent state updates
+ * - Startup/prototype projects
+ *
+ * **Bundle cost:** +2.4KB gzipped
+ * **Performance gain:** 2-5x faster bulk updates, detailed monitoring
+ *
+ * @example
+ * ```typescript
+ * import { signalTree } from '@signaltree/core';
+ * import { withEnterprise } from '@signaltree/enterprise';
+ *
+ * const tree = signalTree(largeState).with(withEnterprise());
+ *
+ * // Now available: optimized bulk updates
+ * const result = tree.updateOptimized(newData, {
+ *   ignoreArrayOrder: true,
+ *   maxDepth: 10
+ * });
+ *
+ * console.log(result.stats);
+ * // { totalChanges: 45, adds: 10, updates: 30, deletes: 5 }
+ * ```
+ *
+ * @public
+ */
+export function withEnterprise<T extends Record<string, unknown>>(): Enhancer<
+  T,
+  T & EnterpriseEnhancedTree<T>
+> {
+  return (tree: T): T & EnterpriseEnhancedTree<T> => {
+    // Lazy initialization - only create when first needed
+    let pathIndex: PathIndex<Signal<unknown>> | null = null;
+    let updateEngine: OptimizedUpdateEngine | null = null;
+
+    // Type assertion to access SignalTree properties
+    const signalTree = tree as unknown as { state: unknown };
+
+    // Cast tree to enhanced type for safe property assignment
+    const enhancedTree = tree as T & EnterpriseEnhancedTree<T>;
+
+    // Add updateOptimized method to tree
+    enhancedTree.updateOptimized = (
+      updates: Partial<T>,
+      options?: {
+        maxDepth?: number;
+        ignoreArrayOrder?: boolean;
+        equalityFn?: (a: unknown, b: unknown) => boolean;
+        batch?: boolean;
+        batchSize?: number;
+      }
+    ): UpdateResult => {
+      // Lazy initialize on first use
+      if (!updateEngine) {
+        pathIndex = new PathIndex<Signal<unknown>>();
+        pathIndex.buildFromTree(signalTree.state);
+        updateEngine = new OptimizedUpdateEngine(signalTree.state);
+      }
+
+      const result = updateEngine.update(signalTree.state, updates, options);
+
+      // Rebuild index if changes were made
+      if (result.changed && result.stats && pathIndex) {
+        pathIndex.clear();
+        pathIndex.buildFromTree(signalTree.state);
+      }
+
+      return result;
+    };
+
+    // Add PathIndex access for debugging/monitoring
+    enhancedTree.getPathIndex = () => pathIndex;
+
+    return enhancedTree;
+  };
+}
+
+/**
+ * Type augmentation for trees enhanced with enterprise features.
+ * This is applied when using withEnterprise().
+ *
+ * @public
+ */
+export interface EnterpriseEnhancedTree<T> {
+  /**
+   * Optimized bulk update method using diff-based change detection.
+   * Only available when using withEnterprise().
+   *
+   * @param newValue - The new state value
+   * @param options - Update options
+   * @returns Update result with statistics
+   */
+  updateOptimized(
+    newValue: T,
+    options?: {
+      /** Maximum depth to traverse (default: 100) */
+      maxDepth?: number;
+      /** Ignore array element order (default: false) */
+      ignoreArrayOrder?: boolean;
+      /** Custom equality function */
+      equalityFn?: (a: unknown, b: unknown) => boolean;
+      /** Automatically batch updates (default: true) */
+      autoBatch?: boolean;
+      /** Number of patches per batch (default: 10) */
+      batchSize?: number;
+    }
+  ): UpdateResult;
+
+  /**
+   * Get the PathIndex for debugging/monitoring.
+   * Only available when using withEnterprise().
+   * Returns null if updateOptimized hasn't been called yet (lazy initialization).
+   */
+  getPathIndex(): PathIndex<Signal<unknown>> | null;
+}

package/src/lib/enterprise.spec.ts

@@ -0,0 +1,7 @@
+import { enterprise } from './enterprise';
+
+describe('enterprise', () => {
+  it('should work', () => {
+    expect(enterprise()).toEqual('enterprise');
+  });
+});

package/src/lib/enterprise.ts

@@ -0,0 +1,3 @@
+export function enterprise(): string {
+  return 'enterprise';
+}