@creact-labs/creact 0.1.0

package/dist/hooks/useInstance.d.ts

@@ -0,0 +1,139 @@
+/**
+
+ * 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 '../core/types';
+import { ProviderOutputTracker } from '../core/ProviderOutputTracker';
+/**
+ * Set the ProviderOutputTracker instance (for testing/injection)
+ * @internal
+ */
+export declare function setProviderOutputTracker(tracker: ProviderOutputTracker): void;
+/**
+ * Get the ProviderOutputTracker instance (for external access)
+ * @internal
+ */
+export declare function getProviderOutputTrackerInstance(): ProviderOutputTracker;
+/**
+ * Set the current rendering context
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+export declare function setInstanceRenderContext(fiber: any, path: string[]): void;
+/**
+ * Clear the current rendering context
+ * Called by Renderer after component execution
+ *
+ * @internal
+ */
+export declare function clearInstanceRenderContext(): void;
+/**
+ * Set previous outputs map for restoration during render
+ * Called by CReact before rendering
+ *
+ * @internal
+ */
+export declare function setPreviousOutputs(outputsMap: Map<string, Record<string, any>> | null): void;
+/**
+ * useInstance hook - Register an infrastructure resource (React-like API)
+ *
+ * This hook creates a CloudDOM node and attaches it to the current Fiber.
+ * It must be called during component rendering (inside a component function).
+ *
+ * Automatically extracts event callbacks (onDeploy, onError, onDestroy) from
+ * component props and attaches them to the CloudDOM node for lifecycle events.
+ *
+ * REQ-01: JSX → CloudDOM rendering
+ * REQ-04: Resource creation via hooks (React-like API)
+ * REQ-2.3: CloudDOM event callbacks for deployment lifecycle
+ *
+ * @param construct - Constructor/class for the infrastructure resource
+ * @param props - Properties/configuration for the resource (may include `key` and event callbacks)
+ * @returns Reference to the created CloudDOM node
+ *
+ * @example
+ * ```tsx
+ * // With event callbacks (extracted from component props)
+ * function MyDatabase({ onDeploy, onError }) {
+ *   const db = useInstance(Database, {
+ *     name: 'my-db',
+ *     size: '100GB'
+ *   });
+ *   // onDeploy and onError are automatically extracted from component props
+ *   return <></>;
+ * }
+ *
+ * // Usage with event callbacks
+ * <MyDatabase
+ *   onDeploy={(ctx) => logger.info('Database deployed:', ctx.resourceId)}
+ *   onError={(ctx, err) => logger.error('Database failed:', err)}
+ * />
+ *
+ * // Without event callbacks (normal usage)
+ * function MyBucket() {
+ *   const bucket = useInstance(S3Bucket, {
+ *     bucketName: 'my-assets'
+ *   });
+ *   return <></>;
+ * }
+ * ```
+ */
+export declare function useInstance<T = any>(construct: new (...args: any[]) => T, props: Record<string, any>): CloudDOMNode;
+/**
+ * Reset construct call counts for a fiber
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+export declare function resetConstructCounts(fiber: any): void;
+/**
+ * Get the current rendering path
+ * Useful for debugging and testing
+ *
+ * @internal
+ */
+export declare function getCurrentPath(): string[];
+/**
+ * Check if currently rendering
+ * Useful for validation and testing
+ *
+ * @internal
+ */
+export declare function isRendering(): boolean;
+/**
+ * Update outputs for a CloudDOM node and notify bound components
+ * This is called after deployment when provider outputs are available
+ * @internal
+ */
+export declare function updateNodeOutputs(nodeId: string, newOutputs: Record<string, any>): void;
+/**
+ * Get current outputs for a CloudDOM node
+ * @internal
+ */
+export declare function getNodeOutputs(nodeId: string): Record<string, any>;

package/dist/hooks/useInstance.js

