@creact-labs/creact 0.1.8 → 0.2.1

package/dist/core/CloudDOMBuilder.d.ts

@@ -1,447 +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 { FiberNode, CloudDOMNode, OutputChange } from './types';
-import { ICloudProvider } from '../providers/ICloudProvider';
-import { StateBindingManager } from './StateBindingManager';
-import { ProviderOutputTracker } from './ProviderOutputTracker';
-import { ContextDependencyTracker } from './ContextDependencyTracker';
-/**
- * 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?;
-    /**
-     * Context dependency tracker for context reactivity
-     */
-    private contextDependencyTracker?;
-    /**
-     * 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
-     * @param contextDependencyTracker - Context dependency tracker instance (optional)
-     */
-    setReactiveComponents(stateBindingManager: StateBindingManager, providerOutputTracker: ProviderOutputTracker, contextDependencyTracker?: ContextDependencyTracker): 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.
-     *
-     * CRITICAL FIX: Preserves nodes from previousCloudDOM that weren't re-rendered.
-     * This prevents node loss during selective re-renders (e.g., multi-environment apps).
-     *
-     * REQ-01: Transform Fiber → CloudDOM
-     *
-     * @param fiber - Root Fiber node
-     * @param previousCloudDOM - Optional previous CloudDOM for incremental builds
-     * @returns Promise resolving to array of CloudDOM nodes (top-level resources)
-     */
-    build(fiber: FiberNode, previousCloudDOM?: CloudDOMNode[]): Promise<CloudDOMNode[]>;
-    /**
-     * Flatten CloudDOM tree into a flat array of all nodes
-     *
-     * @param nodes - Root CloudDOM nodes
-     * @returns Flattened array of all nodes
-     */
-    private flattenCloudDOM;
-    /**
-     * 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
-     * @param previousCloudDOM - Optional previous CloudDOM for incremental builds
-     * @returns Promise resolving to array of CloudDOM nodes, or empty array on error
-     */
-    buildSafe(fiber: FiberNode, previousCloudDOM?: CloudDOMNode[]): 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;
-}