@creact-labs/creact 0.1.8 → 0.2.1

package/dist/core/Reconciler.d.ts

@@ -1,415 +0,0 @@
-/**
-
- * 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;
-}