@creact-labs/creact 0.1.0

package/dist/core/RenderScheduler.d.ts

@@ -0,0 +1,153 @@
+/**
+
+ * 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, ReRenderReason, CReactEvents } from './types';
+/**
+ * RenderScheduler - Manages batched re-rendering of components
+ *
+ * Provides:
+ * - Batched re-rendering to avoid excessive renders
+ * - Circular dependency detection
+ * - Performance safeguards and rate limiting
+ * - Event hook integration for tooling
+ */
+export declare class RenderScheduler {
+    private pendingReRenders;
+    private batchTimeout;
+    private eventHooks?;
+    private renderChain;
+    private maxRenderDepth;
+    private rateLimitMap;
+    private maxRendersPerSecond;
+    private errorRecoveryManager;
+    private failedRenders;
+    private maxRetries;
+    private backoffMultiplier;
+    private baseBackoffMs;
+    constructor(eventHooks?: CReactEvents);
+    /**
+     * Schedule a component for re-rendering with mark-and-sweep model
+     * Uses batching to avoid excessive renders and prevents duplicate scheduling
+     */
+    schedule(fiber: FiberNode, reason: ReRenderReason, contextId?: symbol): void;
+    /**
+     * Schedule the next batch of re-renders
+     * Uses setTimeout to batch multiple changes in the same tick
+     */
+    private scheduleBatch;
+    /**
+     * Execute all pending re-renders in a batch with error handling and recovery
+     */
+    private flushBatch;
+    /**
+     * Execute re-renders for the given fibers
+     * Integrates with the Renderer to perform actual re-rendering
+     */
+    private executeReRenders;
+    /**
+     * Detect circular dependencies in the render chain
+     */
+    private detectCircularDependencies;
+    /**
+     * Check if a fiber has circular dependencies using DFS
+     */
+    private hasCycle;
+    /**
+     * Sort fibers by dependency order (dependencies before dependents)
+     */
+    private sortByDependencies;
+    /**
+     * Check if a fiber is rate limited
+     */
+    private isRateLimited;
+    /**
+     * Get pending re-renders (for testing/debugging)
+     */
+    getPendingReRenders(): Set<FiberNode>;
+    /**
+     * Clear all pending re-renders (for testing/cleanup)
+     */
+    clearPending(): void;
+    /**
+     * Set performance limits (for testing/configuration)
+     */
+    setLimits(maxRenderDepth: number, maxRendersPerSecond: number): void;
+    /**
+     * Create snapshots of fiber states for rollback
+     */
+    private createFiberSnapshots;
+    /**
+     * Filter out fibers that have failed too many times
+     */
+    private filterEligibleFibers;
+    /**
+     * Execute re-render for a single fiber
+     */
+    private executeReRender;
+    /**
+     * Record a failure for a fiber
+     */
+    private recordFailure;
+    /**
+     * Clear failure record for a fiber (after successful render)
+     */
+    private clearFailureRecord;
+    /**
+     * Handle partial failures with graceful degradation
+     */
+    private handlePartialFailures;
+    /**
+     * Determine if successful renders should be rolled back due to dependency failures
+     */
+    private shouldRollbackSuccessfulRenders;
+    /**
+     * Rollback specific fibers to their snapshots
+     */
+    private rollbackFibers;
+    /**
+     * Rollback all changes (critical error recovery)
+     */
+    private rollbackAllChanges;
+    /**
+     * Schedule retries for failed renders with exponential backoff
+     */
+    private scheduleRetries;
+    /**
+     * Get failure statistics (for monitoring/debugging)
+     */
+    getFailureStats(): {
+        totalFailures: number;
+        fibersWithFailures: number;
+        averageFailureCount: number;
+    };
+    /**
+     * Clear all failure records (for testing/cleanup)
+     */
+    clearFailureRecords(): void;
+}

package/dist/core/RenderScheduler.js

