@creact-labs/creact 0.1.0

package/dist/core/ErrorRecoveryManager.d.ts

@@ -0,0 +1,145 @@
+/**
+
+ * 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, ReRenderReason, CReactEvents } from './types';
+import { CircularDependencyError } from './errors';
+/**
+ * Recovery strategy for different types of errors
+ */
+export type RecoveryStrategy = 'rollback' | 'isolate' | 'retry' | 'skip' | 'abort';
+/**
+ * Recovery action result
+ */
+export interface RecoveryResult {
+    success: boolean;
+    strategy: RecoveryStrategy;
+    message: string;
+    recoveredFibers?: FiberNode[];
+    failedFibers?: FiberNode[];
+}
+/**
+ * ErrorRecoveryManager - Handles error recovery and rollback semantics
+ *
+ * Provides:
+ * - Rollback semantics for failed re-renders
+ * - Error isolation for component failures
+ * - Graceful degradation for partial failures
+ * - Recovery strategies based on error type
+ */
+export declare class ErrorRecoveryManager {
+    private componentSnapshots;
+    private contextSnapshots;
+    private eventHooks?;
+    private maxRetries;
+    private retryDelay;
+    constructor(eventHooks?: CReactEvents);
+    /**
+     * Create a snapshot of component state before risky operations
+     */
+    createComponentSnapshot(fiber: FiberNode): void;
+    /**
+     * Create snapshots for multiple components
+     */
+    createComponentSnapshots(fibers: FiberNode[]): void;
+    /**
+     * Create a snapshot of context value before changes
+     */
+    createContextSnapshot(contextId: symbol, value: any): void;
+    /**
+     * Rollback a component to its previous snapshot
+     */
+    rollbackComponent(fiber: FiberNode): boolean;
+    /**
+     * Rollback multiple components to their snapshots
+     */
+    rollbackComponents(fibers: FiberNode[]): RecoveryResult;
+    /**
+     * Rollback context value to its previous snapshot
+     */
+    rollbackContextValue(contextId: symbol): boolean;
+    /**
+     * Handle re-render errors with appropriate recovery strategy
+     */
+    handleReRenderError(error: Error, affectedFibers: FiberNode[], reason: ReRenderReason): Promise<RecoveryResult>;
+    /**
+     * Handle state update errors with isolation
+     */
+    handleStateUpdateError(error: Error, fiber: FiberNode, hookIndex: number): RecoveryResult;
+    /**
+     * Handle context propagation errors
+     */
+    handleContextPropagationError(error: Error, contextId: symbol, affectedFibers: FiberNode[]): Promise<RecoveryResult>;
+    /**
+     * Handle circular dependency errors
+     */
+    handleCircularDependencyError(error: CircularDependencyError, affectedFibers: FiberNode[]): RecoveryResult;
+    /**
+     * Determine the appropriate recovery strategy based on error type and context
+     */
+    private determineRecoveryStrategy;
+    /**
+     * Isolate failed components and continue with successful ones
+     */
+    private isolateFailedComponents;
+    /**
+     * Retry operation with exponential backoff
+     */
+    private retryOperation;
+    /**
+     * Skip failed components and continue with others
+     */
+    private skipFailedComponents;
+    /**
+     * Find the fiber that's causing a circular dependency
+     */
+    private findCycleCausingFiber;
+    /**
+     * Deep clone an object for snapshots
+     */
+    private deepClone;
+    /**
+     * Clean up old snapshots to prevent memory leaks
+     */
+    cleanupOldSnapshots(maxAge?: number): void;
+    /**
+     * Get recovery statistics
+     */
+    getRecoveryStats(): {
+        activeSnapshots: number;
+        contextSnapshots: number;
+    };
+    /**
+     * Clear all snapshots (for testing/cleanup)
+     */
+    clearAllSnapshots(): void;
+    /**
+     * Set retry configuration
+     */
+    setRetryConfig(maxRetries: number, retryDelay: number): void;
+}

package/dist/core/ErrorRecoveryManager.js

