@creact-labs/creact 0.1.0

package/dist/core/EventBus.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+
+ * 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
+
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudDOMEventBus = void 0;
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('clouddom');
+/**
+ * CloudDOM Event Bus - Centralized event system for deployment lifecycle
+ *
+ * Provides a clean way to trigger CloudDOM event callbacks without
+ * coupling to specific classes like CloudDOMBuilder or StateMachine.
+ *
+ * REQ-2.3: CloudDOM event callbacks for deployment lifecycle
+ * REQ-3.2: Error handling with component context
+ */
+class CloudDOMEventBus {
+    /**
+     * Trigger CloudDOM event callbacks for a resource
+     *
+     * Called during deployment lifecycle to notify parent components
+     * about their child resources' deployment events.
+     *
+     * @param node - CloudDOM node with event callbacks
+     * @param phase - Deployment phase ('deploy', 'error', 'destroy')
+     * @param error - Error object (only for 'error' phase)
+     */
+    static async triggerEventCallbacks(node, phase, error) {
+        if (!node.eventCallbacks) {
+            return; // No callbacks to trigger
+        }
+        // Create event context
+        const context = {
+            resourceId: node.id,
+            path: node.path,
+            construct: node.construct,
+            props: { ...node.props }, // Clone to prevent mutations
+            outputs: node.outputs ? { ...node.outputs } : undefined,
+            phase,
+            timestamp: Date.now(),
+        };
+        try {
+            // Trigger appropriate callback based on phase
+            switch (phase) {
+                case 'deploy':
+                    if (node.eventCallbacks.onDeploy) {
+                        await node.eventCallbacks.onDeploy(context);
+                    }
+                    break;
+                case 'error':
+                    if (node.eventCallbacks.onError && error) {
+                        await node.eventCallbacks.onError(context, error);
+                    }
+                    break;
+                case 'destroy':
+                    if (node.eventCallbacks.onDestroy) {
+                        await node.eventCallbacks.onDestroy(context);
+                    }
+                    break;
+            }
+        }
+        catch (callbackError) {
+            // Don't let callback errors break deployment
+            logger.error(`Event callback failed for ${node.id} (${phase}):`, callbackError);
+        }
+    }
+    /**
+     * Trigger event callbacks for all nodes in a CloudDOM tree
+     *
+     * Recursively walks the tree and triggers callbacks for each node.
+     *
+     * @param nodes - CloudDOM nodes to trigger events for
+     * @param phase - Deployment phase
+     * @param error - Error object (only for 'error' phase)
+     */
+    static async triggerEventCallbacksRecursive(nodes, phase, error) {
+        for (const node of nodes) {
+            // Trigger callback for this node
+            await CloudDOMEventBus.triggerEventCallbacks(node, phase, error);
+            // Recursively trigger for children
+            if (node.children && node.children.length > 0) {
+                await CloudDOMEventBus.triggerEventCallbacksRecursive(node.children, phase, error);
+            }
+        }
+    }
+    /**
+     * Trigger event callbacks for a specific list of nodes by ID
+     *
+     * Useful for triggering events for specific resources during deployment.
+     *
+     * @param allNodes - All CloudDOM nodes to search in
+     * @param nodeIds - IDs of nodes to trigger events for
+     * @param phase - Deployment phase
+     * @param error - Error object (only for 'error' phase)
+     */
+    static async triggerEventCallbacksForNodes(allNodes, nodeIds, phase, error) {
+        // Build a map for fast lookup
+        const nodeMap = new Map();
+        const buildMap = (nodes) => {
+            for (const node of nodes) {
+                nodeMap.set(node.id, node);
+                if (node.children && node.children.length > 0) {
+                    buildMap(node.children);
+                }
+            }
+        };
+        buildMap(allNodes);
+        // Trigger events for specified nodes
+        for (const nodeId of nodeIds) {
+            const node = nodeMap.get(nodeId);
+            if (node) {
+                await CloudDOMEventBus.triggerEventCallbacks(node, phase, error);
+            }
+        }
+    }
+    /**
+     * Check if any nodes in a tree have event callbacks
+     *
+     * Useful for optimization - skip event processing if no callbacks exist.
+     *
+     * @param nodes - CloudDOM nodes to check
+     * @returns True if any node has event callbacks
+     */
+    static hasEventCallbacks(nodes) {
+        for (const node of nodes) {
+            if (node.eventCallbacks && Object.keys(node.eventCallbacks).length > 0) {
+                return true;
+            }
+            if (node.children && node.children.length > 0) {
+                if (CloudDOMEventBus.hasEventCallbacks(node.children)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Get all nodes with event callbacks from a tree
+     *
+     * Useful for debugging and introspection.
+     *
+     * @param nodes - CloudDOM nodes to search
+     * @returns Array of nodes that have event callbacks
+     */
+    static getNodesWithEventCallbacks(nodes) {
+        const result = [];
+        for (const node of nodes) {
+            if (node.eventCallbacks && Object.keys(node.eventCallbacks).length > 0) {
+                result.push(node);
+            }
+            if (node.children && node.children.length > 0) {
+                result.push(...CloudDOMEventBus.getNodesWithEventCallbacks(node.children));
+            }
+        }
+        return result;
+    }
+}
+exports.CloudDOMEventBus = CloudDOMEventBus;

package/dist/core/ProviderOutputTracker.d.ts

@@ -0,0 +1,211 @@
+/**
+
+ * 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, CReactEvents, OutputChange } from './types';
+/**
+ * Access tracking session for dependency analysis
+ * REQ-6.2, 6.3, 6.4: Track output reads during component execution
+ */
+interface AccessTrackingSession {
+    fiber: FiberNode;
+    startTime: number;
+    trackedOutputs: Set<string>;
+    isActive: boolean;
+}
+/**
+ * ProviderOutputTracker - Tracks useInstance calls and their output dependencies
+ *
+ * Key Features:
+ * - Track which components use which provider instances
+ * - Detect when provider outputs change
+ * - Notify bound components of output changes
+ * - Event hook integration for tooling and debugging
+ * - REQ-6.2, 6.3, 6.4: Track output reads for automatic binding creation
+ */
+export declare class ProviderOutputTracker {
+    private instanceBindings;
+    private instanceOutputs;
+    private eventHooks?;
+    private activeSessions;
+    constructor(eventHooks?: CReactEvents);
+    /**
+     * Track a useInstance call - bind a fiber to a CloudDOM node
+     * This is called whenever useInstance is called in a component
+     */
+    trackInstance(node: CloudDOMNode, fiber: FiberNode): void;
+    /**
+     * Get all fibers bound to a specific instance
+     */
+    getBindingsForInstance(nodeId: string): Set<FiberNode>;
+    /**
+     * Update outputs for an instance and detect changes
+     * Returns array of output changes that occurred
+     */
+    updateInstanceOutputs(nodeId: string, newOutputs: Record<string, any>): OutputChange[];
+    /**
+     * Notify bound components of output changes
+     * This triggers re-renders for affected components
+     */
+    notifyOutputChanges(changes: OutputChange[]): void;
+    /**
+     * Process a batch of CloudDOM nodes and detect all output changes
+     * This is typically called after deployment completes
+     */
+    processCloudDOMOutputs(nodes: CloudDOMNode[]): OutputChange[];
+    /**
+     * Remove bindings for a specific fiber (cleanup)
+     */
+    removeBindingsForFiber(fiber: FiberNode): void;
+    /**
+     * Remove bindings for a specific instance (when resource is deleted)
+     */
+    removeBindingsForInstance(nodeId: string): void;
+    /**
+     * Validate bindings and remove invalid ones
+     * This should be called periodically to clean up stale bindings
+     */
+    validateBindings(validNodes: Set<string>): void;
+    /**
+     * Get current outputs for an instance
+     */
+    getInstanceOutputs(nodeId: string): Record<string, any> | undefined;
+    /**
+     * Check if an instance has any bound components
+     */
+    hasBindings(nodeId: string): boolean;
+    /**
+     * Get all tracked instances
+     */
+    getTrackedInstances(): string[];
+    /**
+     * Get statistics about current bindings
+     */
+    getBindingStats(): {
+        totalInstances: number;
+        totalBindings: number;
+        instancesWithOutputs: number;
+    };
+    /**
+     * Get all bindings for debugging/inspection
+     */
+    getAllBindings(): Map<string, {
+        fibers: FiberNode[];
+        outputs: Record<string, any> | undefined;
+    }>;
+    /**
+     * Clear all bindings (for testing/cleanup)
+     */
+    clearAllBindings(): void;
+    /**
+     * Create a snapshot of current state for comparison
+     * Useful for detecting changes between deployments
+     */
+    createSnapshot(): {
+        bindings: Map<string, string[]>;
+        outputs: Map<string, Record<string, any>>;
+    };
+    /**
+     * Compare with a previous snapshot to detect changes
+     */
+    compareWithSnapshot(snapshot: {
+        bindings: Map<string, string[]>;
+        outputs: Map<string, Record<string, any>>;
+    }): {
+        bindingChanges: {
+            added: string[];
+            removed: string[];
+            modified: string[];
+        };
+        outputChanges: OutputChange[];
+    };
+    /**
+     * Compare two output objects and return changes
+     */
+    private compareOutputs;
+    /**
+     * Extract output references for automatic state binding
+     * Creates proxy objects that can be used to automatically bind state to outputs
+     */
+    extractOutputReferences(node: CloudDOMNode): Record<string, any>;
+    /**
+     * Update outputs for a specific node and return changes
+     * This is an alias for updateInstanceOutputs for compatibility
+     */
+    updateNodeOutputs(nodeId: string, newOutputs: Record<string, any>): OutputChange[];
+    /**
+     * Process output changes and return affected fibers
+     * This is an alias for processCloudDOMOutputs for single node updates
+     */
+    processOutputChanges(changes: OutputChange[]): Set<FiberNode>;
+    /**
+     * Get current outputs for a node
+     * This is an alias for getInstanceOutputs for compatibility
+     */
+    getNodeOutputs(nodeId: string): Record<string, any>;
+    /**
+     * Start an access tracking session for a fiber
+     * REQ-6.2, 6.3: Track which outputs are accessed during execution
+     *
+     * @param fiber - Fiber node to track
+     */
+    startAccessTracking(fiber: FiberNode): void;
+    /**
+     * End an access tracking session and return tracked outputs
+     * REQ-6.3, 6.4: Collect tracked outputs for binding creation
+     *
+     * @param fiber - Fiber node to end tracking for
+     * @returns Set of binding keys that were accessed
+     */
+    endAccessTracking(fiber: FiberNode): Set<string>;
+    /**
+     * Track an output read during an active session
+     * REQ-6.2, 6.4: Record when outputs are accessed for binding creation
+     *
+     * @param nodeId - CloudDOM node ID
+     * @param outputKey - Output key that was accessed
+     * @param fiber - Fiber node that accessed the output
+     */
+    trackOutputRead(nodeId: string, outputKey: string, fiber: FiberNode): void;
+    /**
+     * Check if a fiber has an active tracking session
+     *
+     * @param fiber - Fiber node to check
+     * @returns True if tracking is active for this fiber
+     */
+    isTrackingActive(fiber: FiberNode): boolean;
+    /**
+     * Get all active tracking sessions (for debugging)
+     */
+    getActiveSessions(): AccessTrackingSession[];
+    /**
+     * Clear all active tracking sessions (for cleanup/testing)
+     */
+    clearActiveSessions(): void;
+}
+export {};