@creact-labs/creact 0.1.0

package/dist/hooks/useState.js

@@ -0,0 +1,298 @@
+"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.setStateBindingManager = setStateBindingManager;
+exports.getStateBindingManagerInstance = getStateBindingManagerInstance;
+exports.setStateRenderContext = setStateRenderContext;
+exports.clearStateRenderContext = clearStateRenderContext;
+exports.useState = useState;
+exports.hasStateContext = hasStateContext;
+exports.getCurrentState = getCurrentState;
+// REQ-02: useState hook for declarative output binding
+// This hook declares component outputs that persist across build/deploy cycles
+const context_1 = require("./context");
+const StateBindingManager_1 = require("../core/StateBindingManager");
+const naming_1 = require("../utils/naming");
+const ReactiveUpdateQueue_1 = require("../core/ReactiveUpdateQueue");
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('hooks');
+const CReact_1 = require("../core/CReact");
+// Global StateBindingManager instance
+let stateBindingManager = null;
+/**
+ * Get or create the global StateBindingManager instance
+ * @internal
+ */
+function getStateBindingManager() {
+    if (!stateBindingManager) {
+        stateBindingManager = new StateBindingManager_1.StateBindingManager();
+    }
+    return stateBindingManager;
+}
+/**
+ * Set the StateBindingManager instance (for testing/injection)
+ * @internal
+ */
+function setStateBindingManager(manager) {
+    stateBindingManager = manager;
+}
+/**
+ * Get the StateBindingManager instance (for external access)
+ * @internal
+ */
+function getStateBindingManagerInstance() {
+    return getStateBindingManager();
+}
+/**
+ * Set the current rendering context for useState
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+function setStateRenderContext(fiber, path) {
+    (0, context_1.setRenderContext)(fiber, path);
+}
+/**
+ * Clear the current rendering context for useState
+ * Called by Renderer after component execution
+ *
+ * @internal
+ */
+function clearStateRenderContext() {
+    (0, context_1.clearRenderContext)();
+}
+/**
+ * useState hook - Declare component outputs (NOT reactive state)
+ *
+ * This hook declares outputs that will be persisted across build/deploy cycles.
+ * Unlike React's useState, this does NOT trigger re-renders.
+ *
+ * Mimics React's useState API with hooks array pattern for multiple calls.
+ *
+ * REQ-02: Stack Context (declarative outputs)
+ *
+ * Semantics:
+ * - `useState(initialValue)` - Declares a single output value
+ * - `setState(value)` during build - Updates the output value for build-time enrichment
+ * - `setState(value)` during deploy - Updates persisted output after provider materialization
+ * - NOT a render trigger - it's a persistent output update mechanism
+ * - Supports multiple useState calls per component (like React)
+ *
+ * Key difference from React:
+ * - React: `setState()` causes re-render in memory
+ * - CReact: `setState()` updates persisted outputs for next cycle
+ *
+ * @param initialValue - Initial output value to declare
+ * @returns Tuple of [state, setState] where setState updates the output value
+ *
+ * @example
+ * ```tsx
+ * function CDNStack({ children }) {
+ *   const distribution = useInstance('cdn', CloudFrontDistribution, { ... });
+ *
+ *   // Multiple useState calls (like React)
+ *   const [distributionId, setDistributionId] = useState<string>();
+ *   const [distributionDomain, setDistributionDomain] = useState<string>();
+ *   const [distributionArn, setDistributionArn] = useState<string>();
+ *
+ *   // Optional: Enrich outputs after async materialization
+ *   useEffect(async () => {
+ *     const actualDomain = await distribution.getDomain();
+ *     setDistributionDomain(actualDomain);
+ *   }, [distribution]);
+ *
+ *   // Aggregate outputs for StackContext
+ *   const outputs = {
+ *     distributionId,
+ *     distributionDomain,
+ *     distributionArn,
+ *   };
+ *
+ *   return <StackContext.Provider value={outputs}>{children}</StackContext.Provider>;
+ * }
+ * ```
+ */
+function useState(initialValue) {
+    // Use consolidated hook context
+    const context = (0, context_1.requireHookContext)();
+    const currentFiber = context.currentFiber; // Non-null assertion safe due to requireHookContext validation
+    // Initialize hooks array in Fiber node if not already present
+    if (!currentFiber.hooks) {
+        currentFiber.hooks = [];
+    }
+    // Get current hook index and increment for next call (state-specific)
+    const currentHookIndex = (0, context_1.incrementHookIndex)('state');
+    // Initialize this hook's state if first render
+    if (currentFiber.hooks[currentHookIndex] === undefined) {
+        // CRITICAL: Check for hydrated value first (hot reload state restoration)
+        // This allows useState to restore persisted state instead of using initial value
+        let hydratedValue = undefined;
+        // Try to get CReact instance to check for hydration data
+        try {
+            const creactInstance = (0, CReact_1.getCReactInstance)?.();
+            if (creactInstance && creactInstance.hasHydrationData()) {
+                // CRITICAL: The fiber path is the component path (e.g., 'web-app-stack')
+                const fiberPath = currentFiber.path?.join('.') || '';
+                logger.debug(`🔍 Looking for hydration: component="${fiberPath}", hookIndex=${currentHookIndex}`);
+                // Try to get hydration from component path
+                hydratedValue = creactInstance.getHydratedValueForComponent(fiberPath, currentHookIndex);
+                if (hydratedValue !== undefined) {
+                    logger.debug(`✅ HYDRATION SUCCESS for ${fiberPath}[${currentHookIndex}]:`, hydratedValue);
+                }
+                else {
+                    logger.debug(`❌ HYDRATION FAILED for ${fiberPath}[${currentHookIndex}]`);
+                    logger.debug(`   Available hydration keys:`, creactInstance.getHydrationMapKeys?.() || 'N/A');
+                }
+            }
+            else {
+                logger.debug(`⚠️  No hydration data available (instance=${!!creactInstance}, hasData=${creactInstance?.hasHydrationData()})`);
+            }
+        }
+        catch (error) {
+            // Hydration is optional, continue with initial value if it fails
+            logger.warn('⚠️  Hydration check failed:', error);
+            logger.debug('Stack:', error.stack);
+        }
+        // Use hydrated value if available, otherwise use initial value
+        const finalValue = hydratedValue !== undefined ? hydratedValue : initialValue;
+        currentFiber.hooks[currentHookIndex] = finalValue;
+        logger.debug(`📝 Initialized hook[${currentHookIndex}] = ${JSON.stringify(finalValue)} (hydrated=${hydratedValue !== undefined})`);
+    }
+    // Store the fiber and hook index for later access
+    const fiber = currentFiber;
+    const hookIdx = currentHookIndex;
+    /**
+     * setState function - Updates the output value with reactive capabilities
+     *
+     * This function updates the persisted output in the Fiber node's hooks array.
+     * It now includes:
+     * - Change detection to avoid unnecessary updates
+     * - Automatic binding detection for provider outputs
+     * - Integration with StateBindingManager for reactive updates
+     * - REQ-4.1, 4.2, 4.3: Internal update mechanism to prevent circular dependencies
+     *
+     * During build: Collects values known at build-time
+     * During deploy: Patches in async resources (queue URLs, ARNs)
+     *
+     * @param value - New value or updater function
+     * @param isInternalUpdate - If true, skip binding creation (prevents loops)
+     */
+    const setState = (value, isInternalUpdate = false) => {
+        // Resolve value (handle both direct value and function forms)
+        const newValue = typeof value === 'function' ? value(fiber.hooks?.[hookIdx]) : value;
+        const oldValue = fiber.hooks?.[hookIdx];
+        // Debug logging (before change check for better visibility)
+        if (process.env.CREACT_DEBUG === 'true') {
+            const safeStringify = (value) => {
+                try {
+                    return JSON.stringify(value);
+                }
+                catch {
+                    return String(value);
+                }
+            };
+            logger.debug(`setState called: hookIdx=${hookIdx}, oldValue=${safeStringify(oldValue)}, newValue=${safeStringify(newValue)}, isInternal=${isInternalUpdate}, fiber.id=${fiber.path?.join('.')}`);
+        }
+        // Only proceed if value actually changed
+        if (oldValue === newValue) {
+            logger.debug(`No change detected, skipping update`);
+            return; // No change, skip update
+        }
+        // Update this hook's state
+        if (fiber.hooks) {
+            fiber.hooks[hookIdx] = newValue;
+        }
+        // REQ-4.2: Only create bindings for user updates, not internal ones
+        // This prevents infinite binding loops when StateBindingManager updates state
+        if (!isInternalUpdate) {
+            // Check if the new value is a provider output and create automatic binding
+            const bindingManager = getStateBindingManager();
+            const outputInfo = bindingManager.isProviderOutput(newValue);
+            if (outputInfo) {
+                // REQ-4.1, 4.3: Prevent infinite binding loops during reactivity
+                // Only bind if this state is not already bound to this output
+                if (!bindingManager.isStateBoundToOutput(fiber, hookIdx)) {
+                    // Automatically bind this state to the provider output
+                    bindingManager.bindStateToOutput(fiber, hookIdx, outputInfo.nodeId, outputInfo.outputKey, newValue);
+                    const bindingKey = (0, naming_1.generateBindingKey)(outputInfo.nodeId, outputInfo.outputKey);
+                    logger.debug(`Auto-bound state to output: ${bindingKey}`);
+                }
+                else {
+                    const bindingKey = (0, naming_1.generateBindingKey)(outputInfo.nodeId, outputInfo.outputKey);
+                    logger.debug(`Skipped re-binding already bound state: ${bindingKey}`);
+                }
+            }
+        }
+        else {
+            logger.debug(`Skipped binding check for internal update`);
+        }
+        // REQ-4.4: Mark fiber as dirty and enqueue for re-render
+        // This is critical for initial deployment where outputs go from undefined → value
+        // The fiber will be collected by the reactivity phase and re-rendered
+        if (!isInternalUpdate && oldValue !== newValue) {
+            // Mark this fiber as having state changes
+            if (!fiber.__stateChanged) {
+                fiber.__stateChanged = true;
+            }
+            // Enqueue fiber for re-rendering in reactivity phase
+            const queue = (0, ReactiveUpdateQueue_1.getReactiveUpdateQueue)();
+            queue.enqueue(fiber);
+            logger.debug(`Enqueued fiber ${fiber.path?.join('.')} for re-render (queue size: ${queue.size()})`);
+        }
+    };
+    // REQ-4.1, 4.2: Store setState callback in fiber for internal updates
+    // This allows StateBindingManager to update state without creating new bindings
+    if (!fiber.setStateCallbacks) {
+        fiber.setStateCallbacks = [];
+    }
+    fiber.setStateCallbacks[hookIdx] = setState;
+    // Get current state for this hook - read it fresh each time
+    // This ensures synchronous setState calls during render are reflected
+    const state = (fiber.hooks && fiber.hooks[hookIdx]);
+    return [state, setState];
+}
+/**
+ * Check if useState context is available
+ * Useful for validation and testing
+ *
+ * @internal
+ */
+function hasStateContext() {
+    return (0, context_1.hasRenderContext)();
+}
+/**
+ * Get the current state from Fiber (for testing)
+ *
+ * @internal
+ */
+function getCurrentState() {
+    return (0, context_1.getCurrentState)();
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+
+ * 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 { CReact, JSXElement } from './jsx';
+export type { FC, PropsWithChildren } from './jsx.d';
+import { CReact as CReactClass } from './core/CReact';
+export { CReact as CReactCore, CReactConfig } from './core/CReact';
+export declare const renderCloudDOM: typeof CReactClass.renderCloudDOM;
+export { Renderer } from './core/Renderer';
+export { Validator } from './core/Validator';
+export { CloudDOMBuilder } from './core/CloudDOMBuilder';
+export { FiberNode, CloudDOMNode } from './core/types';
+export { ICloudProvider } from './providers/ICloudProvider';
+export { IBackendProvider } from './providers/IBackendProvider';
+export { useInstance } from './hooks/useInstance';
+export { useState } from './hooks/useState';
+export { useContext } from './hooks/useContext';
+export { useEffect } from './hooks/useEffect';
+export { createContext, Context } from './context';
+export { generateResourceId, toKebabCase, getNodeName, validateIdUniqueness, normalizePathSegment, normalizePath, formatPath, parseResourceId, } from './utils/naming';

package/dist/index.js

@@ -0,0 +1,70 @@
+"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.parseResourceId = exports.formatPath = exports.normalizePath = exports.normalizePathSegment = exports.validateIdUniqueness = exports.getNodeName = exports.toKebabCase = exports.generateResourceId = exports.createContext = exports.useEffect = exports.useContext = exports.useState = exports.useInstance = exports.CloudDOMBuilder = exports.Validator = exports.Renderer = exports.renderCloudDOM = exports.CReactCore = exports.CReact = void 0;
+// CReact - Infrastructure as Code with JSX
+// Main entry point for the library
+// JSX support
+var jsx_1 = require("./jsx");
+Object.defineProperty(exports, "CReact", { enumerable: true, get: function () { return jsx_1.CReact; } });
+// Core classes
+const CReact_1 = require("./core/CReact");
+var CReact_2 = require("./core/CReact");
+Object.defineProperty(exports, "CReactCore", { enumerable: true, get: function () { return CReact_2.CReact; } });
+exports.renderCloudDOM = CReact_1.CReact.renderCloudDOM;
+var Renderer_1 = require("./core/Renderer");
+Object.defineProperty(exports, "Renderer", { enumerable: true, get: function () { return Renderer_1.Renderer; } });
+var Validator_1 = require("./core/Validator");
+Object.defineProperty(exports, "Validator", { enumerable: true, get: function () { return Validator_1.Validator; } });
+var CloudDOMBuilder_1 = require("./core/CloudDOMBuilder");
+Object.defineProperty(exports, "CloudDOMBuilder", { enumerable: true, get: function () { return CloudDOMBuilder_1.CloudDOMBuilder; } });
+// Hooks
+var useInstance_1 = require("./hooks/useInstance");
+Object.defineProperty(exports, "useInstance", { enumerable: true, get: function () { return useInstance_1.useInstance; } });
+var useState_1 = require("./hooks/useState");
+Object.defineProperty(exports, "useState", { enumerable: true, get: function () { return useState_1.useState; } });
+var useContext_1 = require("./hooks/useContext");
+Object.defineProperty(exports, "useContext", { enumerable: true, get: function () { return useContext_1.useContext; } });
+var useEffect_1 = require("./hooks/useEffect");
+Object.defineProperty(exports, "useEffect", { enumerable: true, get: function () { return useEffect_1.useEffect; } });
+// Context API
+var context_1 = require("./context");
+Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return context_1.createContext; } });
+// Utilities
+var naming_1 = require("./utils/naming");
+Object.defineProperty(exports, "generateResourceId", { enumerable: true, get: function () { return naming_1.generateResourceId; } });
+Object.defineProperty(exports, "toKebabCase", { enumerable: true, get: function () { return naming_1.toKebabCase; } });
+Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function () { return naming_1.getNodeName; } });
+Object.defineProperty(exports, "validateIdUniqueness", { enumerable: true, get: function () { return naming_1.validateIdUniqueness; } });
+Object.defineProperty(exports, "normalizePathSegment", { enumerable: true, get: function () { return naming_1.normalizePathSegment; } });
+Object.defineProperty(exports, "normalizePath", { enumerable: true, get: function () { return naming_1.normalizePath; } });
+Object.defineProperty(exports, "formatPath", { enumerable: true, get: function () { return naming_1.formatPath; } });
+Object.defineProperty(exports, "parseResourceId", { enumerable: true, get: function () { return naming_1.parseResourceId; } });

