@creact-labs/creact 0.1.0

package/dist/core/ProviderOutputTracker.js

@@ -0,0 +1,476 @@
+"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.ProviderOutputTracker = void 0;
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('hooks');
+/**
+ * ProviderOutputTracker - Tracks useInstance calls and their output dependencies
+ *
+ * Key Features:
+ * - Track which components use which provider instances
+ * - Detect when provider outputs change
+ * - Notify bound components of output changes
+ * - Event hook integration for tooling and debugging
+ * - REQ-6.2, 6.3, 6.4: Track output reads for automatic binding creation
+ */
+class ProviderOutputTracker {
+    constructor(eventHooks) {
+        this.instanceBindings = new Map();
+        this.instanceOutputs = new Map();
+        // REQ-6.2, 6.3: Access tracking sessions for dependency analysis
+        this.activeSessions = new Map();
+        this.eventHooks = eventHooks;
+    }
+    /**
+     * Track a useInstance call - bind a fiber to a CloudDOM node
+     * This is called whenever useInstance is called in a component
+     */
+    trackInstance(node, fiber) {
+        // Initialize bindings for this instance if not exists
+        if (!this.instanceBindings.has(node.id)) {
+            this.instanceBindings.set(node.id, new Set());
+        }
+        // Add the fiber to the bindings
+        this.instanceBindings.get(node.id).add(fiber);
+        // Store initial outputs if available
+        if (node.outputs) {
+            this.instanceOutputs.set(node.id, { ...node.outputs });
+        }
+    }
+    /**
+     * Get all fibers bound to a specific instance
+     */
+    getBindingsForInstance(nodeId) {
+        return this.instanceBindings.get(nodeId) || new Set();
+    }
+    /**
+     * Update outputs for an instance and detect changes
+     * Returns array of output changes that occurred
+     */
+    updateInstanceOutputs(nodeId, newOutputs) {
+        const previousOutputs = this.instanceOutputs.get(nodeId) || {};
+        const changes = [];
+        const boundFibers = Array.from(this.getBindingsForInstance(nodeId));
+        // Check for changed outputs
+        for (const [outputKey, newValue] of Object.entries(newOutputs)) {
+            const previousValue = previousOutputs[outputKey];
+            if (previousValue !== newValue) {
+                changes.push({
+                    nodeId,
+                    outputKey,
+                    previousValue,
+                    newValue,
+                    affectedFibers: boundFibers,
+                });
+            }
+        }
+        // Check for removed outputs
+        for (const [outputKey, previousValue] of Object.entries(previousOutputs)) {
+            if (!(outputKey in newOutputs)) {
+                changes.push({
+                    nodeId,
+                    outputKey,
+                    previousValue,
+                    newValue: undefined,
+                    affectedFibers: boundFibers,
+                });
+            }
+        }
+        // Update stored outputs
+        this.instanceOutputs.set(nodeId, { ...newOutputs });
+        return changes;
+    }
+    /**
+     * Notify bound components of output changes
+     * This triggers re-renders for affected components
+     */
+    notifyOutputChanges(changes) {
+        for (const change of changes) {
+            const boundFibers = this.getBindingsForInstance(change.nodeId);
+            for (const fiber of boundFibers) {
+                try {
+                    // Emit render start event for tooling
+                    this.eventHooks?.onRenderStart(fiber);
+                    // Mark fiber as needing re-render due to output change
+                    if (!fiber.reactiveState) {
+                        fiber.reactiveState = {
+                            renderCount: 0,
+                            isDirty: true,
+                            updatePending: true,
+                            lastRenderReason: 'output-update',
+                            lastRenderTime: Date.now(),
+                        };
+                    }
+                    else {
+                        fiber.reactiveState.lastRenderReason = 'output-update';
+                        fiber.reactiveState.lastRenderTime = Date.now();
+                        fiber.reactiveState.isDirty = true;
+                        fiber.reactiveState.updatePending = true;
+                    }
+                }
+                catch (error) {
+                    this.eventHooks?.onError(error, fiber);
+                }
+            }
+        }
+    }
+    /**
+     * Process a batch of CloudDOM nodes and detect all output changes
+     * This is typically called after deployment completes
+     */
+    processCloudDOMOutputs(nodes) {
+        const allChanges = [];
+        for (const node of nodes) {
+            if (node.outputs) {
+                const changes = this.updateInstanceOutputs(node.id, node.outputs);
+                allChanges.push(...changes);
+            }
+            // Process child nodes recursively
+            if (node.children && node.children.length > 0) {
+                const childChanges = this.processCloudDOMOutputs(node.children);
+                allChanges.push(...childChanges);
+            }
+        }
+        return allChanges;
+    }
+    /**
+     * Remove bindings for a specific fiber (cleanup)
+     */
+    removeBindingsForFiber(fiber) {
+        for (const [nodeId, bindings] of this.instanceBindings) {
+            bindings.delete(fiber);
+            // Clean up empty binding sets
+            if (bindings.size === 0) {
+                this.instanceBindings.delete(nodeId);
+                this.instanceOutputs.delete(nodeId);
+            }
+        }
+    }
+    /**
+     * Remove bindings for a specific instance (when resource is deleted)
+     */
+    removeBindingsForInstance(nodeId) {
+        this.instanceBindings.delete(nodeId);
+        this.instanceOutputs.delete(nodeId);
+    }
+    /**
+     * Validate bindings and remove invalid ones
+     * This should be called periodically to clean up stale bindings
+     */
+    validateBindings(validNodes) {
+        const invalidNodeIds = [];
+        for (const nodeId of this.instanceBindings.keys()) {
+            if (!validNodes.has(nodeId)) {
+                invalidNodeIds.push(nodeId);
+            }
+        }
+        // Remove invalid bindings
+        for (const nodeId of invalidNodeIds) {
+            this.removeBindingsForInstance(nodeId);
+        }
+    }
+    /**
+     * Get current outputs for an instance
+     */
+    getInstanceOutputs(nodeId) {
+        return this.instanceOutputs.get(nodeId);
+    }
+    /**
+     * Check if an instance has any bound components
+     */
+    hasBindings(nodeId) {
+        const bindings = this.instanceBindings.get(nodeId);
+        return bindings ? bindings.size > 0 : false;
+    }
+    /**
+     * Get all tracked instances
+     */
+    getTrackedInstances() {
+        return Array.from(this.instanceBindings.keys());
+    }
+    /**
+     * Get statistics about current bindings
+     */
+    getBindingStats() {
+        let totalBindings = 0;
+        for (const bindings of this.instanceBindings.values()) {
+            totalBindings += bindings.size;
+        }
+        return {
+            totalInstances: this.instanceBindings.size,
+            totalBindings,
+            instancesWithOutputs: this.instanceOutputs.size,
+        };
+    }
+    /**
+     * Get all bindings for debugging/inspection
+     */
+    getAllBindings() {
+        const result = new Map();
+        for (const [nodeId, bindings] of this.instanceBindings) {
+            result.set(nodeId, {
+                fibers: Array.from(bindings),
+                outputs: this.instanceOutputs.get(nodeId),
+            });
+        }
+        return result;
+    }
+    /**
+     * Clear all bindings (for testing/cleanup)
+     */
+    clearAllBindings() {
+        this.instanceBindings.clear();
+        this.instanceOutputs.clear();
+    }
+    /**
+     * Create a snapshot of current state for comparison
+     * Useful for detecting changes between deployments
+     */
+    createSnapshot() {
+        const bindingsSnapshot = new Map();
+        const outputsSnapshot = new Map();
+        // Create bindings snapshot with fiber paths instead of fiber objects
+        for (const [nodeId, fibers] of this.instanceBindings) {
+            bindingsSnapshot.set(nodeId, Array.from(fibers).map((f) => f.path.join('.')));
+        }
+        // Create outputs snapshot
+        for (const [nodeId, outputs] of this.instanceOutputs) {
+            outputsSnapshot.set(nodeId, { ...outputs });
+        }
+        return {
+            bindings: bindingsSnapshot,
+            outputs: outputsSnapshot,
+        };
+    }
+    /**
+     * Compare with a previous snapshot to detect changes
+     */
+    compareWithSnapshot(snapshot) {
+        const bindingChanges = {
+            added: [],
+            removed: [],
+            modified: [],
+        };
+        const outputChanges = [];
+        // Check for binding changes
+        const currentNodeIds = new Set(this.instanceBindings.keys());
+        const snapshotNodeIds = new Set(snapshot.bindings.keys());
+        // Added instances
+        for (const nodeId of currentNodeIds) {
+            if (!snapshotNodeIds.has(nodeId)) {
+                bindingChanges.added.push(nodeId);
+            }
+        }
+        // Removed instances
+        for (const nodeId of snapshotNodeIds) {
+            if (!currentNodeIds.has(nodeId)) {
+                bindingChanges.removed.push(nodeId);
+            }
+        }
+        // Modified instances (binding changes)
+        for (const nodeId of currentNodeIds) {
+            if (snapshotNodeIds.has(nodeId)) {
+                const currentPaths = Array.from(this.instanceBindings.get(nodeId)).map((f) => f.path.join('.'));
+                const snapshotPaths = snapshot.bindings.get(nodeId);
+                if (JSON.stringify(currentPaths.sort()) !== JSON.stringify(snapshotPaths.sort())) {
+                    bindingChanges.modified.push(nodeId);
+                }
+            }
+        }
+        // Check for output changes
+        for (const nodeId of currentNodeIds) {
+            const currentOutputs = this.instanceOutputs.get(nodeId) || {};
+            const snapshotOutputs = snapshot.outputs.get(nodeId) || {};
+            const changes = this.compareOutputs(nodeId, snapshotOutputs, currentOutputs);
+            outputChanges.push(...changes);
+        }
+        return { bindingChanges, outputChanges };
+    }
+    /**
+     * Compare two output objects and return changes
+     */
+    compareOutputs(nodeId, previousOutputs, currentOutputs) {
+        const changes = [];
+        const boundFibers = Array.from(this.getBindingsForInstance(nodeId));
+        // Check for changed/added outputs
+        for (const [outputKey, currentValue] of Object.entries(currentOutputs)) {
+            const previousValue = previousOutputs[outputKey];
+            if (previousValue !== currentValue) {
+                changes.push({
+                    nodeId,
+                    outputKey,
+                    previousValue,
+                    newValue: currentValue,
+                    affectedFibers: boundFibers,
+                });
+            }
+        }
+        // Check for removed outputs
+        for (const [outputKey, previousValue] of Object.entries(previousOutputs)) {
+            if (!(outputKey in currentOutputs)) {
+                changes.push({
+                    nodeId,
+                    outputKey,
+                    previousValue,
+                    newValue: undefined,
+                    affectedFibers: boundFibers,
+                });
+            }
+        }
+        return changes;
+    }
+    /**
+     * Extract output references for automatic state binding
+     * Creates proxy objects that can be used to automatically bind state to outputs
+     */
+    extractOutputReferences(node) {
+        const outputReferences = {};
+        if (!node.outputs) {
+            return outputReferences;
+        }
+        // Create output reference objects for each output
+        for (const [outputKey, value] of Object.entries(node.outputs)) {
+            outputReferences[outputKey] = {
+                __providerOutput: {
+                    nodeId: node.id,
+                    outputKey,
+                    value,
+                },
+                // Also include the actual value for direct access
+                valueOf: () => value,
+                toString: () => String(value),
+                // Make it behave like the actual value in most contexts
+                [Symbol.toPrimitive]: () => value,
+            };
+        }
+        return outputReferences;
+    }
+    /**
+     * Update outputs for a specific node and return changes
+     * This is an alias for updateInstanceOutputs for compatibility
+     */
+    updateNodeOutputs(nodeId, newOutputs) {
+        return this.updateInstanceOutputs(nodeId, newOutputs);
+    }
+    /**
+     * Process output changes and return affected fibers
+     * This is an alias for processCloudDOMOutputs for single node updates
+     */
+    processOutputChanges(changes) {
+        const affectedFibers = new Set();
+        for (const change of changes) {
+            change.affectedFibers.forEach((fiber) => affectedFibers.add(fiber));
+        }
+        // Notify about the changes
+        this.notifyOutputChanges(changes);
+        return affectedFibers;
+    }
+    /**
+     * Get current outputs for a node
+     * This is an alias for getInstanceOutputs for compatibility
+     */
+    getNodeOutputs(nodeId) {
+        return this.getInstanceOutputs(nodeId) || {};
+    }
+    /**
+     * Start an access tracking session for a fiber
+     * REQ-6.2, 6.3: Track which outputs are accessed during execution
+     *
+     * @param fiber - Fiber node to track
+     */
+    startAccessTracking(fiber) {
+        this.activeSessions.set(fiber, {
+            fiber,
+            startTime: Date.now(),
+            trackedOutputs: new Set(),
+            isActive: true,
+        });
+        logger.debug(`Started access tracking for ${fiber.path.join('.')}`);
+    }
+    /**
+     * End an access tracking session and return tracked outputs
+     * REQ-6.3, 6.4: Collect tracked outputs for binding creation
+     *
+     * @param fiber - Fiber node to end tracking for
+     * @returns Set of binding keys that were accessed
+     */
+    endAccessTracking(fiber) {
+        const session = this.activeSessions.get(fiber);
+        if (!session) {
+            return new Set();
+        }
+        session.isActive = false;
+        this.activeSessions.delete(fiber);
+        logger.debug(`Ended access tracking for ${fiber.path.join('.')}, tracked ${session.trackedOutputs.size} outputs`);
+        return session.trackedOutputs;
+    }
+    /**
+     * Track an output read during an active session
+     * REQ-6.2, 6.4: Record when outputs are accessed for binding creation
+     *
+     * @param nodeId - CloudDOM node ID
+     * @param outputKey - Output key that was accessed
+     * @param fiber - Fiber node that accessed the output
+     */
+    trackOutputRead(nodeId, outputKey, fiber) {
+        const session = this.activeSessions.get(fiber);
+        if (session?.isActive) {
+            // Generate binding key for this output
+            const bindingKey = `${nodeId}.${outputKey}`;
+            session.trackedOutputs.add(bindingKey);
+            logger.debug(`Tracked output read: ${bindingKey} by ${fiber.path.join('.')}`);
+        }
+    }
+    /**
+     * Check if a fiber has an active tracking session
+     *
+     * @param fiber - Fiber node to check
+     * @returns True if tracking is active for this fiber
+     */
+    isTrackingActive(fiber) {
+        const session = this.activeSessions.get(fiber);
+        return session?.isActive ?? false;
+    }
+    /**
+     * Get all active tracking sessions (for debugging)
+     */
+    getActiveSessions() {
+        return Array.from(this.activeSessions.values());
+    }
+    /**
+     * Clear all active tracking sessions (for cleanup/testing)
+     */
+    clearActiveSessions() {
+        this.activeSessions.clear();
+    }
+}
+exports.ProviderOutputTracker = ProviderOutputTracker;