@@ -0,0 +1,519 @@
+"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.RenderScheduler = void 0;
+const ErrorRecoveryManager_1 = require("./ErrorRecoveryManager");
+const errors_1 = require("./errors");
+const CReact_1 = require("./CReact");
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('renderer');
+/**
+ * RenderScheduler - Manages batched re-rendering of components
+ *
+ * Provides:
+ * - Batched re-rendering to avoid excessive renders
+ * - Circular dependency detection
+ * - Performance safeguards and rate limiting
+ * - Event hook integration for tooling
+ */
+class RenderScheduler {
+    constructor(eventHooks) {
+        this.pendingReRenders = new Set();
+        this.batchTimeout = null;
+        this.renderChain = [];
+        this.maxRenderDepth = 50; // Prevent infinite loops
+        this.rateLimitMap = new Map();
+        this.maxRendersPerSecond = 10;
+        // Error handling and recovery
+        this.failedRenders = new Map();
+        this.maxRetries = 3;
+        this.backoffMultiplier = 2;
+        this.baseBackoffMs = 100;
+        this.eventHooks = eventHooks;
+        this.errorRecoveryManager = new ErrorRecoveryManager_1.ErrorRecoveryManager(eventHooks);
+    }
+    /**
+     * Schedule a component for re-rendering with mark-and-sweep model
+     * Uses batching to avoid excessive renders and prevents duplicate scheduling
+     */
+    schedule(fiber, reason, contextId) {
+        // Rate limiting check
+        if (this.isRateLimited(fiber)) {
+            logger.warn(`Rate limiting re-render for component at path: ${fiber.path.join('.')}`);
+            return;
+        }
+        // Initialize reactive state if needed
+        if (!fiber.reactiveState) {
+            fiber.reactiveState = {
+                renderCount: 0,
+                isDirty: false,
+                updatePending: false,
+            };
+        }
+        // Mark-and-sweep: avoid duplicate scheduling
+        if (fiber.reactiveState.updatePending) {
+            // Update context tracking for debugging
+            if (contextId && reason === 'context-change') {
+                if (!fiber.reactiveState.pendingContexts) {
+                    fiber.reactiveState.pendingContexts = new Set();
+                }
+                fiber.reactiveState.pendingContexts.add(contextId);
+            }
+            return; // Already scheduled, skip duplicate
+        }
+        // Mark as pending update
+        fiber.reactiveState.updatePending = true;
+        fiber.reactiveState.lastRenderReason = reason;
+        fiber.reactiveState.lastRenderTime = Date.now();
+        fiber.reactiveState.isDirty = true;
+        // Track context for debugging
+        if (contextId && reason === 'context-change') {
+            fiber.reactiveState.pendingContexts = new Set([contextId]);
+        }
+        // Emit telemetry hook
+        this.eventHooks?.onFiberReRenderScheduled?.(fiber, reason, contextId);
+        this.pendingReRenders.add(fiber);
+        this.scheduleBatch();
+    }
+    /**
+     * Schedule the next batch of re-renders
+     * Uses setTimeout to batch multiple changes in the same tick
+     */
+    scheduleBatch() {
+        if (this.batchTimeout)
+            return;
+        this.batchTimeout = setTimeout(() => {
+            this.flushBatch();
+        }, 0); // Next tick batching
+    }
+    /**
+     * Execute all pending re-renders in a batch with error handling and recovery
+     */
+    async flushBatch() {
+        const fibers = Array.from(this.pendingReRenders);
+        this.pendingReRenders.clear();
+        this.batchTimeout = null;
+        if (fibers.length === 0)
+            return;
+        // Create snapshots for rollback
+        const fiberSnapshots = this.createFiberSnapshots(fibers);
+        const successfulRenders = [];
+        const failedRenders = [];
+        try {
+            // Detect circular dependencies
+            this.detectCircularDependencies(fibers);
+            // Filter out fibers that have failed too many times
+            const eligibleFibers = this.filterEligibleFibers(fibers);
+            if (eligibleFibers.length === 0) {
+                logger.warn('All fibers filtered out due to repeated failures');
+                return;
+            }
+            // Sort by dependency order (dependents after dependencies)
+            const sortedFibers = this.sortByDependencies(eligibleFibers);
+            // Execute re-renders with individual error isolation
+            for (const fiber of sortedFibers) {
+                try {
+                    // Emit render start event
+                    this.eventHooks?.onRenderStart(fiber);
+                    this.renderChain.push(fiber);
+                    // Execute single fiber re-render
+                    await this.executeReRender(fiber);
+                    // Mark as successful
+                    successfulRenders.push(fiber);
+                    this.clearFailureRecord(fiber);
+                    // Update reactive state
+                    if (fiber.reactiveState) {
+                        fiber.reactiveState.renderCount++;
+                        fiber.reactiveState.isDirty = false;
+                    }
+                    // Emit render complete event
+                    this.eventHooks?.onRenderComplete(fiber);
+                }
+                catch (error) {
+                    // Record failure
+                    this.recordFailure(fiber, error);
+                    failedRenders.push({ fiber, error: error });
+                    // Emit error event
+                    this.eventHooks?.onError(error, fiber);
+                    // Continue with other fibers (error isolation)
+                    logger.warn(`Fiber render failed: ${fiber.path.join('.')}, continuing with others`);
+                }
+            }
+            // Handle partial failures with graceful degradation
+            if (failedRenders.length > 0) {
+                await this.handlePartialFailures(failedRenders, successfulRenders, fiberSnapshots);
+            }
+            // Clear render chain
+            this.renderChain = [];
+        }
+        catch (error) {
+            // Critical error - rollback all changes
+            logger.error('Critical error during batch render, rolling back all changes');
+            await this.rollbackAllChanges(fiberSnapshots);
+            this.eventHooks?.onError(error);
+            throw error;
+        }
+    }
+    /**
+     * Execute re-renders for the given fibers
+     * Integrates with the Renderer to perform actual re-rendering
+     */
+    async executeReRenders(fibers) {
+        if (fibers.length === 0)
+            return;
+        try {
+            // Get the CReact instance to access the renderer
+            const creact = (0, CReact_1.getCReactInstance)();
+            if (!creact) {
+                logger.warn('No CReact instance available for re-rendering');
+                return;
+            }
+            // Use the CReact rerender method to perform actual re-rendering
+            await creact.rerender('default', fibers);
+            // Update render count for successfully rendered fibers
+            for (const fiber of fibers) {
+                if (fiber.reactiveState) {
+                    fiber.reactiveState.renderCount++;
+                    fiber.reactiveState.isDirty = false;
+                }
+            }
+        }
+        catch (error) {
+            logger.error('Failed to execute re-renders:', error);
+            throw error;
+        }
+    }
+    /**
+     * Detect circular dependencies in the render chain
+     */
+    detectCircularDependencies(fibers) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        for (const fiber of fibers) {
+            if (this.hasCycle(fiber, visited, recursionStack)) {
+                const cyclePath = Array.from(recursionStack).map((f) => f.path.join('.'));
+                throw new errors_1.CircularDependencyError(`Circular dependency detected in re-render chain: ${cyclePath.join(' -> ')}`, cyclePath);
+            }
+        }
+        // Check render chain depth
+        if (this.renderChain.length > this.maxRenderDepth) {
+            const chainPath = this.renderChain.map((f) => f.path.join('.')).join(' -> ');
+            throw new Error(`Maximum render depth exceeded (${this.maxRenderDepth}): ${chainPath}`);
+        }
+    }
+    /**
+     * Check if a fiber has circular dependencies using DFS
+     */
+    hasCycle(fiber, visited, recursionStack) {
+        if (recursionStack.has(fiber)) {
+            return true; // Back edge found - cycle detected
+        }
+        if (visited.has(fiber)) {
+            return false; // Already processed
+        }
+        visited.add(fiber);
+        recursionStack.add(fiber);
+        // Check dependencies
+        if (fiber.dependencies) {
+            for (const dependency of Array.from(fiber.dependencies)) {
+                if (this.hasCycle(dependency, visited, recursionStack)) {
+                    return true;
+                }
+            }
+        }
+        recursionStack.delete(fiber);
+        return false;
+    }
+    /**
+     * Sort fibers by dependency order (dependencies before dependents)
+     */
+    sortByDependencies(fibers) {
+        const sorted = [];
+        const visited = new Set();
+        const temp = new Set();
+        const visit = (fiber) => {
+            if (temp.has(fiber)) {
+                throw new Error(`Circular dependency detected during sort: ${fiber.path.join('.')}`);
+            }
+            if (visited.has(fiber)) {
+                return;
+            }
+            temp.add(fiber);
+            // Visit dependencies first
+            if (fiber.dependencies) {
+                for (const dependency of Array.from(fiber.dependencies)) {
+                    if (fibers.includes(dependency)) {
+                        visit(dependency);
+                    }
+                }
+            }
+            temp.delete(fiber);
+            visited.add(fiber);
+            sorted.push(fiber);
+        };
+        for (const fiber of fibers) {
+            if (!visited.has(fiber)) {
+                visit(fiber);
+            }
+        }
+        return sorted;
+    }
+    /**
+     * Check if a fiber is rate limited
+     */
+    isRateLimited(fiber) {
+        const now = Date.now();
+        const lastRenderTime = this.rateLimitMap.get(fiber) || 0;
+        const timeSinceLastRender = now - lastRenderTime;
+        const minInterval = 1000 / this.maxRendersPerSecond; // ms between renders
+        if (timeSinceLastRender < minInterval) {
+            return true;
+        }
+        this.rateLimitMap.set(fiber, now);
+        return false;
+    }
+    /**
+     * Get pending re-renders (for testing/debugging)
+     */
+    getPendingReRenders() {
+        return new Set(this.pendingReRenders);
+    }
+    /**
+     * Clear all pending re-renders (for testing/cleanup)
+     */
+    clearPending() {
+        if (this.batchTimeout) {
+            clearTimeout(this.batchTimeout);
+            this.batchTimeout = null;
+        }
+        this.pendingReRenders.clear();
+        this.renderChain = [];
+        // Clear updatePending flags from all fibers
+        Array.from(this.pendingReRenders).forEach((fiber) => {
+            if (fiber.reactiveState) {
+                fiber.reactiveState.updatePending = false;
+                fiber.reactiveState.pendingContexts?.clear();
+            }
+        });
+    }
+    /**
+     * Set performance limits (for testing/configuration)
+     */
+    setLimits(maxRenderDepth, maxRendersPerSecond) {
+        this.maxRenderDepth = maxRenderDepth;
+        this.maxRendersPerSecond = maxRendersPerSecond;
+    }
+    // Error Handling and Recovery Methods
+    /**
+     * Create snapshots of fiber states for rollback
+     */
+    createFiberSnapshots(fibers) {
+        const snapshots = new Map();
+        fibers.forEach((fiber) => {
+            snapshots.set(fiber, {
+                hooks: fiber.hooks ? [...fiber.hooks] : undefined,
+                state: fiber.state ? { ...fiber.state } : undefined,
+                reactiveState: fiber.reactiveState ? { ...fiber.reactiveState } : undefined,
+                cloudDOMNodes: fiber.cloudDOMNodes ? [...fiber.cloudDOMNodes] : undefined,
+            });
+        });
+        return snapshots;
+    }
+    /**
+     * Filter out fibers that have failed too many times
+     */
+    filterEligibleFibers(fibers) {
+        const now = Date.now();
+        return fibers.filter((fiber) => {
+            const failureRecord = this.failedRenders.get(fiber);
+            if (!failureRecord) {
+                return true; // Never failed, eligible
+            }
+            if (failureRecord.count >= this.maxRetries) {
+                // Check if enough time has passed for retry with backoff
+                const backoffTime = this.baseBackoffMs * Math.pow(this.backoffMultiplier, failureRecord.count - 1);
+                const timeSinceLastFailure = now - failureRecord.lastFailure;
+                if (timeSinceLastFailure < backoffTime) {
+                    logger.warn(`Fiber ${fiber.path.join('.')} still in backoff period`);
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    /**
+     * Execute re-render for a single fiber
+     */
+    async executeReRender(fiber) {
+        try {
+            // Get the CReact instance to access the renderer
+            const creact = (0, CReact_1.getCReactInstance)();
+            if (!creact) {
+                logger.warn('No CReact instance available for re-rendering');
+                return;
+            }
+            // Note: Previously skipped re-renders during initial build, but now that
+            // CloudDOMBuilder properly handles re-render scenarios, we allow all re-renders
+            // Use selective re-rendering to avoid rebuilding the entire tree
+            const renderer = creact.renderer;
+            if (renderer && renderer.reRenderComponents) {
+                renderer.reRenderComponents([fiber], 'manual');
+            }
+            else {
+                logger.warn('Renderer not available for selective re-rendering');
+            }
+            // Update render count
+            if (fiber.reactiveState) {
+                fiber.reactiveState.renderCount++;
+                fiber.reactiveState.isDirty = false;
+            }
+        }
+        catch (error) {
+            logger.error('Failed to execute re-render for fiber:', fiber.path.join('.'), error);
+            throw error;
+        }
+    }
+    /**
+     * Record a failure for a fiber
+     */
+    recordFailure(fiber, error) {
+        const existing = this.failedRenders.get(fiber);
+        if (existing) {
+            existing.count++;
+            existing.lastFailure = Date.now();
+            existing.error = error;
+        }
+        else {
+            this.failedRenders.set(fiber, {
+                count: 1,
+                lastFailure: Date.now(),
+                error,
+            });
+        }
+    }
+    /**
+     * Clear failure record for a fiber (after successful render)
+     */
+    clearFailureRecord(fiber) {
+        this.failedRenders.delete(fiber);
+    }
+    /**
+     * Handle partial failures with graceful degradation
+     */
+    async handlePartialFailures(failedRenders, successfulRenders, fiberSnapshots) {
+        logger.warn(`Partial failure: ${failedRenders.length} failed, ${successfulRenders.length} succeeded`);
+        // Check if we should rollback successful renders due to dependencies
+        const shouldRollback = this.shouldRollbackSuccessfulRenders(failedRenders, successfulRenders);
+        if (shouldRollback) {
+            logger.warn('Rolling back successful renders due to dependency failures');
+            await this.rollbackFibers(successfulRenders, fiberSnapshots);
+        }
+        else {
+            logger.info('Continuing with partial success (graceful degradation)');
+        }
+        // Schedule retry for failed renders with backoff
+        this.scheduleRetries(failedRenders);
+    }
+    /**
+     * Determine if successful renders should be rolled back due to dependency failures
+     */
+    shouldRollbackSuccessfulRenders(failedRenders, successfulRenders) {
+        // Check if any successful render depends on a failed render
+        for (const successfulFiber of successfulRenders) {
+            if (successfulFiber.dependencies) {
+                const dependencyArray = Array.from(successfulFiber.dependencies);
+                for (const dependency of dependencyArray) {
+                    if (failedRenders.some((failed) => failed.fiber === dependency)) {
+                        return true; // Successful fiber depends on failed fiber
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Rollback specific fibers to their snapshots
+     */
+    async rollbackFibers(fibers, snapshots) {
+        for (const fiber of fibers) {
+            const snapshot = snapshots.get(fiber);
+            if (snapshot) {
+                // Restore fiber state
+                fiber.hooks = snapshot.hooks ? [...snapshot.hooks] : undefined;
+                fiber.state = snapshot.state ? { ...snapshot.state } : undefined;
+                fiber.reactiveState = snapshot.reactiveState ? { ...snapshot.reactiveState } : undefined;
+                fiber.cloudDOMNodes = snapshot.cloudDOMNodes ? [...snapshot.cloudDOMNodes] : undefined;
+            }
+        }
+    }
+    /**
+     * Rollback all changes (critical error recovery)
+     */
+    async rollbackAllChanges(snapshots) {
+        const fibers = Array.from(snapshots.keys());
+        await this.rollbackFibers(fibers, snapshots);
+    }
+    /**
+     * Schedule retries for failed renders with exponential backoff
+     */
+    scheduleRetries(failedRenders) {
+        for (const { fiber } of failedRenders) {
+            const failureRecord = this.failedRenders.get(fiber);
+            if (failureRecord && failureRecord.count < this.maxRetries) {
+                const backoffTime = this.baseBackoffMs * Math.pow(this.backoffMultiplier, failureRecord.count);
+                setTimeout(() => {
+                    logger.info(`Retrying failed render for ${fiber.path.join('.')}`);
+                    this.schedule(fiber, 'manual'); // Retry with manual reason
+                }, backoffTime);
+            }
+        }
+    }
+    /**
+     * Get failure statistics (for monitoring/debugging)
+     */
+    getFailureStats() {
+        const totalFailures = Array.from(this.failedRenders.values()).reduce((sum, record) => sum + record.count, 0);
+        const fibersWithFailures = this.failedRenders.size;
+        const averageFailureCount = fibersWithFailures > 0 ? totalFailures / fibersWithFailures : 0;
+        return {
+            totalFailures,
+            fibersWithFailures,
+            averageFailureCount,
+        };
+    }
+    /**
+     * Clear all failure records (for testing/cleanup)
+     */
+    clearFailureRecords() {
+        this.failedRenders.clear();
+    }
+}
+exports.RenderScheduler = RenderScheduler;