package/dist/jsx.d.ts

@@ -0,0 +1,64 @@
+/**
+
+ * 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
+
+ */
+/**
+ * JSX factory for CReact
+ *
+ * This module provides the createElement factory function that TypeScript
+ * uses to transform JSX syntax into function calls.
+ *
+ * Example transformation:
+ *   <Component prop="value" />
+ *   → CReact.createElement(Component, { prop: "value" })
+ */
+export interface JSXElement {
+    type: any;
+    props: Record<string, any>;
+    key?: string | number;
+}
+export declare namespace CReact {
+    /**
+     * JSX factory function called by TypeScript when transforming JSX
+     *
+     * @param type - Component function or string (for intrinsic elements)
+     * @param props - Props object (may include key and children)
+     * @param children - Child elements (variadic)
+     * @returns JSXElement object with normalized props
+     */
+    function createElement(type: any, props: Record<string, any> | null, ...children: any[]): JSXElement;
+    /**
+     * Fragment symbol for <>...</> syntax
+     * Fragments allow grouping multiple children without adding extra nodes
+     *
+     * Note: Fragment is a Symbol at runtime, but typed as a function for JSX compatibility
+     */
+    const Fragment: (props: {
+        children?: any;
+    }) => JSXElement;
+}

package/dist/jsx.js

