@creact-labs/creact 0.1.0

package/dist/core/index.js

@@ -0,0 +1,64 @@
+"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
+
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateMachine = exports.ProviderError = exports.ValidationError = exports.DeploymentError = exports.ReconciliationError = exports.Reconciler = exports.CloudDOMEventBus = void 0;
+// REQ-01: Core module exports
+__exportStar(require("./types"), exports);
+__exportStar(require("./Renderer"), exports);
+__exportStar(require("./Validator"), exports);
+__exportStar(require("./CloudDOMBuilder"), exports);
+__exportStar(require("./CReact"), exports);
+var EventBus_1 = require("./EventBus");
+Object.defineProperty(exports, "CloudDOMEventBus", { enumerable: true, get: function () { return EventBus_1.CloudDOMEventBus; } });
+var Reconciler_1 = require("./Reconciler");
+Object.defineProperty(exports, "Reconciler", { enumerable: true, get: function () { return Reconciler_1.Reconciler; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ReconciliationError", { enumerable: true, get: function () { return errors_1.ReconciliationError; } });
+Object.defineProperty(exports, "DeploymentError", { enumerable: true, get: function () { return errors_1.DeploymentError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "ProviderError", { enumerable: true, get: function () { return errors_1.ProviderError; } });
+var StateMachine_1 = require("./StateMachine");
+Object.defineProperty(exports, "StateMachine", { enumerable: true, get: function () { return StateMachine_1.StateMachine; } });
+// Runtime removed - not being used, CReact handles all orchestration

package/dist/core/types.d.ts

@@ -0,0 +1,263 @@
+/**
+
+ * 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
+
+ */
+/**
+ * Fiber Node - Intermediate representation of JSX tree
+ * Contains all components (containers + resources) before filtering to CloudDOM
+ */
+export interface FiberNode {
+    /** Component type (function or class) */
+    type: any;
+    /** Props passed to the component */
+    props: Record<string, any>;
+    /** Child Fiber nodes */
+    children: FiberNode[];
+    /** Hierarchical path from root (e.g., ['registry', 'service']) */
+    path: string[];
+    /** CloudDOM nodes attached by useInstance calls (if any) */
+    cloudDOMNodes?: CloudDOMNode[];
+    /** Hooks attached by useState/useEffect calls (if any) */
+    hooks?: any[];
+    /** State attached by useState (if any) */
+    state?: Record<string, any>;
+    /** Key for stable identity (optional) */
+    key?: string | number;
+    /** Reactive state tracking for re-rendering system */
+    reactiveState?: {
+        /** Reason for the last re-render */
+        lastRenderReason?: ReRenderReason;
+        /** Timestamp of the last render */
+        lastRenderTime?: number;
+        /** Total number of times this component has been rendered */
+        renderCount: number;
+        /** Whether this component needs re-rendering */
+        isDirty: boolean;
+        /** Whether this component has a pending update (mark-and-sweep model) */
+        updatePending: boolean;
+        /** Context IDs that triggered the pending update (for debugging) */
+        pendingContexts?: Set<symbol>;
+    };
+    /** Dependency tracking for selective re-rendering */
+    dependencies?: Set<FiberNode>;
+    /** Components that depend on this component */
+    dependents?: Set<FiberNode>;
+    /** Effect bindings for reactive system integration */
+    effectBindings?: Map<number, {
+        boundOutputs: string[];
+        registeredAt: number;
+    }>;
+}
+/**
+ * CloudDOM Event Callbacks - Lifecycle event handlers for resources
+ * These are extracted from component props and triggered during deployment
+ */
+export interface CloudDOMEventCallbacks {
+    /** Called when resource deployment starts */
+    onDeploy?: (context: CloudDOMEventContext) => void | Promise<void>;
+    /** Called when resource deployment fails */
+    onError?: (context: CloudDOMEventContext, error: Error) => void | Promise<void>;
+    /** Called when resource is destroyed/deleted */
+    onDestroy?: (context: CloudDOMEventContext) => void | Promise<void>;
+}
+/**
+ * CloudDOM Event Context - Information passed to event callbacks
+ */
+export interface CloudDOMEventContext {
+    /** Resource ID */
+    resourceId: string;
+    /** Resource path */
+    path: string[];
+    /** Construct type */
+    construct: any;
+    /** Resource props (without event callbacks) */
+    props: Record<string, any>;
+    /** Resource outputs (if available) */
+    outputs?: Record<string, any>;
+    /** Deployment phase */
+    phase: 'deploy' | 'error' | 'destroy';
+    /** Timestamp when event occurred */
+    timestamp: number;
+}
+/**
+ * Event callback props that are automatically available to components using useInstance
+ */
+export interface CloudDOMEventProps {
+    /** Called when resource deployment starts */
+    onDeploy?: (ctx: CloudDOMEventContext) => void | Promise<void>;
+    /** Called when resource deployment fails */
+    onError?: (ctx: CloudDOMEventContext, error: Error) => void | Promise<void>;
+    /** Called when resource is destroyed/deleted */
+    onDestroy?: (ctx: CloudDOMEventContext) => void | Promise<void>;
+}
+/**
+ * Utility type that adds event callback props to any component props
+ * Use this for components that call useInstance
+ */
+export type WithCloudDOMEvents<T = {}> = T & CloudDOMEventProps;
+/**
+ * CloudDOM Node - Represents actual cloud resources
+ * Only includes components that called useInstance
+ */
+export interface CloudDOMNode {
+    /** Unique resource ID (e.g., 'registry.service') */
+    id: string;
+    /** Hierarchical path (e.g., ['registry', 'service']) */
+    path: string[];
+    /** Construct type (e.g., EcrRepository, AppRunnerService) */
+    construct: any;
+    /** Serializable construct type name (e.g., 'EcrRepository', 'AppRunnerService') */
+    constructType: string;
+    /** Props for the construct */
+    props: Record<string, any>;
+    /** Child CloudDOM nodes */
+    children: CloudDOMNode[];
+    /** Infrastructure outputs from cloud provider (e.g., connectionUrl, port, bucketName) */
+    outputs?: Record<string, any>;
+    /** Application state from useState hooks (e.g., { state1: "...", state2: 123 }) */
+    state?: Record<string, any>;
+    /** Event callbacks extracted from component props (optional) */
+    eventCallbacks?: CloudDOMEventCallbacks;
+    /** Internal: Cached shallow hash of props for fast diff (optional) */
+    _propHash?: string;
+}
+/**
+ * JSX Element type
+ */
+export interface JSXElement {
+    type: any;
+    props: any;
+    key?: string | number;
+}
+/**
+ * ChangeSet represents the minimal set of operations to reconcile two CloudDOM states
+ *
+ * REQ-O01: State Machine needs diff to detect changes
+ * REQ-O04: Plan Command needs diff to show preview
+ */
+export interface ChangeSet {
+    /** Nodes that exist in current but not in previous (need to be created) */
+    creates: CloudDOMNode[];
+    /** Nodes that exist in both but have different props (need to be updated) */
+    updates: CloudDOMNode[];
+    /** Nodes that exist in previous but not in current (need to be deleted) */
+    deletes: CloudDOMNode[];
+    /** Nodes that changed type (need to be replaced: delete + create) */
+    replacements: CloudDOMNode[];
+    /** Nodes that moved in the hierarchy (includes node ID for traceability) */
+    moves: Array<{
+        nodeId: string;
+        from: string;
+        to: string;
+    }>;
+    /** Deployment order based on dependency graph (topologically sorted) */
+    deploymentOrder: string[];
+    /** Parallel deployment batches (nodes at same depth can deploy in parallel) */
+    parallelBatches: string[][];
+}
+/**
+ * Get filtered deployment order containing only resources that need deployment
+ * (creates, updates, replacements) - excludes unchanged resources
+ *
+ * @param changeSet - The change set to filter
+ * @returns Array of resource IDs that need deployment, in dependency order
+ */
+export declare function getResourcesToDeploy(changeSet: ChangeSet): string[];
+/**
+ * DependencyGraph represents resource dependencies for deployment ordering
+ *
+ * Maps node ID → array of dependency IDs
+ */
+export interface DependencyGraph {
+    /** Adjacency list: node ID → dependency IDs */
+    dependencies: Map<string, string[]>;
+    /** Reverse adjacency list: node ID → dependent IDs (nodes that depend on this node) */
+    dependents: Map<string, string[]>;
+}
+/**
+ * ReRenderReason - Reasons why a component re-render was triggered
+ * Used for debugging, performance monitoring, and selective re-rendering
+ *
+ * Note: useState changes alone do NOT trigger re-renders in CReact.
+ * Re-renders only occur when provider outputs that are bound to state change.
+ */
+export type ReRenderReason = 'output-update' | 'context-change' | 'structural-change' | 'hot-reload' | 'manual';
+/**
+ * CReactEvents - Lifecycle event hooks for reactive system
+ * Optional interface for tooling, debugging, and performance monitoring
+ */
+export interface CReactEvents {
+    /** Called when a component render starts */
+    onRenderStart(fiber: FiberNode): void;
+    /** Called when a component render completes successfully */
+    onRenderComplete(fiber: FiberNode): void;
+    /** Called when deployment starts for a stack */
+    onDeployStart(stack: string): void;
+    /** Called when deployment completes successfully for a stack */
+    onDeployComplete(stack: string): void;
+    /** Called when an error occurs during rendering or deployment */
+    onError(error: Error, fiber?: FiberNode): void;
+    /** Called when a context value is updated (for observability) */
+    onContextUpdate?(contextId: symbol, previousValue: any, newValue: any): void;
+    /** Called when a fiber is scheduled for re-render (for telemetry/visualization) */
+    onFiberReRenderScheduled?(fiber: FiberNode, reason: ReRenderReason, contextId?: symbol): void;
+    /** Called when structural changes are detected in CloudDOM topology */
+    onStructuralChange?(change: any): void;
+}
+/**
+ * OutputBinding - Tracks binding between component state and provider outputs
+ * Used by StateBindingManager to detect when outputs change
+ */
+export interface OutputBinding {
+    /** CloudDOM node ID that provides the output */
+    nodeId: string;
+    /** Output key from the provider */
+    outputKey: string;
+    /** Last known value of the output */
+    lastValue: any;
+    /** Timestamp when binding was created */
+    bindTime: number;
+    /** Timestamp when binding was last updated (optional, for observability) */
+    lastUpdate?: number;
+}
+/**
+ * OutputChange - Represents a change in provider output
+ * Used to track what changed and which components are affected
+ */
+export interface OutputChange {
+    /** CloudDOM node ID that changed */
+    nodeId: string;
+    /** Output key that changed */
+    outputKey: string;
+    /** Previous value */
+    previousValue: any;
+    /** New value */
+    newValue: any;
+    /** Fiber nodes affected by this change */
+    affectedFibers: FiberNode[];
+}

package/dist/core/types.js

@@ -0,0 +1,48 @@
+"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.getResourcesToDeploy = getResourcesToDeploy;
+/**
+ * Get filtered deployment order containing only resources that need deployment
+ * (creates, updates, replacements) - excludes unchanged resources
+ *
+ * @param changeSet - The change set to filter
+ * @returns Array of resource IDs that need deployment, in dependency order
+ */
+function getResourcesToDeploy(changeSet) {
+    const resourcesToDeploy = new Set([
+        ...changeSet.creates.map(n => n.id),
+        ...changeSet.updates.map(n => n.id),
+        ...changeSet.replacements.map(n => n.id),
+    ]);
+    // Filter deployment order to maintain dependency ordering
+    return changeSet.deploymentOrder.filter(id => resourcesToDeploy.has(id));
+}

package/dist/hooks/context.d.ts

@@ -0,0 +1,147 @@
+/**
+
+ * 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 } from '../core/types';
+/**
+ * Access tracking session for output dependency analysis
+ */
+interface AccessTrackingSession {
+    fiber: FiberNode;
+    startTime: number;
+    trackedOutputs: Set<string>;
+    isActive: boolean;
+}
+/**
+ * Consolidated Hook Context - Single source of truth for all hook state
+ * Addresses Issue #9: Hook Context Consolidation
+ */
+interface ConsolidatedHookContext {
+    currentFiber: FiberNode | null;
+    stateHookIndex: number;
+    effectHookIndex: number;
+    contextHookIndex: number;
+    instanceHookIndex: number;
+    contextStacks: Map<symbol, any[]>;
+    currentPath: string[];
+    previousOutputsMap: Map<string, Record<string, any>> | null;
+    accessTrackingSessions: Map<FiberNode, AccessTrackingSession>;
+}
+/**
+ * Get the consolidated hook context with validation
+ * This is the primary function all hooks should use
+ */
+export declare function requireHookContext(): ConsolidatedHookContext;
+/**
+ * Run a function with a new consolidated hook context
+ */
+export declare function runWithHookContext<T>(fn: () => T): T;
+/**
+ * Increment hook index for specific hook type
+ */
+export declare function incrementHookIndex(hookType?: 'state' | 'effect' | 'context' | 'instance'): number;
+/**
+ * Set the current rendering context for all hooks
+ * Called by Renderer before executing a component
+ *
+ * Requirements: 8.2, 8.4
+ */
+export declare function setRenderContext(fiber: FiberNode, path?: string[]): void;
+/**
+ * Clear the current rendering context for all hooks
+ * Called by Renderer after component execution
+ *
+ * Requirements: 8.2, 8.4
+ */
+export declare function clearRenderContext(): void;
+/**
+ * Check if there is an active render context
+ */
+export declare function hasRenderContext(): boolean;
+/**
+ * Get the current fiber state
+ */
+export declare function getCurrentState(): Record<string, any> | undefined;
+/**
+ * Push a context value onto the stack
+ * Called by Renderer when entering a Provider
+ */
+export declare function pushContextValue(contextId: symbol, value: any): void;
+/**
+ * Pop a context value from the stack
+ * Called by Renderer when exiting a Provider
+ */
+export declare function popContextValue(contextId: symbol): void;
+/**
+ * Get the current context value from the stack
+ */
+export declare function getContextValue(contextId: symbol): {
+    hasValue: boolean;
+    value: any;
+};
+/**
+ * Clear all context stacks
+ * Called by Renderer to prevent memory leaks
+ */
+export declare function clearContextStacks(): void;
+/**
+ * Clear the global previous outputs map
+ * Called for test isolation and cleanup
+ */
+export declare function clearPreviousOutputs(): void;
+/**
+ * Set previous outputs map for restoration during render
+ * Called by CReact before rendering
+ */
+export declare function setPreviousOutputs(outputsMap: Map<string, Record<string, any>> | null): void;
+/**
+ * Get the current rendering path
+ */
+export declare function getCurrentPath(): string[];
+/**
+ * Check if currently rendering
+ */
+export declare function isRendering(): boolean;
+/**
+ * Start tracking output accesses for a fiber
+ * Used by useEffect to track which outputs are accessed in dependencies
+ */
+export declare function startAccessTracking(fiber: FiberNode): void;
+/**
+ * End tracking and return the set of accessed outputs
+ */
+export declare function endAccessTracking(fiber: FiberNode): Set<string>;
+/**
+ * Track an output access during an active tracking session
+ */
+export declare function trackOutputAccess(fiber: FiberNode, bindingKey: string): void;
+/**
+ * Get the current access tracking session for a fiber
+ */
+export declare function getAccessTrackingSession(fiber: FiberNode): AccessTrackingSession | undefined;
+export {};