@creact-labs/creact 0.1.0

package/dist/core/Reconciler.d.ts

@@ -0,0 +1,415 @@
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+import { CloudDOMNode } from './types';
+/**
+ * Type representing a construct (function, class, or string)
+ */
+export type ConstructLike = {
+    name?: string;
+} | Function | string;
+/**
+ * ChangeSet represents the minimal set of operations to reconcile two CloudDOM states
+ *
+ * REQ-O01: State Machine needs diff to detect changes
+ * REQ-O04: Plan Command needs diff to show preview
+ */
+export interface ChangeSet {
+    /** Nodes that exist in current but not in previous (need to be created) */
+    creates: CloudDOMNode[];
+    /** Nodes that exist in both but have different props (need to be updated) */
+    updates: CloudDOMNode[];
+    /** Nodes that exist in previous but not in current (need to be deleted) */
+    deletes: CloudDOMNode[];
+    /** Nodes that changed type (need to be replaced: delete + create) */
+    replacements: CloudDOMNode[];
+    /** Nodes that moved in the hierarchy (includes node ID for traceability) */
+    moves: Array<{
+        nodeId: string;
+        from: string;
+        to: string;
+    }>;
+    /** Deployment order based on dependency graph (topologically sorted) */
+    deploymentOrder: string[];
+    /** Parallel deployment batches (nodes at same depth can deploy in parallel) */
+    parallelBatches: string[][];
+}
+/**
+ * Helper function to get total number of changes from a ChangeSet
+ * Single source of truth for change counting
+ */
+export declare function getTotalChanges(changeSet: ChangeSet): number;
+/**
+ * Helper function to check if a ChangeSet has any changes
+ */
+export declare function hasChanges(changeSet: ChangeSet): boolean;
+/**
+ * DependencyGraph represents resource dependencies for deployment ordering
+ *
+ * Maps node ID → array of dependency IDs
+ */
+export interface DependencyGraph {
+    /** Adjacency list: node ID → dependency IDs */
+    dependencies: Map<string, string[]>;
+    /** Reverse adjacency list: node ID → dependent IDs (nodes that depend on this node) */
+    dependents: Map<string, string[]>;
+}
+/**
+ * Reconciler computes minimal change sets between CloudDOM states
+ *
+ * This is CReact's equivalent to React's Fiber reconciliation algorithm.
+ * It enables:
+ * - Incremental updates (only deploy what changed)
+ * - Plan preview (show diff before deploy)
+ * - Hot reload (apply deltas without full rebuild)
+ * - Dependency-aware ordering (deploy in correct order)
+ *
+ * REQ-O01: CloudDOM State Machine
+ * REQ-O04: Plan and Change Preview
+ */
+export declare class Reconciler {
+    /**
+     * Internal methods exposed for testing
+     *
+     * These are pure functions that are ideal for unit testing.
+     * Prefixed with __ to indicate they're internal/testing-only.
+     */
+    __testing__: {
+        buildDependencyGraph: (nodes: CloudDOMNode[]) => DependencyGraph;
+        detectChangeType: (previous: CloudDOMNode, current: CloudDOMNode) => "replacement" | "update" | "none";
+        computeParallelBatches: (deploymentOrder: string[], graph: DependencyGraph) => string[][];
+        topologicalSort: (graph: DependencyGraph) => string[];
+        extractDependencies: (node: CloudDOMNode, nodeIds: Set<string>) => string[];
+        detectMoves: (previousMap: Map<string, CloudDOMNode>, currentMap: Map<string, CloudDOMNode>) => Array<{
+            nodeId: string;
+            from: string;
+            to: string;
+        }>;
+        validateGraph: (graph: DependencyGraph) => void;
+        computeShallowHash: (props: Record<string, any>) => string;
+        isMetadataKey: (key: string) => boolean;
+    };
+    /**
+     * Generate a human-readable diff visualization for UI/CLI
+     *
+     * Formats the ChangeSet as JSON suitable for:
+     * - CLI diff previews (like Terraform plans)
+     * - Web UI diff visualization
+     * - CI/CD pipeline reports
+     *
+     * @param changeSet - ChangeSet to visualize
+     * @returns JSON-serializable diff visualization
+     */
+    generateDiffVisualization(changeSet: ChangeSet): {
+        summary: {
+            creates: number;
+            updates: number;
+            deletes: number;
+            replacements: number;
+            moves: number;
+            total: number;
+        };
+        changes: Array<{
+            type: 'create' | 'update' | 'delete' | 'replacement' | 'move';
+            nodeId: string;
+            details?: any;
+        }>;
+        deployment: {
+            order: string[];
+            batches: Array<{
+                depth: number;
+                nodes: string[];
+                parallelism: number;
+            }>;
+        };
+    };
+    /**
+     * Debug logging helper
+     * Logs messages when CREACT_DEBUG environment variable is set
+     *
+     * Supports both string messages and structured data for telemetry.
+     * Includes timestamps for async reconciliation tracing.
+     */
+    private log;
+    /**
+     * Check if a key is internal metadata (starts with underscore)
+     *
+     * Used for filtering metadata from prop comparisons and dependency scanning.
+     *
+     * @param key - Property key to check
+     * @returns True if key is metadata
+     */
+    private isMetadataKey;
+    /**
+     * Compute a shallow hash of props for fast equality checks
+     *
+     * Creates a stable, key-order-independent hash by:
+     * - Filtering out special props (metadata, key, children)
+     * - Sorting entries by key
+     * - JSON stringifying the result
+     *
+     * This enables O(1) prop comparisons for unchanged nodes.
+     *
+     * @param props - Props object to hash
+     * @returns Stable hash string
+     */
+    private computeShallowHash;
+    /**
+     * Reconcile two CloudDOM states and compute minimal change set
+     *
+     * Algorithm:
+     * 1. Build ID maps for O(n) lookup
+     * 2. Detect creates (in current, not in previous)
+     * 3. Detect updates/replacements (in both, but props or construct changed)
+     * 4. Detect deletes (in previous, not in current)
+     * 5. Detect moves (nodes that changed parent)
+     * 6. Build dependency graph from current nodes
+     * 7. Compute topological sort for deployment order
+     * 8. Group independent resources into parallel batches
+     *
+     * Performance notes:
+     * - Synchronous for graphs <10k nodes
+     * - For larger graphs, consider async version with periodic yielding
+     * - Uses memoized deep equality for prop comparison
+     *
+     * REQ-O01: Diff algorithm for incremental updates
+     * REQ-O04: Change preview for plan command
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state
+     * @returns ChangeSet with creates, updates, deletes, replacements, and deployment order
+     */
+    reconcile(previous: CloudDOMNode[], current: CloudDOMNode[]): ChangeSet;
+    /**
+     * Async reconcile for large CloudDOM graphs (>10k nodes)
+     *
+     * Yields periodically to prevent blocking the event loop.
+     * Useful for:
+     * - Large infrastructure graphs
+     * - UI responsiveness during diff computation
+     * - Long-running CI/CD pipelines
+     *
+     * Algorithm is identical to synchronous reconcile, but yields every N nodes.
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state
+     * @param yieldInterval - Number of nodes to process before yielding (default: 1000)
+     * @returns Promise resolving to ChangeSet
+     */
+    reconcileAsync(previous: CloudDOMNode[], current: CloudDOMNode[], yieldInterval?: number): Promise<ChangeSet>;
+    /**
+     * Yield control to event loop
+     *
+     * Uses setImmediate in Node.js, setTimeout in browser.
+     * Prevents blocking during large graph reconciliation.
+     */
+    private yield;
+    /**
+     * Build a flat map of node ID → CloudDOMNode for O(n) lookup
+     *
+     * Recursively walks the CloudDOM tree and collects all nodes.
+     *
+     * @param nodes - CloudDOM tree (root nodes)
+     * @returns Map of node ID → CloudDOMNode
+     */
+    private buildNodeMap;
+    /**
+     * Detect moves (nodes that changed parent in hierarchy)
+     *
+     * A move is detected when:
+     * - Node exists in both previous and current
+     * - Node's parent path changed (using array equality, not string comparison)
+     *
+     * This is useful for hierarchical updates where resources move
+     * between parent containers.
+     *
+     * @param previousMap - Previous node map
+     * @param currentMap - Current node map
+     * @returns Array of move operations with node ID
+     */
+    private detectMoves;
+    /**
+     * Detect the type of change between two nodes
+     *
+     * Returns:
+     * - 'replacement': Construct type changed (needs delete + create)
+     * - 'update': Props changed but construct is same (can update in place)
+     * - 'none': No changes detected
+     *
+     * Performance optimization:
+     * - Uses shallow prop hashes for O(1) comparison
+     * - Only falls back to deep equality if hashes differ
+     * - Caches hashes in node metadata (_propHash)
+     *
+     * NOTE: The `state` field is intentionally NOT compared during reconciliation.
+     * Only `props` and `outputs` are compared. The `state` field contains useState
+     * values which should not trigger infrastructure updates. This separation ensures
+     * that application state changes don't cause unnecessary resource deployments.
+     *
+     * @param previous - Previous node
+     * @param current - Current node
+     * @returns Change type
+     */
+    private detectChangeType;
+    /**
+     * Check if two constructs are equal
+     *
+     * Constructs are considered equal if they have the same name.
+     * Handles edge cases like minified builds where function names may be undefined.
+     *
+     * NOTE: After serialization, construct field may be undefined, so we rely on
+     * constructType string field for comparison.
+     *
+     * @param a - First construct
+     * @param b - Second construct
+     * @returns True if constructs are equal
+     */
+    private constructsEqual;
+    /**
+     * Get the name of a construct
+     *
+     * @param construct - Construct to get name from
+     * @returns Construct name
+     */
+    private getConstructName;
+    /**
+     * Check if node props have changed using deep equality
+     *
+     * Compares props objects deeply to detect any changes.
+     * Uses the deepEqual utility with memoization for performance.
+     *
+     * Excludes special props that don't affect rendering:
+     * - Metadata props (starting with _)
+     * - key prop (used for identity, not rendering)
+     * - children prop (handled separately in rendering)
+     *
+     * @param prevProps - Previous props (optional, defaults to empty object)
+     * @param currProps - Current props (optional, defaults to empty object)
+     * @returns True if props have changed
+     */
+    private propsChanged;
+    /**
+     * Check if outputs have changed using deep equality
+     *
+     * Treats empty objects ({}) as equivalent to undefined for idempotency.
+     *
+     * NOTE: This method only receives and compares the `outputs` field from CloudDOMNode.
+     * The `state` field is never passed to this method, ensuring that useState values
+     * do not trigger infrastructure updates. This separation is automatic - callers
+     * explicitly pass `node.outputs`, not `node.state`.
+     *
+     * @param previous - Previous outputs (from node.outputs field only)
+     * @param current - Current outputs (from node.outputs field only)
+     * @returns True if outputs changed
+     */
+    private outputsChanged;
+    /**
+     * Build dependency graph from CloudDOM nodes
+     *
+     * Scans node props for references to other node IDs and builds
+     * an adjacency list representing dependencies.
+     *
+     * A node depends on another if its props reference the other node's ID.
+     *
+     * REQ-O01: Dependency graph for deployment ordering
+     *
+     * @param nodes - CloudDOM nodes
+     * @returns DependencyGraph with adjacency lists
+     */
+    private buildDependencyGraph;
+    /**
+     * Validate dependency graph integrity
+     *
+     * Ensures all dependencies exist in the graph and no missing node IDs remain.
+     *
+     * @param graph - Dependency graph to validate
+     * @throws ReconciliationError if graph is invalid
+     */
+    private validateGraph;
+    /**
+     * Extract dependencies from a node's props
+     *
+     * Recursively scans props object for strings that match other node IDs.
+     *
+     * Optimizations:
+     * - Skips props that start with underscore (internal metadata)
+     * - Uses explicit ref convention when available (props.ref or props.dependsOn)
+     * - Caches known non-ID props to avoid false positives
+     *
+     * @param node - CloudDOM node
+     * @param nodeIds - Set of all node IDs for validation
+     * @returns Array of dependency IDs
+     */
+    private extractDependencies;
+    /**
+     * Check if a prop key is known to never contain node IDs
+     *
+     * This helps avoid false positives in dependency extraction.
+     *
+     * @param key - Prop key
+     * @returns True if this prop is known to not contain IDs
+     */
+    private isKnownNonIdProp;
+    /**
+     * Detect circular dependencies using DFS
+     *
+     * Collects all cycles before throwing to provide comprehensive diagnostics.
+     *
+     * REQ-O01: Circular dependency detection
+     *
+     * @param dependencies - Dependency adjacency list
+     * @throws ReconciliationError if circular dependencies are detected
+     */
+    private detectCircularDependencies;
+    /**
+     * Compute topological sort for deployment order using Kahn's algorithm
+     *
+     * Returns array of node IDs in deployment order (dependencies first).
+     * Nodes with same depth are sorted by ID for determinism.
+     *
+     * REQ-O01: Topological sort for deployment order
+     *
+     * @param graph - Dependency graph
+     * @returns Array of node IDs in deployment order
+     */
+    private topologicalSort;
+    /**
+     * Compute parallel deployment batches
+     *
+     * Groups nodes by depth in dependency graph.
+     * Nodes at same depth can deploy in parallel (no dependencies between them).
+     *
+     * REQ-O01: Parallel deployment batches
+     *
+     * @param deploymentOrder - Topologically sorted node IDs
+     * @param graph - Dependency graph
+     * @returns Array of batches (each batch can deploy in parallel)
+     */
+    private computeParallelBatches;
+}