@@ -0,0 +1,441 @@
+"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.setProviderOutputTracker = setProviderOutputTracker;
+exports.getProviderOutputTrackerInstance = getProviderOutputTrackerInstance;
+exports.setInstanceRenderContext = setInstanceRenderContext;
+exports.clearInstanceRenderContext = clearInstanceRenderContext;
+exports.setPreviousOutputs = setPreviousOutputs;
+exports.useInstance = useInstance;
+exports.resetConstructCounts = resetConstructCounts;
+exports.getCurrentPath = getCurrentPath;
+exports.isRendering = isRendering;
+exports.updateNodeOutputs = updateNodeOutputs;
+exports.getNodeOutputs = getNodeOutputs;
+const naming_1 = require("../utils/naming");
+const ProviderOutputTracker_1 = require("../core/ProviderOutputTracker");
+const context_1 = require("./context");
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('hooks');
+// Global ProviderOutputTracker instance
+let providerOutputTracker = null;
+/**
+ * Get or create the global ProviderOutputTracker instance
+ * @internal
+ */
+function getProviderOutputTracker() {
+    if (!providerOutputTracker) {
+        providerOutputTracker = new ProviderOutputTracker_1.ProviderOutputTracker();
+    }
+    return providerOutputTracker;
+}
+/**
+ * Set the ProviderOutputTracker instance (for testing/injection)
+ * @internal
+ */
+function setProviderOutputTracker(tracker) {
+    providerOutputTracker = tracker;
+}
+/**
+ * Get the ProviderOutputTracker instance (for external access)
+ * @internal
+ */
+function getProviderOutputTrackerInstance() {
+    return getProviderOutputTracker();
+}
+/**
+ * Create a placeholder node when dependencies are undefined
+ * This node won't be included in CloudDOM but allows the component to continue rendering
+ * All output accesses return undefined
+ *
+ * @internal
+ */
+function createPlaceholderNode() {
+    const placeholderNode = {
+        id: '__placeholder__',
+        path: ['__placeholder__'],
+        construct: class Placeholder {
+        },
+        constructType: 'Placeholder',
+        props: {},
+        children: [],
+        outputs: {},
+    };
+    // Return a proxy that always returns undefined for outputs
+    return new Proxy(placeholderNode, {
+        get(target, prop) {
+            if (prop === 'outputs') {
+                return new Proxy({}, {
+                    get() {
+                        return undefined;
+                    },
+                });
+            }
+            return Reflect.get(target, prop);
+        },
+    });
+}
+/**
+ * Create an enhanced CloudDOM node with output reference capabilities
+ * This allows automatic binding when outputs are used in useState
+ * The proxy dynamically reads from the node's current outputs for reactivity
+ *
+ * REQ-2.1, 2.4, 2.5: Enhanced proxy that always reads live values and tracks access
+ *
+ * @internal
+ */
+function createEnhancedNode(node, fiber) {
+    // Create a proxy that intercepts property access to provide reactive output access
+    return new Proxy(node, {
+        get(target, prop, receiver) {
+            // Special handling for 'outputs' property to ensure reactivity
+            if (prop === 'outputs') {
+                // Return a proxy for the outputs object that tracks reads
+                return new Proxy(target.outputs || {}, {
+                    get(outputsTarget, outputKey) {
+                        if (typeof outputKey === 'string') {
+                            // REQ-2.1: Always read from current target.outputs (live values)
+                            const currentValue = target.outputs?.[outputKey];
+                            // REQ-2.4, 2.5: Track this output read for binding creation
+                            if (currentValue !== undefined) {
+                                const tracker = getProviderOutputTracker();
+                                tracker.trackOutputRead(target.id, outputKey, fiber);
+                                logger.debug(`Tracked output read: ${target.id}.${outputKey} = ${currentValue}`);
+                            }
+                            // REQ-2.2: Return undefined gracefully if not populated
+                            return currentValue;
+                        }
+                        return Reflect.get(outputsTarget, outputKey);
+                    },
+                    has(outputsTarget, outputKey) {
+                        // Check if output exists in current target.outputs
+                        return (typeof outputKey === 'string' &&
+                            target.outputs !== undefined &&
+                            outputKey in target.outputs);
+                    },
+                    ownKeys(outputsTarget) {
+                        // Return keys from current target.outputs
+                        return target.outputs ? Object.keys(target.outputs) : [];
+                    },
+                });
+            }
+            // For all other properties, return the original value
+            return Reflect.get(target, prop, receiver);
+        },
+        has(target, prop) {
+            // Standard property checks
+            return Reflect.has(target, prop);
+        },
+        ownKeys(target) {
+            // Return original keys
+            return Reflect.ownKeys(target);
+        },
+    });
+}
+/**
+ * Set the current rendering context
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+function setInstanceRenderContext(fiber, path) {
+    (0, context_1.setRenderContext)(fiber, path);
+}
+/**
+ * Clear the current rendering context
+ * Called by Renderer after component execution
+ *
+ * @internal
+ */
+function clearInstanceRenderContext() {
+    (0, context_1.clearRenderContext)();
+}
+/**
+ * Set previous outputs map for restoration during render
+ * Called by CReact before rendering
+ *
+ * @internal
+ */
+function setPreviousOutputs(outputsMap) {
+    (0, context_1.setPreviousOutputs)(outputsMap);
+}
+/**
+ * Track construct call counts per component for auto-ID generation
+ * Maps component fiber to construct type to call count
+ */
+const constructCallCounts = new WeakMap();
+/**
+ * useInstance hook - Register an infrastructure resource (React-like API)
+ *
+ * This hook creates a CloudDOM node and attaches it to the current Fiber.
+ * It must be called during component rendering (inside a component function).
+ *
+ * Automatically extracts event callbacks (onDeploy, onError, onDestroy) from
+ * component props and attaches them to the CloudDOM node for lifecycle events.
+ *
+ * REQ-01: JSX → CloudDOM rendering
+ * REQ-04: Resource creation via hooks (React-like API)
+ * REQ-2.3: CloudDOM event callbacks for deployment lifecycle
+ *
+ * @param construct - Constructor/class for the infrastructure resource
+ * @param props - Properties/configuration for the resource (may include `key` and event callbacks)
+ * @returns Reference to the created CloudDOM node
+ *
+ * @example
+ * ```tsx
+ * // With event callbacks (extracted from component props)
+ * function MyDatabase({ onDeploy, onError }) {
+ *   const db = useInstance(Database, {
+ *     name: 'my-db',
+ *     size: '100GB'
+ *   });
+ *   // onDeploy and onError are automatically extracted from component props
+ *   return <></>;
+ * }
+ *
+ * // Usage with event callbacks
+ * <MyDatabase
+ *   onDeploy={(ctx) => logger.info('Database deployed:', ctx.resourceId)}
+ *   onError={(ctx, err) => logger.error('Database failed:', err)}
+ * />
+ *
+ * // Without event callbacks (normal usage)
+ * function MyBucket() {
+ *   const bucket = useInstance(S3Bucket, {
+ *     bucketName: 'my-assets'
+ *   });
+ *   return <></>;
+ * }
+ * ```
+ */
+function useInstance(construct, props) {
+    // Use consolidated hook context
+    const context = (0, context_1.requireHookContext)();
+    const currentFiber = context.currentFiber; // Non-null assertion safe due to requireHookContext validation
+    const { currentPath, previousOutputsMap } = context;
+    // Get hook index for this useInstance call (instance-specific)
+    const hookIndex = (0, context_1.incrementHookIndex)('instance');
+    // Extract key from props (React-like)
+    const { key, ...restProps } = props;
+    // Check for undefined dependencies - enforce deployment order
+    // If any prop value is undefined, don't create the node yet
+    // This ensures resources are only created when their dependencies are available
+    const hasUndefinedDeps = Object.values(restProps).some((v) => v === undefined);
+    if (hasUndefinedDeps) {
+        logger.info(`[Deployment Order] Skipping resource creation - undefined dependencies detected`);
+        logger.info(`  Construct: ${construct.name}`);
+        logger.info(`  Props with undefined values:`, Object.entries(restProps)
+            .filter(([_, v]) => v === undefined)
+            .map(([k]) => k));
+        // Don't attach anything to fiber - this resource will be skipped entirely
+        // Return a placeholder node that won't be included in CloudDOM
+        // The proxy will return undefined for all output accesses
+        return createPlaceholderNode();
+    }
+    // Remove undefined values from props to match JSON serialization behavior
+    // When CloudDOM is saved to backend, JSON.stringify strips undefined values
+    // This ensures consistent comparison after deserialization
+    const cleanProps = {};
+    for (const [k, v] of Object.entries(restProps)) {
+        if (v !== undefined) {
+            cleanProps[k] = v;
+        }
+    }
+    // Extract event callbacks from current component's props (not useInstance props)
+    const componentProps = currentFiber.props || {};
+    const eventCallbacks = {};
+    // Extract onDeploy callback
+    if (typeof componentProps.onDeploy === 'function') {
+        eventCallbacks.onDeploy = componentProps.onDeploy;
+    }
+    // Extract onError callback
+    if (typeof componentProps.onError === 'function') {
+        eventCallbacks.onError = componentProps.onError;
+    }
+    // Extract onDestroy callback
+    if (typeof componentProps.onDestroy === 'function') {
+        eventCallbacks.onDestroy = componentProps.onDestroy;
+    }
+    // Generate ID from key or construct type
+    // Priority: explicit key from useInstance props > component fiber key > auto-generated
+    let id;
+    if (key !== undefined) {
+        // Use explicit key if provided in useInstance props
+        id = String(key);
+    }
+    else {
+        // Auto-generate ID from construct type name (kebab-case)
+        const constructName = (0, naming_1.toKebabCase)(construct.name);
+        // Track call count for this construct type in this component
+        if (!constructCallCounts.has(currentFiber)) {
+            constructCallCounts.set(currentFiber, new Map());
+        }
+        const counts = constructCallCounts.get(currentFiber);
+        const count = counts.get(construct) || 0;
+        counts.set(construct, count + 1);
+        // Append index if multiple calls with same type
+        if (count > 0) {
+            id = `${constructName}-${count}`;
+        }
+        else {
+            id = constructName;
+        }
+        // If component has a key (from JSX), prepend it to make resources unique per component instance
+        if (currentFiber.key) {
+            id = `${currentFiber.key}-${id}`;
+        }
+    }
+    // Generate full resource ID from current path
+    // Example: ['registry', 'service'] + 'bucket' → 'registry.service.bucket'
+    const fullPath = [...currentPath, id];
+    const resourceId = (0, naming_1.generateResourceId)(fullPath);
+    // Generate stable constructType identifier
+    // This is a serializable string that uniquely identifies the construct type
+    const constructType = construct.name || 'UnknownConstruct';
+    // Create CloudDOM node
+    const node = {
+        id: resourceId,
+        path: fullPath,
+        construct,
+        constructType, // Serializable construct type identifier
+        props: cleanProps, // Use cleaned props (no undefined values, no key)
+        children: [],
+        outputs: {}, // Will be populated during materialization
+        eventCallbacks: Object.keys(eventCallbacks).length > 0 ? eventCallbacks : undefined,
+    };
+    // Restore outputs from previous state if available
+    logger.debug(`Checking for outputs: ${resourceId}, map has ${previousOutputsMap?.size || 0} entries`);
+    if (previousOutputsMap && previousOutputsMap.has(resourceId)) {
+        node.outputs = { ...previousOutputsMap.get(resourceId) };
+        logger.debug(`✓ Restored outputs for: ${resourceId}`, node.outputs);
+    }
+    else {
+        logger.debug(`✗ No outputs found for: ${resourceId}`);
+        if (previousOutputsMap) {
+            logger.debug(`  Available keys:`, Array.from(previousOutputsMap.keys()));
+        }
+    }
+    // Attach node to current Fiber
+    // The Fiber stores all CloudDOM nodes created during its execution
+    if (!currentFiber.cloudDOMNodes) {
+        currentFiber.cloudDOMNodes = [];
+    }
+    // Check if a node with this ID already exists (from previous render)
+    // If so, update it instead of creating a duplicate
+    const existingNodeIndex = currentFiber.cloudDOMNodes.findIndex((n) => n.id === resourceId);
+    if (existingNodeIndex >= 0) {
+        logger.debug(`Updating existing node: ${resourceId}`);
+        currentFiber.cloudDOMNodes[existingNodeIndex] = node;
+    }
+    else {
+        logger.debug(`Creating new node: ${resourceId}`);
+        currentFiber.cloudDOMNodes.push(node);
+    }
+    // Track this instance with ProviderOutputTracker for output change detection
+    const outputTracker = getProviderOutputTracker();
+    outputTracker.trackInstance(node, currentFiber);
+    // REQ-2.3, 6.1: Enhance the node with proxy that reads live values and tracks access
+    // No longer creating stale outputReferences - proxy reads directly from target.outputs
+    const enhancedNode = createEnhancedNode(node, currentFiber);
+    // Debug logging
+    logger.debug(`Created and tracked instance: ${resourceId}`);
+    logger.debug(`Node outputs at creation: ${JSON.stringify(node.outputs || {})}`);
+    // Return reference to the enhanced node
+    // This allows components to reference the resource and its outputs
+    // REQ-2.5: Multiple accesses within same render cycle are consistent
+    return enhancedNode;
+}
+/**
+ * Reset construct call counts for a fiber
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+function resetConstructCounts(fiber) {
+    constructCallCounts.delete(fiber);
+}
+/**
+ * Get the current rendering path
+ * Useful for debugging and testing
+ *
+ * @internal
+ */
+function getCurrentPath() {
+    try {
+        const context = (0, context_1.requireHookContext)();
+        return [...context.currentPath];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check if currently rendering
+ * Useful for validation and testing
+ *
+ * @internal
+ */
+function isRendering() {
+    try {
+        const context = (0, context_1.requireHookContext)();
+        return context.currentFiber !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Update outputs for a CloudDOM node and notify bound components
+ * This is called after deployment when provider outputs are available
+ * @internal
+ */
+function updateNodeOutputs(nodeId, newOutputs) {
+    const outputTracker = getProviderOutputTracker();
+    const changes = outputTracker.updateNodeOutputs(nodeId, newOutputs);
+    if (changes.length > 0) {
+        // Process the changes and get affected fibers
+        const affectedFibers = outputTracker.processOutputChanges(changes);
+        logger.debug(`Output changes detected for ${nodeId}:`, {
+            changes: changes.length,
+            affectedFibers: affectedFibers.size,
+        });
+        // Note: The actual re-rendering will be handled by the RenderScheduler
+        // when it's integrated with the CReact main orchestrator
+    }
+}
+/**
+ * Get current outputs for a CloudDOM node
+ * @internal
+ */
+function getNodeOutputs(nodeId) {
+    const outputTracker = getProviderOutputTracker();
+    return outputTracker.getNodeOutputs(nodeId);
+}

package/dist/hooks/useState.d.ts

@@ -0,0 +1,120 @@
+/**
+
+ * 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 { StateBindingManager } from '../core/StateBindingManager';
+import { FiberNode } from '../core/types';
+/**
+ * Set the StateBindingManager instance (for testing/injection)
+ * @internal
+ */
+export declare function setStateBindingManager(manager: StateBindingManager): void;
+/**
+ * Get the StateBindingManager instance (for external access)
+ * @internal
+ */
+export declare function getStateBindingManagerInstance(): StateBindingManager;
+/**
+ * Set the current rendering context for useState
+ * Called by Renderer before executing a component
+ *
+ * @internal
+ */
+export declare function setStateRenderContext(fiber: FiberNode, path?: string[]): void;
+/**
+ * Clear the current rendering context for useState
+ * Called by Renderer after component execution
+ *
+ * @internal
+ */
+export declare function clearStateRenderContext(): void;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+export declare function useState<T = undefined>(initialValue?: T): [T, (value: T | ((prev: T) => T)) => void];
+/**
+ * Check if useState context is available
+ * Useful for validation and testing
+ *
+ * @internal
+ */
+export declare function hasStateContext(): boolean;
+/**
+ * Get the current state from Fiber (for testing)
+ *
+ * @internal
+ */
+export declare function getCurrentState(): Record<string, any> | undefined;