@@ -0,0 +1,76 @@
+"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.CReact = void 0;
+var CReact;
+(function (CReact) {
+    /**
+     * JSX factory function called by TypeScript when transforming JSX
+     *
+     * @param type - Component function or string (for intrinsic elements)
+     * @param props - Props object (may include key and children)
+     * @param children - Child elements (variadic)
+     * @returns JSXElement object with normalized props
+     */
+    function createElement(type, props, ...children) {
+        // Normalize props (handle null case)
+        const normalizedProps = props ? { ...props } : {};
+        // Extract key from props if present
+        const key = normalizedProps.key;
+        delete normalizedProps.key;
+        // Handle children normalization
+        if (children.length > 0) {
+            // Flatten children array and filter out null/undefined
+            const flattenedChildren = children.flat().filter((child) => child != null);
+            // Single child: store as-is
+            // Multiple children: store as array
+            if (flattenedChildren.length === 1) {
+                normalizedProps.children = flattenedChildren[0];
+            }
+            else if (flattenedChildren.length > 1) {
+                normalizedProps.children = flattenedChildren;
+            }
+        }
+        return {
+            type,
+            props: normalizedProps,
+            key,
+        };
+    }
+    CReact.createElement = createElement;
+    /**
+     * Fragment symbol for <>...</> syntax
+     * Fragments allow grouping multiple children without adding extra nodes
+     *
+     * Note: Fragment is a Symbol at runtime, but typed as a function for JSX compatibility
+     */
+    CReact.Fragment = Symbol.for('CReact.Fragment');
+})(CReact || (exports.CReact = CReact = {}));