@creact-labs/creact 0.1.0

package/dist/core/Runtime.d.ts

@@ -0,0 +1,246 @@
+/**
+
+ * 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 { ICloudProvider } from '../providers/ICloudProvider';
+import { IBackendProvider } from '../providers/IBackendProvider';
+import { CloudDOMNode, JSXElement, ChangeSet } from './types';
+/**
+ * Runtime configuration
+ * REQ-1.6: Configuration with providers, deployment options, log config, hooks
+ */
+export interface RuntimeConfig {
+    /** Cloud provider for resource materialization */
+    cloudProvider: ICloudProvider;
+    /** Backend provider for state persistence */
+    backendProvider: IBackendProvider;
+    /** Deployment options */
+    deployment?: {
+        /** Enable parallel deployment (default: true) */
+        parallel?: boolean;
+        /** Max concurrent deployments (default: 10) */
+        maxConcurrency?: number;
+        /** Provider-specific concurrency limits */
+        providerConcurrency?: Record<string, number>;
+    };
+    /** Logging configuration */
+    log?: {
+        /** Enabled scopes (e.g., ['renderer', 'reconciler']) */
+        scopes?: string[];
+        /** Log level (default: 'info') */
+        level?: 'debug' | 'info' | 'warn' | 'error';
+    };
+    /** Lifecycle hooks */
+    hooks?: {
+        onStart?: () => void | Promise<void>;
+        onComplete?: (result: DeploymentResult) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    };
+    /** Async timeout in milliseconds (default: 5 minutes) */
+    asyncTimeout?: number;
+    /** Migration map for refactoring */
+    migrationMap?: Record<string, string>;
+}
+/**
+ * Deployment result
+ * REQ-1.4: Deploy method returns DeploymentResult
+ */
+export interface DeploymentResult {
+    /** CloudDOM tree after deployment */
+    cloudDOM: CloudDOMNode[];
+    /** Change set that was applied */
+    changeSet: ChangeSet;
+    /** Deployment duration in milliseconds */
+    duration: number;
+    /** Resource outputs */
+    outputs: Record<string, any>;
+    /** Deployment statistics */
+    stats: {
+        totalResources: number;
+        created: number;
+        updated: number;
+        deleted: number;
+        parallelBatches: number;
+        parallelEfficiency: number;
+    };
+}
+/**
+ * Runtime class for CReact execution management
+ *
+ * REQ-1.1: Dedicated Runtime class for managing execution lifecycle
+ * REQ-1.2: Initialize renderer, reconciler, state machine, and providers
+ * REQ-1.3: Execute full deployment pipeline
+ * REQ-1.4: Compute deployment diff without executing
+ * REQ-1.5: Tear down resources in reverse dependency order
+ * REQ-1.6: Accept provider instances, backend configuration, and deployment options
+ * REQ-1.7: Multiple Runtime instances are isolated from each other
+ * REQ-1.8: Provide lifecycle hooks (onStart, onComplete, onError)
+ * REQ-1.9: Clean up all resources and connections
+ *
+ * @example
+ * ```typescript
+ * const runtime = new Runtime({
+ *   cloudProvider: new MyCloudProvider(),
+ *   backendProvider: new MyBackendProvider(),
+ *   deployment: {
+ *     parallel: true,
+ *     maxConcurrency: 10
+ *   },
+ *   log: {
+ *     scopes: ['runtime', 'reconciler'],
+ *     level: 'info'
+ *   },
+ *   hooks: {
+ *     onStart: () => console.log('Deployment starting...'),
+ *     onComplete: (result) => console.log('Deployment complete!'),
+ *     onError: (error) => console.error('Deployment failed:', error)
+ *   }
+ * });
+ *
+ * // Deploy application
+ * const result = await runtime.deploy(<MyApp />);
+ *
+ * // Clean up
+ * await runtime.dispose();
+ * ```
+ */
+export declare class Runtime {
+    private config;
+    private renderer;
+    private validator;
+    private cloudDOMBuilder;
+    private reconciler;
+    private stateMachine;
+    private renderScheduler;
+    private stateBindingManager;
+    private providerOutputTracker;
+    private contextDependencyTracker;
+    private errorRecoveryManager;
+    private structuralChangeDetector;
+    private lastFiberTree;
+    private isDisposed;
+    /**
+     * Constructor receives all dependencies via config (dependency injection)
+     * REQ-1.2: Initialize renderer, reconciler, state machine, and providers
+     * REQ-1.6: Accept configuration with providers and options
+     * REQ-1.7: Ensure multiple Runtime instances are isolated
+     *
+     * @param config - Runtime configuration with providers and options
+     */
+    constructor(config: RuntimeConfig);
+    /**
+     * Deploy the application
+     * REQ-1.3: Execute full deployment pipeline and return DeploymentResult
+     * REQ-1.8: Lifecycle hooks support (onStart, onComplete, onError)
+     *
+     * Pipeline: render → validate → build → reconcile → deploy
+     *
+     * @param app - JSX element to deploy
+     * @param stackName - Stack name for state management (default: 'default')
+     * @param user - User initiating deployment (default: 'system')
+     * @returns Promise resolving to DeploymentResult
+     */
+    deploy(app: JSXElement, stackName?: string, user?: string): Promise<DeploymentResult>;
+    /**
+     * Compute deployment plan without executing
+     * REQ-1.4: Plan method computes ChangeSet without executing
+     *
+     * @param app - JSX element to plan
+     * @param stackName - Stack name for state comparison (default: 'default')
+     * @returns Promise resolving to ChangeSet
+     */
+    plan(app: JSXElement, stackName?: string): Promise<ChangeSet>;
+    /**
+     * Destroy all resources
+     * REQ-1.5: Tear down resources in reverse dependency order
+     *
+     * @param stackName - Stack name to destroy (default: 'default')
+     */
+    destroy(stackName?: string): Promise<void>;
+    /**
+     * Get current CloudDOM state
+     * REQ-1.6: Get current CloudDOM state
+     *
+     * @param stackName - Stack name (default: 'default')
+     * @returns Promise resolving to CloudDOM tree
+     */
+    getState(stackName?: string): Promise<CloudDOMNode[]>;
+    /**
+     * Dispose runtime and clean up resources
+     * REQ-1.9: Clean up all resources and connections
+     */
+    dispose(): Promise<void>;
+    /**
+     * Ensure runtime is not disposed
+     * @private
+     */
+    private ensureNotDisposed;
+    /**
+     * Handle output change events from provider (event-driven reactivity)
+     * Called when provider emits 'outputsChanged' event
+     *
+     * This enables real-time reactivity without polling:
+     * 1. Update ProviderOutputTracker with new outputs
+     * 2. Execute useEffect callbacks bound to these outputs (TODO)
+     * 3. Update bound state and enqueue affected fibers for re-render
+     *
+     * @param change - Output change event from provider
+     * @private
+     */
+    private handleProviderOutputChange;
+    /**
+     * Prepare hydration data from previous CloudDOM
+     * @private
+     */
+    private prepareHydration;
+    /**
+     * Clear hydration data
+     * @private
+     */
+    private clearHydration;
+    /**
+     * Build outputs map from CloudDOM
+     * @private
+     */
+    private buildOutputsMap;
+    /**
+     * Find node by ID in CloudDOM tree
+     * @private
+     */
+    private findNodeById;
+    /**
+     * Extract outputs from CloudDOM
+     * @private
+     */
+    private extractOutputs;
+    /**
+     * Calculate parallel efficiency from change set
+     * @private
+     */
+    private calculateParallelEfficiency;
+}