package/dist/core/ReactiveUpdateQueue.d.ts

@@ -0,0 +1,76 @@
+/**
+
+ * 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 './types';
+/**
+ * Global queue for tracking fibers that need re-rendering
+ */
+declare class ReactiveUpdateQueue {
+    private dirtyFibers;
+    private isProcessing;
+    /**
+     * Enqueue a fiber for re-rendering due to state change
+     * Uses Set to automatically deduplicate multiple setState calls
+     *
+     * @param fiber - Fiber node that needs re-rendering
+     */
+    enqueue(fiber: FiberNode): void;
+    /**
+     * Flush the queue and return all dirty fibers
+     * Clears the queue after returning
+     *
+     * @returns Array of dirty fibers that need re-rendering
+     */
+    flush(): FiberNode[];
+    /**
+     * Check if a fiber is in the queue
+     *
+     * @param fiber - Fiber to check
+     * @returns True if fiber is queued for re-render
+     */
+    has(fiber: FiberNode): boolean;
+    /**
+     * Get current queue size
+     *
+     * @returns Number of fibers in queue
+     */
+    size(): number;
+    /**
+     * Clear the queue without processing
+     * Used for cleanup or error recovery
+     */
+    clear(): void;
+}
+/**
+ * Get the global reactive update queue
+ *
+ * @returns Global ReactiveUpdateQueue instance
+ */
+export declare function getReactiveUpdateQueue(): ReactiveUpdateQueue;
+export {};