@@ -0,0 +1,443 @@
+"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.ErrorRecoveryManager = void 0;
+const errors_1 = require("./errors");
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('runtime');
+/**
+ * ErrorRecoveryManager - Handles error recovery and rollback semantics
+ *
+ * Provides:
+ * - Rollback semantics for failed re-renders
+ * - Error isolation for component failures
+ * - Graceful degradation for partial failures
+ * - Recovery strategies based on error type
+ */
+class ErrorRecoveryManager {
+    constructor(eventHooks) {
+        this.componentSnapshots = new WeakMap();
+        this.contextSnapshots = new Map();
+        this.maxRetries = 3;
+        this.retryDelay = 100; // ms
+        this.eventHooks = eventHooks;
+    }
+    /**
+     * Create a snapshot of component state before risky operations
+     */
+    createComponentSnapshot(fiber) {
+        const snapshot = {
+            fiber,
+            hooks: fiber.hooks ? [...fiber.hooks] : [],
+            reactiveState: fiber.reactiveState ? { ...fiber.reactiveState } : undefined,
+            timestamp: Date.now(),
+        };
+        this.componentSnapshots.set(fiber, snapshot);
+    }
+    /**
+     * Create snapshots for multiple components
+     */
+    createComponentSnapshots(fibers) {
+        fibers.forEach((fiber) => this.createComponentSnapshot(fiber));
+    }
+    /**
+     * Create a snapshot of context value before changes
+     */
+    createContextSnapshot(contextId, value) {
+        this.contextSnapshots.set(contextId, {
+            value: this.deepClone(value),
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Rollback a component to its previous snapshot
+     */
+    rollbackComponent(fiber) {
+        const snapshot = this.componentSnapshots.get(fiber);
+        if (!snapshot) {
+            return false;
+        }
+        try {
+            // Restore hooks
+            if (fiber.hooks && snapshot.hooks) {
+                fiber.hooks.splice(0, fiber.hooks.length, ...snapshot.hooks);
+            }
+            // Restore reactive state
+            if (fiber.reactiveState && snapshot.reactiveState) {
+                Object.assign(fiber.reactiveState, snapshot.reactiveState);
+            }
+            return true;
+        }
+        catch (error) {
+            logger.warn(`Failed to rollback component ${fiber.path.join('.')}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Rollback multiple components to their snapshots
+     */
+    rollbackComponents(fibers) {
+        const recoveredFibers = [];
+        const failedFibers = [];
+        for (const fiber of fibers) {
+            if (this.rollbackComponent(fiber)) {
+                recoveredFibers.push(fiber);
+            }
+            else {
+                failedFibers.push(fiber);
+            }
+        }
+        return {
+            success: failedFibers.length === 0,
+            strategy: 'rollback',
+            message: `Rolled back ${recoveredFibers.length}/${fibers.length} components`,
+            recoveredFibers,
+            failedFibers,
+        };
+    }
+    /**
+     * Rollback context value to its previous snapshot
+     */
+    rollbackContextValue(contextId) {
+        const snapshot = this.contextSnapshots.get(contextId);
+        if (!snapshot) {
+            return false;
+        }
+        try {
+            // The actual context value rollback would be handled by ContextDependencyTracker
+            // This method just validates that we have a snapshot to rollback to
+            return true;
+        }
+        catch (error) {
+            logger.warn(`Failed to rollback context ${String(contextId)}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Handle re-render errors with appropriate recovery strategy
+     */
+    async handleReRenderError(error, affectedFibers, reason) {
+        // Determine recovery strategy based on error type and reason
+        const strategy = this.determineRecoveryStrategy(error, reason);
+        switch (strategy) {
+            case 'rollback':
+                return this.rollbackComponents(affectedFibers);
+            case 'isolate':
+                return this.isolateFailedComponents(error, affectedFibers);
+            case 'retry':
+                return await this.retryOperation(error, affectedFibers, reason);
+            case 'skip':
+                return this.skipFailedComponents(affectedFibers);
+            case 'abort':
+            default:
+                return {
+                    success: false,
+                    strategy: 'abort',
+                    message: `Aborting due to unrecoverable error: ${error.message}`,
+                    failedFibers: affectedFibers,
+                };
+        }
+    }
+    /**
+     * Handle state update errors with isolation
+     */
+    handleStateUpdateError(error, fiber, hookIndex) {
+        try {
+            // Try to rollback the specific hook
+            const snapshot = this.componentSnapshots.get(fiber);
+            if (snapshot && snapshot.hooks[hookIndex] !== undefined) {
+                if (fiber.hooks) {
+                    fiber.hooks[hookIndex] = snapshot.hooks[hookIndex];
+                }
+                return {
+                    success: true,
+                    strategy: 'rollback',
+                    message: `Rolled back state hook ${hookIndex} for component ${fiber.path.join('.')}`,
+                    recoveredFibers: [fiber],
+                };
+            }
+            // If no snapshot, isolate the component
+            return this.isolateFailedComponents(error, [fiber]);
+        }
+        catch (recoveryError) {
+            return {
+                success: false,
+                strategy: 'abort',
+                message: `Failed to recover from state update error: ${recoveryError}`,
+                failedFibers: [fiber],
+            };
+        }
+    }
+    /**
+     * Handle context propagation errors
+     */
+    async handleContextPropagationError(error, contextId, affectedFibers) {
+        try {
+            // Try to rollback context value
+            const contextRollback = this.rollbackContextValue(contextId);
+            if (contextRollback) {
+                // Rollback affected components
+                const componentRollback = this.rollbackComponents(affectedFibers);
+                return {
+                    success: componentRollback.success,
+                    strategy: 'rollback',
+                    message: `Rolled back context and ${componentRollback.recoveredFibers?.length || 0} components`,
+                    recoveredFibers: componentRollback.recoveredFibers,
+                    failedFibers: componentRollback.failedFibers,
+                };
+            }
+            // If context rollback fails, isolate affected components
+            return this.isolateFailedComponents(error, affectedFibers);
+        }
+        catch (recoveryError) {
+            return {
+                success: false,
+                strategy: 'abort',
+                message: `Failed to recover from context propagation error: ${recoveryError}`,
+                failedFibers: affectedFibers,
+            };
+        }
+    }
+    /**
+     * Handle circular dependency errors
+     */
+    handleCircularDependencyError(error, affectedFibers) {
+        try {
+            // For circular dependencies, we need to break the cycle
+            // Find the fiber that's causing the cycle and isolate it
+            const cycleFiber = this.findCycleCausingFiber(error.cyclePath, affectedFibers);
+            if (cycleFiber) {
+                // Isolate the cycle-causing fiber
+                const isolationResult = this.isolateFailedComponents(error, [cycleFiber]);
+                // Continue with remaining fibers
+                const remainingFibers = affectedFibers.filter((f) => f !== cycleFiber);
+                return {
+                    success: true,
+                    strategy: 'isolate',
+                    message: `Isolated cycle-causing component ${cycleFiber.path.join('.')}`,
+                    recoveredFibers: remainingFibers,
+                    failedFibers: [cycleFiber],
+                };
+            }
+            // If we can't identify the cycle cause, rollback all
+            return this.rollbackComponents(affectedFibers);
+        }
+        catch (recoveryError) {
+            return {
+                success: false,
+                strategy: 'abort',
+                message: `Failed to recover from circular dependency: ${recoveryError}`,
+                failedFibers: affectedFibers,
+            };
+        }
+    }
+    /**
+     * Determine the appropriate recovery strategy based on error type and context
+     */
+    determineRecoveryStrategy(error, reason) {
+        // Circular dependency errors should be isolated
+        if (error instanceof errors_1.CircularDependencyError) {
+            return 'isolate';
+        }
+        // State update errors can usually be rolled back
+        if (error instanceof errors_1.StateUpdateError) {
+            return 'rollback';
+        }
+        // Context propagation errors should be rolled back
+        if (error instanceof errors_1.ContextPropagationError) {
+            return 'rollback';
+        }
+        // For manual re-renders, we can retry
+        if (reason === 'manual') {
+            return 'retry';
+        }
+        // For output updates, we can skip and continue
+        if (reason === 'output-update') {
+            return 'skip';
+        }
+        // For hot reload, we can retry
+        if (reason === 'hot-reload') {
+            return 'retry';
+        }
+        // Default to rollback for other cases
+        return 'rollback';
+    }
+    /**
+     * Isolate failed components and continue with successful ones
+     */
+    isolateFailedComponents(error, failedFibers) {
+        // Mark failed components as isolated
+        failedFibers.forEach((fiber) => {
+            if (fiber.reactiveState) {
+                fiber.reactiveState.isDirty = false;
+                fiber.reactiveState.updatePending = false;
+                // Add isolation marker
+                fiber.reactiveState.isolated = true;
+                fiber.reactiveState.isolationReason = error.message;
+                fiber.reactiveState.isolationTime = Date.now();
+            }
+        });
+        this.eventHooks?.onError(error, failedFibers[0]);
+        return {
+            success: true,
+            strategy: 'isolate',
+            message: `Isolated ${failedFibers.length} failed components`,
+            failedFibers,
+        };
+    }
+    /**
+     * Retry operation with exponential backoff
+     */
+    async retryOperation(error, fibers, reason, attempt = 1) {
+        if (attempt > this.maxRetries) {
+            return {
+                success: false,
+                strategy: 'retry',
+                message: `Max retries (${this.maxRetries}) exceeded`,
+                failedFibers: fibers,
+            };
+        }
+        // Wait with exponential backoff
+        const delay = this.retryDelay * Math.pow(2, attempt - 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        try {
+            // The actual retry would be handled by the calling code
+            // This method just provides the retry logic framework
+            return {
+                success: true,
+                strategy: 'retry',
+                message: `Retry attempt ${attempt} scheduled`,
+                recoveredFibers: fibers,
+            };
+        }
+        catch (retryError) {
+            // Recursive retry
+            return this.retryOperation(error, fibers, reason, attempt + 1);
+        }
+    }
+    /**
+     * Skip failed components and continue with others
+     */
+    skipFailedComponents(fibers) {
+        // Mark components as skipped
+        fibers.forEach((fiber) => {
+            if (fiber.reactiveState) {
+                fiber.reactiveState.isDirty = false;
+                fiber.reactiveState.updatePending = false;
+                // Add skip marker
+                fiber.reactiveState.skipped = true;
+                fiber.reactiveState.skipTime = Date.now();
+            }
+        });
+        return {
+            success: true,
+            strategy: 'skip',
+            message: `Skipped ${fibers.length} components`,
+            recoveredFibers: [],
+        };
+    }
+    /**
+     * Find the fiber that's causing a circular dependency
+     */
+    findCycleCausingFiber(cyclePath, fibers) {
+        // Look for a fiber whose path matches part of the cycle path
+        for (const fiber of fibers) {
+            const fiberPathStr = fiber.path.join('.');
+            if (cyclePath.includes(fiberPathStr)) {
+                return fiber;
+            }
+        }
+        return null;
+    }
+    /**
+     * Deep clone an object for snapshots
+     */
+    deepClone(obj) {
+        if (obj === null || typeof obj !== 'object') {
+            return obj;
+        }
+        if (obj instanceof Date) {
+            return new Date(obj.getTime());
+        }
+        if (obj instanceof Array) {
+            return obj.map((item) => this.deepClone(item));
+        }
+        if (typeof obj === 'object') {
+            const cloned = {};
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key)) {
+                    cloned[key] = this.deepClone(obj[key]);
+                }
+            }
+            return cloned;
+        }
+        return obj;
+    }
+    /**
+     * Clean up old snapshots to prevent memory leaks
+     */
+    cleanupOldSnapshots(maxAge = 300000) {
+        // 5 minutes default
+        const now = Date.now();
+        // Clean up context snapshots
+        Array.from(this.contextSnapshots.entries()).forEach(([contextId, snapshot]) => {
+            if (now - snapshot.timestamp > maxAge) {
+                this.contextSnapshots.delete(contextId);
+            }
+        });
+        // Note: Component snapshots use WeakMap, so they'll be garbage collected
+        // automatically when the fiber is no longer referenced
+    }
+    /**
+     * Get recovery statistics
+     */
+    getRecoveryStats() {
+        return {
+            activeSnapshots: 0, // WeakMap doesn't have size
+            contextSnapshots: this.contextSnapshots.size,
+        };
+    }
+    /**
+     * Clear all snapshots (for testing/cleanup)
+     */
+    clearAllSnapshots() {
+        this.contextSnapshots.clear();
+        // WeakMap will be cleared automatically when fibers are GC'd
+    }
+    /**
+     * Set retry configuration
+     */
+    setRetryConfig(maxRetries, retryDelay) {
+        this.maxRetries = maxRetries;
+        this.retryDelay = retryDelay;
+    }
+}
+exports.ErrorRecoveryManager = ErrorRecoveryManager;

package/dist/core/EventBus.d.ts

@@ -0,0 +1,91 @@
+/**
+
+ * 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';
+/**
+ * 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
+ */
+export declare 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 triggerEventCallbacks(node: CloudDOMNode, phase: 'deploy' | 'error' | 'destroy', error?: Error): Promise<void>;
+    /**
+     * 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 triggerEventCallbacksRecursive(nodes: CloudDOMNode[], phase: 'deploy' | 'error' | 'destroy', error?: Error): Promise<void>;
+    /**
+     * 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 triggerEventCallbacksForNodes(allNodes: CloudDOMNode[], nodeIds: string[], phase: 'deploy' | 'error' | 'destroy', error?: Error): Promise<void>;
+    /**
+     * 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: CloudDOMNode[]): boolean;
+    /**
+     * 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: CloudDOMNode[]): CloudDOMNode[];
+}