@creact-labs/creact 0.1.0

package/dist/core/CloudDOMBuilder.d.ts

@@ -0,0 +1,429 @@
+/**
+
+ * 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 { FiberNode, CloudDOMNode, OutputChange } from './types';
+import { ICloudProvider } from '../providers/ICloudProvider';
+import { StateBindingManager } from './StateBindingManager';
+import { ProviderOutputTracker } from './ProviderOutputTracker';
+/**
+ * CloudDOMBuilder transforms a Fiber tree into a CloudDOM tree
+ *
+ * The CloudDOM tree represents actual cloud resources to be deployed:
+ * - Only includes components that called useInstance (have cloudDOMNode attached)
+ * - Filters out container components (no useInstance)
+ * - Builds parent-child relationships for deployment order
+ * - Generates resource IDs from hierarchical paths
+ *
+ * REQ-01: JSX → CloudDOM rendering
+ * REQ-04: Receives ICloudProvider via dependency injection (not used in build, but available for future extensions)
+ */
+export declare class CloudDOMBuilder {
+    private cloudProvider;
+    /**
+     * Optional lifecycle hooks for integration with other components
+     * Supports async hooks for validation, telemetry, and provider preparation
+     */
+    private beforeBuildHook?;
+    private afterBuildHook?;
+    /**
+     * State binding manager for reactive output synchronization
+     */
+    private stateBindingManager?;
+    /**
+     * Provider output tracker for instance-output binding
+     */
+    private providerOutputTracker?;
+    /**
+     * Track existing nodes to handle re-render scenarios
+     * Maps node ID to fiber path for duplicate detection during re-renders
+     */
+    private existingNodeMap;
+    /**
+     * Constructor receives ICloudProvider via dependency injection
+     *
+     * REQ-04: Dependency injection pattern - provider is injected, not inherited
+     *
+     * @param cloudProvider - Cloud provider implementation (injected)
+     */
+    constructor(cloudProvider: ICloudProvider);
+    /**
+     * Set lifecycle hooks for integration with other components
+     *
+     * Supports async hooks for:
+     * - beforeBuild: Validation, pre-processing, telemetry
+     * - afterBuild: Provider preparation, post-processing, logging
+     *
+     * Example:
+     * ```typescript
+     * builder.setHooks({
+     *   beforeBuild: async fiber => validator.validate(fiber),
+     *   afterBuild: async tree => cloudProvider.prepare(tree),
+     * });
+     * ```
+     *
+     * @param hooks - Optional lifecycle hooks (sync or async)
+     */
+    setHooks(hooks: {
+        beforeBuild?: (fiber: FiberNode) => void | Promise<void>;
+        afterBuild?: (rootNodes: CloudDOMNode[]) => void | Promise<void>;
+    }): void;
+    /**
+     * Set reactive components for output synchronization
+     *
+     * @param stateBindingManager - State binding manager instance
+     * @param providerOutputTracker - Provider output tracker instance
+     */
+    setReactiveComponents(stateBindingManager: StateBindingManager, providerOutputTracker: ProviderOutputTracker): void;
+    /**
+     * Build CloudDOM tree from Fiber tree
+     *
+     * Traverses the Fiber tree and collects nodes that have cloudDOMNode attached
+     * (i.e., components that called useInstance). Container components without
+     * useInstance are filtered out, but their children are preserved.
+     *
+     * Supports async lifecycle hooks for validation and provider preparation.
+     *
+     * REQ-01: Transform Fiber → CloudDOM
+     *
+     * @param fiber - Root Fiber node
+     * @returns Promise resolving to array of CloudDOM nodes (top-level resources)
+     */
+    build(fiber: FiberNode): Promise<CloudDOMNode[]>;
+    /**
+     * Build CloudDOM tree with error handling for CLI/CI environments
+     *
+     * Provides a safer entrypoint that handles errors gracefully without
+     * crashing the entire process. Useful for CI/CD pipelines.
+     *
+     * @param fiber - Root Fiber node
+     * @returns Promise resolving to array of CloudDOM nodes, or empty array on error
+     */
+    buildSafe(fiber: FiberNode): Promise<CloudDOMNode[]>;
+    /**
+     * Recursively collect CloudDOM nodes from Fiber tree
+     *
+     * Traverses the Fiber tree depth-first and collects all nodes that have
+     * cloudDOMNode or cloudDOMNodes attached (i.e., components that called useInstance).
+     *
+     * Normalizes paths and IDs during collection for consistency.
+     *
+     * @param fiber - Current Fiber node
+     * @param collected - Array to collect CloudDOM nodes into
+     */
+    private collectCloudDOMNodes;
+    /**
+     * Extract state from useState hooks in a Fiber node
+     *
+     * REQ-02: Extract outputs from useState calls
+     * REQ-06: Universal output access
+     * REQ-2.1: Store useState values without 'state.' prefix
+     *
+     * @param fiber - Fiber node to extract state from
+     * @returns Object mapping state keys to values (state1, state2, etc.)
+     */
+    private extractOutputsFromFiber;
+    /**
+     * Execute post-deployment effects for all Fiber nodes
+     * Called after successful deployment to run useEffect callbacks
+     *
+     * @param fiber - Root Fiber node
+     */
+    executePostDeploymentEffects(fiber: FiberNode): Promise<void>;
+    /**
+     * Sync Fiber hook state back to CloudDOM outputs after effects run
+     * This ensures useState changes in useEffect are reflected in the CloudDOM
+     *
+     * @param fiber - Root Fiber node
+     * @param cloudDOM - CloudDOM nodes to update
+     */
+    syncFiberStateToCloudDOM(fiber: FiberNode, cloudDOM: CloudDOMNode[]): void;
+    /**
+     * Sync a single Fiber node's state to its corresponding CloudDOM node
+     */
+    private syncFiberNodeToCloudDOM;
+    /**
+     * Update a CloudDOM node's state with the latest Fiber hook state
+     *
+     * REQ-1.2, 1.3: Separate useState values from provider outputs
+     * State is stored in separate `state` field, not in `outputs`
+     */
+    private updateCloudDOMNodeOutputs;
+    /**
+     * Sync state back to the original CloudDOM nodes that components reference
+     * This ensures that enhanced node proxies see the updated state
+     */
+    private syncOutputsToOriginalNodes;
+    /**
+     * Type guard to validate CloudDOM node structure
+     *
+     * @param node - Potential CloudDOM node
+     * @returns True if node is a valid CloudDOM node
+     */
+    private isValidCloudNode;
+    /**
+     * Validate CloudDOM nodes for common issues
+     *
+     * Checks for:
+     * - Duplicate IDs (would cause silent overwrites in hierarchy building)
+     * - Invalid paths (empty or non-array)
+     * - Circular references in paths
+     *
+     * Enhanced for re-render scenarios:
+     * - Allows re-validation of existing nodes from the same fiber path
+     * - Prevents false positives during reactive re-renders
+     *
+     * @param nodes - CloudDOM nodes to validate
+     * @throws Error if duplicate IDs or circular references are found
+     */
+    private validateCloudDOMNodes;
+    /**
+     * Create deep defensive copy of CloudDOM nodes to avoid mutation
+     *
+     * Recursively copies:
+     * - Node properties
+     * - Props object
+     * - Outputs object
+     * - Children array (deep copy)
+     *
+     * This prevents mutations from later phases (e.g., provider injection,
+     * dependency graph tagging) from affecting the original nodes.
+     *
+     * @param nodes - Original CloudDOM nodes
+     * @returns Deep copy of nodes
+     */
+    private createDeepDefensiveCopy;
+    /**
+     * Build parent-child hierarchy from flat list of CloudDOM nodes
+     *
+     * Uses the path property to determine parent-child relationships:
+     * - A node is a child of another if its path starts with the parent's path
+     * - Returns only root nodes (nodes with no parent)
+     *
+     * Example:
+     * - ['registry'] is root
+     * - ['registry', 'service'] is child of ['registry']
+     * - ['registry', 'service', 'task'] is child of ['registry', 'service']
+     *
+     * Optimization: Groups nodes by depth for O(n) parent lookup instead of O(n²)
+     *
+     * @param nodes - Flat array of CloudDOM nodes
+     * @returns Array of root CloudDOM nodes with children attached
+     */
+    private buildHierarchy;
+    /**
+     * Find the parent node for a given node (optimized version)
+     *
+     * A node is the parent if:
+     * 1. Its path is a prefix of the child's path
+     * 2. Its path length is exactly one less than the child's path length (immediate parent)
+     *
+     * Example:
+     * - Child path: ['registry', 'service', 'task']
+     * - Parent path: ['registry', 'service'] ✓ (immediate parent)
+     * - Not parent: ['registry'] ✗ (grandparent, not immediate)
+     *
+     * Optimization: Uses nodesByDepth map to only search nodes at parent depth (O(n) instead of O(n²))
+     *
+     * @param node - Node to find parent for
+     * @param nodesByDepth - Map of nodes grouped by path depth
+     * @returns Parent node or undefined if no parent
+     */
+    private findParentOptimized;
+    /**
+     * Get the cloud provider (for testing/debugging)
+     *
+     * @returns The injected cloud provider
+     */
+    getCloudProvider(): ICloudProvider;
+    /**
+     * Convert CloudDOM tree to flat map for debugging and backend storage
+     *
+     * Useful for:
+     * - Backend state providers that need flat ID → node mapping
+     * - Debugging and inspection
+     * - Quick lookups by ID
+     *
+     * Type-safe: Preserves node subtype information for provider-specific extensions
+     *
+     * @param rootNodes - Root CloudDOM nodes
+     * @returns Flat map of ID → CloudDOM node
+     */
+    toFlatMap<T extends CloudDOMNode = CloudDOMNode>(rootNodes: T[]): Record<string, T>;
+    /**
+     * Normalize path segments for consistent resource addressing
+     *
+     * Ensures consistent casing and formatting across environments:
+     * - Trims whitespace
+     * - Converts to lowercase
+     * - Replaces slashes and spaces with hyphens
+     *
+     * REQ-NF: Future safety for cross-OS consistency
+     *
+     * @param path - Path segments to normalize
+     * @returns Normalized path segments
+     */
+    private normalizePath;
+    /**
+     * Format path for human-readable error messages
+     *
+     * @param node - CloudDOM node
+     * @returns Formatted path string (e.g., "registry > service > task")
+     */
+    private formatPath;
+    /**
+     * Detect circular references in CloudDOM hierarchy
+     *
+     * Uses depth-first search to detect cycles in parent-child relationships.
+     * This is a graph-level safety check beyond simple path validation.
+     *
+     * @param nodes - Root CloudDOM nodes
+     * @throws Error if circular hierarchy is detected
+     */
+    private detectCircularRefs;
+    /**
+     * Build efficient node map for CloudDOM comparison
+     * Creates a flat map of node ID to node for fast lookup during comparison
+     * Handles nested node structures properly
+     *
+     * REQ-1.4, 9.1: Efficient map building for CloudDOM comparison
+     *
+     * @param nodes - CloudDOM nodes to map
+     * @returns Map of node ID to CloudDOM node
+     */
+    private buildNodeMap;
+    /**
+     * Detect output changes after deployment by comparing previous and current CloudDOM
+     * This is called after deployment to identify which provider outputs have changed
+     *
+     * Enhanced to:
+     * - Compare previous and current CloudDOM states properly
+     * - Identify specific output keys that changed
+     * - Track affected fibers for each change
+     *
+     * REQ-1.4, 1.5, 9.1, 9.2, 9.3: Enhanced output change detection
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state after deployment
+     * @returns Array of output changes detected
+     */
+    detectOutputChanges(previous: CloudDOMNode[], current: CloudDOMNode[]): OutputChange[];
+    /**
+     * Synchronize provider outputs to bound state and trigger re-renders
+     * This is the main method called after deployment to update reactive state
+     *
+     * @param fiber - Root fiber node
+     * @param cloudDOM - Current CloudDOM after deployment
+     * @param previousCloudDOM - Previous CloudDOM state (optional)
+     * @returns Promise resolving to affected fibers that need re-rendering
+     */
+    syncOutputsAndReRender(fiber: FiberNode, cloudDOM: CloudDOMNode[], previousCloudDOM?: CloudDOMNode[]): Promise<FiberNode[]>;
+    /**
+     * Sync CloudDOM outputs to the original nodes that components reference
+     * This is critical for reactivity to work - components need to see updated outputs
+     */
+    private syncCloudDOMOutputsToOriginalNodes;
+    /**
+     * Recursively sync outputs to original nodes in the fiber tree
+     */
+    private syncOutputsToOriginalNodesRecursive;
+    /**
+     * Update context provider values when outputs change
+     * This enables context reactivity by finding components that create context values from outputs
+     *
+     * Strategy:
+     * 1. Find all fibers that have both cloudDOMNodes (use outputs) AND render a Context.Provider child
+     * 2. These are the components that create context values from outputs
+     * 3. Mark them for re-render so they re-evaluate their context values
+     *
+     * @param fiber - Root fiber to search
+     * @returns Array of fibers that need re-rendering (components creating context values from outputs)
+     */
+    private updateContextProviderValues;
+    /**
+     * Recursively find components that create context values from outputs
+     * These are components that:
+     * 1. Have cloudDOMNodes (use useInstance - depend on outputs)
+     * 2. Have children that are Context.Provider components
+     */
+    private findContextValueCreators;
+    /**
+     * Apply output changes to bound state using StateBindingManager
+     * This updates useState values that are bound to provider outputs
+     *
+     * Enhanced to:
+     * - Apply detected changes to bound state via StateBindingManager
+     * - Handle binding updates without creating loops
+     * - Return affected fibers for re-rendering
+     *
+     * REQ-9.4, 9.5: Apply output changes to state and return affected fibers
+     *
+     * @param changes - Array of output changes to apply
+     * @returns Array of fibers affected by the changes
+     */
+    applyOutputChangesToState(changes: OutputChange[]): FiberNode[];
+    /**
+     * Execute reactive effects for fibers affected by output changes
+     * This triggers useEffect callbacks that depend on changed provider outputs
+     *
+     * @param affectedFibers - Fibers that were affected by output changes
+     * @param changes - Output changes that occurred
+     */
+    private executeReactiveEffects;
+    /**
+     * Integrate with post-deployment effects to trigger output synchronization
+     * This method should be called after deployment completes
+     *
+     * Phase ordering (REQ-1.1, 1.2, 1.5):
+     * 1. Sync outputs to original nodes BEFORE executing effects
+     * 2. Execute effects (they can now see updated outputs)
+     * 3. Sync outputs and trigger re-renders for reactive changes
+     * 4. Sync state changes back to CloudDOM
+     *
+     * @param fiber - Root fiber node
+     * @param cloudDOM - Current CloudDOM after deployment
+     * @param previousCloudDOM - Previous CloudDOM state (optional)
+     * @returns Promise resolving to affected fibers that need re-rendering
+     */
+    integrateWithPostDeploymentEffects(fiber: FiberNode, cloudDOM: CloudDOMNode[], previousCloudDOM?: CloudDOMNode[]): Promise<FiberNode[]>;
+    /**
+     * Clear the existing node map (for testing or fresh builds)
+     * This allows starting with a clean slate for node validation
+     */
+    clearExistingNodes(): void;
+    /**
+     * Get the existing node map (for debugging/inspection)
+     * Returns a copy to prevent external mutation
+     */
+    getExistingNodes(): Map<string, string>;
+    /**
+     * Create a JSON replacer function that handles Symbols safely
+     * Converts Symbols to their string representation for debugging
+     */
+    private createSymbolReplacer;
+}