package/dist/core/ReactiveUpdateQueue.js

@@ -0,0 +1,121 @@
+"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.getReactiveUpdateQueue = getReactiveUpdateQueue;
+/**
+ * ReactiveUpdateQueue - Tracks fibers that need re-rendering due to state changes
+ *
+ * This queue handles user-triggered state changes (via useState) separately from
+ * provider-driven output changes. It enables the reactivity phase to detect and
+ * re-render components that have internal state changes.
+ *
+ * REQ-4.4: Fiber dirty tracking for state-driven re-renders
+ */
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('hooks');
+/**
+ * Global queue for tracking fibers that need re-rendering
+ */
+class ReactiveUpdateQueue {
+    constructor() {
+        this.dirtyFibers = new Set();
+        this.isProcessing = false;
+    }
+    /**
+     * Enqueue a fiber for re-rendering due to state change
+     * Uses Set to automatically deduplicate multiple setState calls
+     *
+     * @param fiber - Fiber node that needs re-rendering
+     */
+    enqueue(fiber) {
+        if (this.isProcessing) {
+            // Don't enqueue during processing to avoid infinite loops
+            logger.debug(`Skipping enqueue during processing: ${fiber.path?.join('.')}`);
+            return;
+        }
+        this.dirtyFibers.add(fiber);
+        logger.debug(`Enqueued fiber: ${fiber.path?.join('.')} (queue size: ${this.dirtyFibers.size})`);
+    }
+    /**
+     * Flush the queue and return all dirty fibers
+     * Clears the queue after returning
+     *
+     * @returns Array of dirty fibers that need re-rendering
+     */
+    flush() {
+        if (this.isProcessing) {
+            logger.debug('Already processing, returning empty array');
+            return [];
+        }
+        this.isProcessing = true;
+        const fibers = Array.from(this.dirtyFibers);
+        this.dirtyFibers.clear();
+        this.isProcessing = false;
+        logger.debug(`Flushed ${fibers.length} dirty fibers`);
+        return fibers;
+    }
+    /**
+     * Check if a fiber is in the queue
+     *
+     * @param fiber - Fiber to check
+     * @returns True if fiber is queued for re-render
+     */
+    has(fiber) {
+        return this.dirtyFibers.has(fiber);
+    }
+    /**
+     * Get current queue size
+     *
+     * @returns Number of fibers in queue
+     */
+    size() {
+        return this.dirtyFibers.size;
+    }
+    /**
+     * Clear the queue without processing
+     * Used for cleanup or error recovery
+     */
+    clear() {
+        this.dirtyFibers.clear();
+        this.isProcessing = false;
+        logger.debug('Queue cleared');
+    }
+}
+// Global singleton instance
+const globalQueue = new ReactiveUpdateQueue();
+/**
+ * Get the global reactive update queue
+ *
+ * @returns Global ReactiveUpdateQueue instance
+ */
+function getReactiveUpdateQueue() {
+    return globalQueue;
+}