@creact-labs/creact 0.1.0

package/dist/context/createContext.js

@@ -0,0 +1,113 @@
+"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.createContext = createContext;
+/**
+ * Create a typed context object (like React.createContext)
+ *
+ * Returns a context object with Provider and Consumer components.
+ * Use with useContext hook to access values from the nearest Provider.
+ *
+ * REQ-02: Stack Context (declarative outputs)
+ *
+ * @param defaultValue - Optional default value when no Provider exists
+ * @returns Context object with Provider and Consumer
+ *
+ * @example
+ * ```tsx
+ * // Create a typed context
+ * interface RegistryOutputs {
+ *   repositoryUrl?: string;
+ *   repositoryArn?: string;
+ * }
+ *
+ * const RegistryContext = createContext<RegistryOutputs>({});
+ *
+ * // Provider component
+ * function RegistryStack({ children }) {
+ *   const repo = useInstance(EcrRepository, { key: 'repo', name: 'my-app' });
+ *   const [repositoryUrl, setRepositoryUrl] = useState();
+ *   const [repositoryArn, setRepositoryArn] = useState();
+ *
+ *   const outputs = { repositoryUrl, repositoryArn };
+ *   return <RegistryContext.Provider value={outputs}>{children}</RegistryContext.Provider>;
+ * }
+ *
+ * // Consumer component
+ * function Service() {
+ *   const { repositoryUrl } = useContext(RegistryContext);
+ *   const service = useInstance(AppRunnerService, {
+ *     image: `${repositoryUrl}:latest`
+ *   });
+ *   return <></>;
+ * }
+ * ```
+ */
+function createContext(defaultValue) {
+    // Create unique symbol to identify this context
+    const contextId = Symbol('Context');
+    /**
+     * Provider component - Supplies context value to descendants
+     *
+     * @param props.value - Value to provide to descendants
+     * @param props.children - Child components
+     */
+    const Provider = (props) => {
+        // Provider is a pass-through component that just returns its children
+        // The Renderer will recognize it by the metadata on the function and store the context value in the Fiber
+        // The props will be preserved in the Fiber node, including _contextId and _contextValue
+        return props.children;
+    };
+    // Mark Provider with context metadata for Renderer to recognize
+    Provider._isContextProvider = true;
+    Provider._contextId = contextId;
+    /**
+     * Consumer component - Consumes context value (alternative to useContext)
+     *
+     * @param props.children - Render function that receives context value
+     */
+    const Consumer = (props) => {
+        // Consumer is a placeholder - useContext hook will handle the actual lookup
+        // The render function will be called by the Renderer with the context value
+        return props.children;
+    };
+    // Mark Consumer with context metadata
+    Consumer._isContextConsumer = true;
+    Consumer._contextId = contextId;
+    // Return context object
+    const context = {
+        _contextId: contextId,
+        defaultValue,
+        Provider,
+        Consumer,
+    };
+    return context;
+}

package/dist/context/index.d.ts

@@ -0,0 +1,30 @@
+/**
+
+ * 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
+
+ */
+export { createContext, Context } from './createContext';

package/dist/context/index.js

@@ -0,0 +1,35 @@
+"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.createContext = void 0;
+// REQ-02: Context API exports
+var createContext_1 = require("./createContext");
+Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return createContext_1.createContext; } });

package/dist/core/CReact.d.ts

@@ -0,0 +1,409 @@
+/**
+
+ * 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 { StateMachine } from './StateMachine';
+import { ICloudProvider } from '../providers/ICloudProvider';
+import { IBackendProvider } from '../providers/IBackendProvider';
+import { CloudDOMNode, JSXElement, ChangeSet, FiberNode, ReRenderReason, CReactEvents } from './types';
+import { CReact as JSXCReact } from '../jsx';
+/**
+ * Configuration for CReact orchestrator
+ * REQ-04: Dependency injection - providers are injected via config
+ */
+export interface CReactConfig {
+    /** Cloud provider for materialization (injected) */
+    cloudProvider: ICloudProvider;
+    /** Backend provider for state management (injected) */
+    backendProvider: IBackendProvider;
+    /** Optional migration map for refactoring (REQ-08) */
+    migrationMap?: Record<string, string>;
+    /** Async timeout in milliseconds (default: 5 minutes) (REQ-10.5) */
+    asyncTimeout?: number;
+    /** Optional event hooks for reactive system integration */
+    eventHooks?: CReactEvents;
+}
+/**
+ * Retry policy configuration
+ */
+export interface RetryPolicy {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    timeout?: number;
+}
+/**
+ * CReact orchestrator - main class
+ *
+ * Orchestrates the entire infrastructure-as-code pipeline:
+ * 1. Render JSX → Fiber tree
+ * 2. Validate Fiber tree
+ * 3. Build CloudDOM from Fiber
+ * 4. Compare CloudDOM trees (diff via Reconciler)
+ * 5. Deploy CloudDOM via StateMachine
+ *
+ * REQ-01: JSX → CloudDOM rendering
+ * REQ-04: Dependency injection pattern
+ * REQ-05: Deployment orchestration via StateMachine
+ * REQ-07: Validation before commit/deploy
+ * REQ-09: Provider lifecycle hooks
+ * REQ-O01: StateMachine handles all state management
+ */
+export declare class CReact {
+    private config;
+    static cloudProvider: ICloudProvider;
+    static backendProvider: IBackendProvider;
+    static retryPolicy?: RetryPolicy;
+    static asyncTimeout?: number;
+    static migrationMap?: Record<string, string>;
+    static createElement: typeof JSXCReact.createElement;
+    static Fragment: (props: {
+        children?: any;
+    }) => import("../jsx").JSXElement;
+    private static globalInstance;
+    private static hydrationMap;
+    private renderer;
+    private validator;
+    private cloudDOMBuilder;
+    private reconciler;
+    private stateMachine;
+    private lastFiberTree;
+    private renderScheduler;
+    private stateBindingManager;
+    private providerOutputTracker;
+    private contextDependencyTracker;
+    private errorRecoveryManager;
+    private structuralChangeDetector;
+    private hasReactiveChanges;
+    private reactiveCloudDOM;
+    private preReactiveCloudDOM;
+    /**
+     * Constructor receives all dependencies via config (dependency injection)
+     *
+     * REQ-04: Providers are injected, not inherited
+     *
+     * @param config - Configuration with injected providers
+     */
+    constructor(config: CReactConfig);
+    /**
+     * Debug logging helper
+     * Logs messages when CREACT_DEBUG environment variable is set
+     *
+     * @param message - Message to log
+     */
+    private log;
+    /**
+     * Get the global CReact instance for hooks to access
+     * @internal
+     */
+    static getCReactInstance(): CReact | null;
+    /**
+     * Schedule a component for re-rendering
+     * This is called by hooks when reactive state changes
+     *
+     * @param fiber - Fiber node to re-render
+     * @param reason - Reason for the re-render
+     */
+    scheduleReRender(fiber: FiberNode, reason: ReRenderReason): void;
+    /**
+     * 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
+     * 3. Update bound state and enqueue affected fibers for re-render
+     *
+     * @param change - Output change event from provider
+     */
+    private handleProviderOutputChange;
+    /**
+     * Handle context value changes and trigger selective re-renders
+     * This is called when a context provider value changes
+     *
+     * @param contextId - Context identifier
+     * @param newValue - New context value
+     * @returns Promise resolving to affected fibers that were re-rendered
+     */
+    handleContextChange(contextId: symbol, newValue: any): Promise<FiberNode[]>;
+    /**
+     * Manual re-render trigger for CLI/testing
+     * Re-renders the entire stack or specific components
+     *
+     * @param stackName - Stack name to re-render (default: 'default')
+     * @param targetComponents - Optional specific components to re-render
+     * @returns Promise resolving to updated CloudDOM
+     */
+    rerender(stackName?: string, targetComponents?: FiberNode[]): Promise<CloudDOMNode[]>;
+    /**
+     * Build CloudDOM from JSX
+     *
+     * Pipeline: render → validate → build → restore outputs
+     *
+     * REQ-01: JSX → CloudDOM rendering
+     * REQ-07: Validate before commit
+     *
+     * @param jsx - JSX element to render
+     * @param stackName - Stack name for state restoration (default: 'default')
+     * @returns Promise resolving to CloudDOM tree
+     */
+    build(jsx: JSXElement, stackName?: string): Promise<CloudDOMNode[]>;
+    /**
+     * Build a map of node ID → outputs from previous CloudDOM
+     *
+     * @param previousCloudDOM - Previous CloudDOM state
+     * @returns Map of node ID → outputs
+     */
+    private buildOutputsMap;
+    /**
+     * Build CloudDOM 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 jsx - JSX element to render
+     * @returns Promise resolving to CloudDOM tree, or empty array on error
+     */
+    buildSafe(jsx: JSXElement): Promise<CloudDOMNode[]>;
+    /**
+     * Compare two CloudDOM trees and return diff
+     *
+     * REQ-05: Reconciliation and diff
+     * REQ-07.6: Validate before comparing
+     *
+     * @param previous - Previous CloudDOM tree
+     * @param current - Current CloudDOM tree
+     * @returns ChangeSet with creates, updates, deletes, and deployment order
+     */
+    compare(previous: CloudDOMNode[], current: CloudDOMNode[]): Promise<ChangeSet>;
+    /**
+     * Get reactive deployment information if changes are pending
+     * Returns null if no reactive changes detected
+     *
+     * This encapsulates the logic for checking reactive changes and computing diffs,
+     * keeping separation of concerns between core and CLI layers.
+     *
+     * @param stackName - Stack name to compute diff against
+     * @returns Reactive deployment info with CloudDOM and ChangeSet, or null
+     */
+    getReactiveDeploymentInfo(stackName: string): Promise<{
+        cloudDOM: CloudDOMNode[];
+        changeSet: any;
+    } | null>;
+    /**
+     * Clear reactive changes flag (called after deployment)
+     */
+    private clearReactiveChanges;
+    /**
+     * Deploy CloudDOM to cloud provider using StateMachine
+     *
+     * Pipeline: validate → compute diff → start deployment → materialize → checkpoint → complete
+     *
+     * REQ-05: Deployment orchestration via StateMachine
+     * REQ-05.4: Idempotent deployment (via Reconciler diff)
+     * REQ-07.6: Validate before deploying
+     * REQ-09: Provider lifecycle hooks
+     * REQ-O01: StateMachine handles all state management
+     *
+     * @param cloudDOM - CloudDOM tree to deploy
+     * @param stackName - Stack name for state management (default: 'default')
+     * @param user - User initiating deployment (default: 'system')
+     */
+    deploy(cloudDOM: CloudDOMNode[], stackName?: string, user?: string): Promise<void>;
+    /**
+     * Load previous state from backend and prepare for hydration
+     * This should be called before rendering to restore persisted state
+     *
+     * @param stackName - Stack name to load state for
+     */
+    loadStateForHydration(stackName: string): Promise<void>;
+    /**
+     * Prepare hydration data from previous CloudDOM
+     * This must be called BEFORE rendering to make state available to useState
+     *
+     * CRITICAL: State outputs belong to the COMPONENT that called useState,
+     * not the CloudDOM node. We need to key by component path (parent of node).
+     *
+     * Example:
+     * - Component path: ['web-app-stack']
+     * - CloudDOM node paths: ['web-app-stack', 'vpc'], ['web-app-stack', 'database']
+     * - All nodes from same component share the same state outputs
+     * - Hydration should be keyed by 'web-app-stack', not 'web-app-stack.vpc'
+     *
+     * @param previousCloudDOM - Previous CloudDOM with persisted state outputs
+     * @param clearExisting - Whether to clear existing hydration data (default: false)
+     */
+    prepareHydration(previousCloudDOM: CloudDOMNode[], clearExisting?: boolean): void;
+    /**
+     * Get hydrated value for a specific fiber and hook index
+     * Called by useState during render to check for persisted state
+     *
+     * @param fiberPath - Path of the fiber
+     * @param hookIndex - Index of the hook
+     * @returns Hydrated value or undefined if not found
+     */
+    getHydratedValue(fiberPath: string, hookIndex: number): any;
+    /**
+     * Get hydrated value for a component by searching for any child node
+     * This handles the case where useState is in a parent component but state
+     * outputs are stored on child CloudDOM nodes
+     *
+     * With the path mapping fix, this should now find exact matches.
+     * The child node search is kept as a fallback for edge cases.
+     *
+     * @param componentPath - Path of the component (e.g., 'web-app-stack')
+     * @param hookIndex - Index of the hook
+     * @returns Hydrated value or undefined if not found
+     */
+    getHydratedValueForComponent(componentPath: string, hookIndex: number): any;
+    /**
+     * Check if hydration data is available
+     *
+     * @returns True if hydration map has data
+     */
+    hasHydrationData(): boolean;
+    /**
+     * Get hydration map keys for debugging
+     *
+     * @returns Array of component paths with hydration data
+     */
+    getHydrationMapKeys(): string[];
+    /**
+     * Clear hydration data after rendering is complete
+     */
+    clearHydration(): void;
+    /**
+     * Serialize internal reactive state for hot reload preservation
+     * This captures the state of reactive systems that need to survive recompilation
+     *
+     * @returns Serialized state object
+     */
+    serializeReactiveState(): any;
+    /**
+     * Restore internal reactive state after hot reload recompilation
+     * This restores the state of reactive systems from serialized data
+     *
+     * @param serializedState - Previously serialized state
+     */
+    restoreReactiveState(serializedState: any): void;
+    /**
+     * Hydrate the current fiber tree with state values from previous CloudDOM
+     * This is used during hot reload to restore persisted state values
+     *
+     * @param previousCloudDOM - Previous CloudDOM with persisted state outputs
+     */
+    hydrateStateFromPreviousCloudDOM(previousCloudDOM: CloudDOMNode[]): void;
+    /**
+     * Check if outputs actually changed between previous and current CloudDOM
+     * REQ-7.1, 7.2, 7.3: Proper output change detection including undefined → value transitions
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state
+     * @returns True if any outputs actually changed
+     */
+    private hasActualOutputChanges;
+    /**
+     * Find a CloudDOM node by ID
+     *
+     * @param nodes - CloudDOM tree to search
+     * @param id - Node ID to find
+     * @returns CloudDOM node or undefined if not found
+     */
+    private findNodeById;
+    /**
+     * Extract outputs from CloudDOM nodes
+     *
+     * Walks the CloudDOM tree and collects all outputs from nodes.
+     * Outputs are formatted as nodeId.outputKey (e.g., 'registry.state-0').
+     *
+     * REQ-02: Extract outputs from useState calls
+     * REQ-06: Universal output access
+     *
+     * @param cloudDOM - CloudDOM tree
+     * @returns Outputs object with keys in format nodeId.outputKey
+     */
+    private extractOutputs;
+    /**
+     * Get the cloud provider (for testing/debugging)
+     *
+     * @returns The injected cloud provider
+     */
+    getCloudProvider(): ICloudProvider;
+    /**
+     * Get the backend provider (for testing/debugging)
+     *
+     * @returns The injected backend provider
+     */
+    getBackendProvider(): IBackendProvider;
+    /**
+     * Get the state machine (for testing/debugging)
+     *
+     * @returns The state machine instance
+     */
+    getStateMachine(): StateMachine;
+    /**
+     * Get backend state for a stack (for CLI/comparison)
+     *
+     * @param stackName - Stack name to get state for
+     * @returns Promise resolving to backend state or null
+     */
+    getBackendState(stackName: string): Promise<any>;
+    /**
+     * React-style render method (singleton API)
+     *
+     * Renders JSX to CloudDOM using the singleton configuration.
+     * This is the recommended API for entry files.
+     *
+     * Example:
+     * ```typescript
+     * // Configure providers
+     * CReact.cloudProvider = new AwsCloudProvider();
+     * CReact.backendProvider = new S3BackendProvider();
+     *
+     * // Render app
+     * export default CReact.renderCloudDOM(<MyApp />, 'my-stack');
+     * ```
+     *
+     * @param element - JSX element to render
+     * @param stackName - Stack name for state management
+     * @returns Promise resolving to CloudDOM tree
+     * @throws Error if providers are not configured
+     */
+    static renderCloudDOM(element: JSXElement, stackName: string): Promise<CloudDOMNode[]>;
+    /**
+     * Get the last instance created by renderCloudDOM (for CLI use)
+     * @internal
+     */
+    static getLastInstance(): {
+        instance: CReact;
+        element: JSXElement;
+        stackName: string;
+    } | null;
+}
+export declare const getCReactInstance: typeof CReact.getCReactInstance;