bunsane 0.3.2 → 0.4.0

package/core/SchedulerManager.ts

@@ -19,20 +19,25 @@ import type { ComponentTargetConfig } from "./EntityHookManager";
 import ArcheType from "./ArcheType";
 import { BaseComponent } from "./components";
 import { DistributedLock, type DistributedLockConfig } from "./scheduler/DistributedLock";
+import { scheduleTask, scheduleJob } from "./scheduler/cronEvaluator";
+import { executeTask, doExecuteTask, updateTaskMetrics } from "./scheduler/taskRunner";
+import { getDistributedLockInfo, isDistributedLockingEnabled, syncLockConfig } from "./scheduler/lockCoordinator";
+import { initializeLifecycleIntegration, disposeLifecycleIntegration as _disposeLifecycleIntegration } from "./scheduler/lifecycleHooks";
+import { getMetrics, getTaskMetrics, getAllTaskMetrics } from "./scheduler/metrics";
 
 const loggerInstance = logger.child({ scope: "SchedulerManager" });
 
 export class SchedulerManager {
     private static instance: SchedulerManager;
-    private tasks: Map<string, ScheduledTaskInfo> = new Map();
-    private intervals: Map<string, NodeJS.Timeout> = new Map();
-    private isRunning: boolean = false;
+    public tasks: Map<string, ScheduledTaskInfo> = new Map();
+    public intervals: Map<string, NodeJS.Timeout> = new Map();
+    public isRunning: boolean = false;
     private eventListeners: SchedulerEventCallback[] = [];
     public config: SchedulerConfig;
-    private distributedLock: DistributedLock;
-    private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
-    private inflightTasks: Set<Promise<any>> = new Set();
-    private metrics: SchedulerMetrics = {
+    public distributedLock: DistributedLock;
+    public phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
+    public inflightTasks: Set<Promise<any>> = new Set();
+    public metrics: SchedulerMetrics = {
         totalTasks: 0,
         runningTasks: 0,
         completedExecutions: 0,
@@ -67,7 +72,7 @@ export class SchedulerManager {
             retryInterval: this.config.lockRetryInterval ?? 100,
         });
 
-        this.initializeLifecycleIntegration();
+        initializeLifecycleIntegration(this);
     }
 
     public static getInstance(): SchedulerManager {
@@ -77,23 +82,8 @@ export class SchedulerManager {
         return SchedulerManager.instance;
     }
 
-    private initializeLifecycleIntegration(): void {
-        this.phaseListener = (event) => {
-            const phase = event.detail;
-            if (phase === ApplicationPhase.APPLICATION_READY) {
-                if (this.config.runOnStart) {
-                    this.start();
-                }
-            }
-        };
-        ApplicationLifecycle.addPhaseListener(this.phaseListener);
-    }
-
     public disposeLifecycleIntegration(): void {
-        if (this.phaseListener) {
-            ApplicationLifecycle.removePhaseListener(this.phaseListener);
-            this.phaseListener = null;
-        }
+        _disposeLifecycleIntegration(this);
     }
 
     public registerTask(taskInfo: ScheduledTaskInfo): void {
@@ -128,7 +118,7 @@ export class SchedulerManager {
 
         // Try to schedule the task - if scheduling fails, don't register it
         try {
-            this.scheduleTask(taskInfo);
+            scheduleTask(this, taskInfo);
             this.tasks.set(taskInfo.id, taskInfo);
             this.metrics.totalTasks++;
 
@@ -154,341 +144,15 @@ export class SchedulerManager {
      * entity-component system integration.
      */
     public scheduleJob(name: string, cronExpression: string, callback: () => Promise<void> | void): { cancel: () => void } {
-        const jobId = `job_${name}_${Date.now()}`;
-
-        // Validate cron expression
-        const validation = CronParser.validate(cronExpression);
-        if (!validation.isValid) {
-            throw new Error(`Invalid cron expression for job "${name}": ${validation.error}`);
-        }
-
-        let timeoutId: ReturnType<typeof setTimeout> | null = null;
-        let cancelled = false;
-
-        const scheduleNextExecution = () => {
-            if (cancelled) return;
-
-            const nextExecution = CronParser.getNextExecution(validation.fields!, new Date());
-            if (!nextExecution) {
-                loggerInstance.warn(`Unable to calculate next execution for job "${name}"`);
-                return;
-            }
-
-            const delay = nextExecution.getTime() - Date.now();
-            timeoutId = setTimeout(async () => {
-                if (cancelled) return;
-                try {
-                    await callback();
-                } catch (error) {
-                    loggerInstance.error(`Job "${name}" failed: ${error instanceof Error ? error.message : String(error)}`);
-                }
-                scheduleNextExecution();
-            }, delay);
-
-            this.intervals.set(jobId, timeoutId as any);
-        };
-
-        scheduleNextExecution();
-
-        return {
-            cancel: () => {
-                cancelled = true;
-                if (timeoutId) {
-                    clearTimeout(timeoutId);
-                    this.intervals.delete(jobId);
-                }
-            }
-        };
-    }
-
-    private scheduleTask(taskInfo: ScheduledTaskInfo): void {
-        try {
-            if (taskInfo.interval === ScheduleInterval.CRON) {
-                this.scheduleCronTask(taskInfo);
-            } else {
-                this.scheduleIntervalTask(taskInfo);
-            }
-        } catch (error) {
-            loggerInstance.error(`Failed to schedule task ${taskInfo.name}: ${error instanceof Error ? error.message : String(error)}`);
-            throw error;
-        }
-    }
-
-    private scheduleIntervalTask(taskInfo: ScheduledTaskInfo): void {
-        const intervalMs = this.getIntervalMilliseconds(taskInfo.interval);
-
-        // Clear any existing interval for this task before creating a new one
-        const existingInterval = this.intervals.get(taskInfo.id);
-        if (existingInterval) {
-            clearInterval(existingInterval);
-            this.intervals.delete(taskInfo.id);
-        }
-
-        // For very long intervals (monthly), use a different approach
-        if (intervalMs > 24 * 60 * 60 * 1000) { // More than 24 hours
-            this.scheduleLongIntervalTask(taskInfo, intervalMs);
-        } else {
-            const intervalId = setInterval(async () => {
-                await this.executeTask(taskInfo.id);
-            }, intervalMs);
-
-            this.intervals.set(taskInfo.id, intervalId);
-            taskInfo.nextExecution = new Date(Date.now() + intervalMs);
-        }
-
-        if (this.config.enableLogging) {
-            loggerInstance.info(`Scheduled task ${taskInfo.name} to run every ${intervalMs}ms`);
-        }
-    }
-
-    private scheduleLongIntervalTask(taskInfo: ScheduledTaskInfo, intervalMs: number): void {
-        // For very long intervals, use a shorter check interval to avoid timeout overflow
-        const checkInterval = Math.min(intervalMs, 24 * 60 * 60 * 1000); // Max 24 hours check interval
-        const nextExecution = new Date(Date.now() + intervalMs);
-        taskInfo.nextExecution = nextExecution;
-
-        const intervalId = setInterval(async () => {
-            const now = Date.now();
-            if (now >= nextExecution.getTime()) {
-                await this.executeTask(taskInfo.id);
-                // Reschedule for next execution
-                taskInfo.nextExecution = new Date(now + intervalMs);
-            }
-        }, checkInterval);
-
-        this.intervals.set(taskInfo.id, intervalId);
-    }
-
-    private scheduleCronTask(taskInfo: ScheduledTaskInfo): void {
-        if (!taskInfo.cronExpression) {
-            throw new Error(`Cron expression is required for CRON interval tasks`);
-        }
-
-        // Validate cron expression
-        const validation = CronParser.validate(taskInfo.cronExpression);
-        if (!validation.isValid) {
-            throw new Error(`Invalid cron expression: ${validation.error}`);
-        }
-
-        // Calculate next execution time
-        const nextExecution = CronParser.getNextExecution(validation.fields!, new Date());
-        if (!nextExecution) {
-            throw new Error(`Unable to calculate next execution time for cron expression: ${taskInfo.cronExpression}`);
-        }
-
-        taskInfo.nextExecution = nextExecution;
-
-        // Clear any existing timeout for this task before creating a new one
-        const existingTimeout = this.intervals.get(taskInfo.id);
-        if (existingTimeout) {
-            clearTimeout(existingTimeout as any);
-        }
-
-        // Schedule the task to run at the calculated time
-        const timeoutId = setTimeout(async () => {
-            await this.executeTask(taskInfo.id);
-            // Reschedule for next execution
-            this.scheduleCronTask(taskInfo);
-        }, nextExecution.getTime() - Date.now());
-
-        this.intervals.set(taskInfo.id, timeoutId as any);
-
-        if (this.config.enableLogging) {
-            loggerInstance.info(`Scheduled cron task ${taskInfo.name} to run at ${nextExecution.toISOString()}`);
-        }
-    }
-
-    private getIntervalMilliseconds(interval: ScheduleInterval): number {
-        switch (interval) {
-            case ScheduleInterval.MINUTE:
-                return 60 * 1000; // 1 minute
-            case ScheduleInterval.HOUR:
-                return 60 * 60 * 1000; // 1 hour
-            case ScheduleInterval.DAILY:
-                return 24 * 60 * 60 * 1000; // 24 hours
-            case ScheduleInterval.WEEKLY:
-                return 7 * 24 * 60 * 60 * 1000; // 7 days
-            case ScheduleInterval.MONTHLY:
-                return 30 * 24 * 60 * 60 * 1000; // 30 days (approximate)
-            default:
-                throw new Error(`Unsupported interval: ${interval}`);
-        }
+        return scheduleJob(this, name, cronExpression, callback);
     }
 
     private async executeTask(taskId: string): Promise<void> {
-        // Track this execution so stop() can await in-flight work before
-        // resources (DB pool, cache) are torn down. Without this, a task mid-
-        // write during SIGTERM hits a closed DB pool and silently corrupts
-        // or loses data.
-        const p = this.doExecuteTask(taskId);
-        this.inflightTasks.add(p);
-        p.finally(() => this.inflightTasks.delete(p));
-        return p;
+        return executeTask(this, taskId);
     }
 
     private async doExecuteTask(taskId: string): Promise<void> {
-        const taskInfo = this.tasks.get(taskId);
-        if (!taskInfo || !taskInfo.enabled) {
-            return;
-        }
-
-        // Skip if the previous tick is still executing. Without this guard
-        // a slow task with interval < execution-time burns a lock-acquire
-        // round-trip every tick and floods the skipped-executions metric
-        // (H-SCHED-1). Cheap in-process check before reaching out to PG.
-        if (taskInfo.isRunning) {
-            this.metrics.skippedExecutions++;
-            if (this.config.enableLogging) {
-                loggerInstance.debug(`Task ${taskInfo.name} skipped - previous execution still running`);
-            }
-            return;
-        }
-
-        if (this.metrics.runningTasks >= this.config.maxConcurrentTasks) {
-            if (this.config.enableLogging) {
-                loggerInstance.warn(`Maximum concurrent tasks reached. Skipping execution of ${taskInfo.name}`);
-            }
-            return;
-        }
-
-        // Try to acquire distributed lock before executing
-        this.metrics.lockAttempts++;
-        const lockResult = await this.distributedLock.tryAcquire(taskId);
-
-        if (!lockResult.acquired) {
-            // Another instance is executing this task
-            this.metrics.skippedExecutions++;
-
-            if (this.config.enableLogging) {
-                loggerInstance.debug(`Task ${taskInfo.name} skipped - another instance is executing (lock key: ${lockResult.lockKey})`);
-            }
-
-            this.emitEvent({
-                type: 'task.skipped',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: { reason: 'lock_unavailable', lockKey: lockResult.lockKey.toString() }
-            });
-
-            return;
-        }
-
-        // Lock acquired successfully
-        this.metrics.locksAcquired++;
-
-        this.emitEvent({
-            type: 'task.lock.acquired',
-            taskId: taskInfo.id,
-            timestamp: new Date(),
-            data: { lockKey: lockResult.lockKey.toString() }
-        });
-
-        taskInfo.isRunning = true;
-        taskInfo.lastExecution = new Date();
-        this.metrics.runningTasks++;
-
-        const startTime = Date.now();
-        const timeout = taskInfo.options?.timeout || this.config.defaultTimeout;
-
-        try {
-            // Create query based on targeting configuration
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let query: Query<any> | null = null;
-
-            if (taskInfo.options?.query) {
-                // Use custom query function (preferred approach)
-                query = taskInfo.options.query();
-            } else if (taskInfo.options?.componentTarget) {
-                // Use component targeting configuration (deprecated - use query instead)
-                const componentTarget = taskInfo.options.componentTarget;
-                query = this.buildQueryFromComponentTarget(componentTarget);
-            } else if (taskInfo.componentTarget) {
-                // Use legacy single component targeting (deprecated - use query instead)
-                query = new Query().with(taskInfo.componentTarget);
-            }
-            // else: time-based task — no entity selection. Handler invoked
-            // with no arguments on each tick.
-
-            // Apply entity limit if specified (can be used with query function)
-            if (query && taskInfo.options?.maxEntitiesPerExecution) {
-                query.take(taskInfo.options.maxEntitiesPerExecution);
-            }
-
-            const entities = query ? await query.exec() : [];
-
-            // Execute the scheduled method with the entities array
-            const method = taskInfo.service[taskInfo.methodName];
-            if (typeof method !== 'function') {
-                throw new Error(`Method ${taskInfo.methodName} not found on service`);
-            }
-
-            // Execute with timeout. Time-based tasks receive no entity arg.
-            const result = await this.executeWithTimeout(
-                query
-                    ? method.call(taskInfo.service, entities)
-                    : method.call(taskInfo.service),
-                timeout,
-                taskInfo
-            );
-
-            const duration = Date.now() - startTime;
-            taskInfo.executionCount++;
-            this.metrics.completedExecutions++;
-            this.metrics.totalExecutionTime += duration;
-            this.metrics.averageExecutionTime = this.metrics.totalExecutionTime / this.metrics.completedExecutions;
-
-            // Update task-specific metrics
-            this.updateTaskMetrics(taskInfo.id, {
-                totalExecutions: taskInfo.executionCount,
-                successfulExecutions: (this.metrics.taskMetrics[taskInfo.id]?.successfulExecutions || 0) + 1,
-                averageExecutionTime: duration,
-                lastExecutionTime: new Date(),
-                totalEntitiesProcessed: entities.length
-            });
-
-            if (this.config.enableLogging) {
-                loggerInstance.info(`Task ${taskInfo.name} completed successfully in ${duration}ms (processed ${entities.length} entities)`);
-            }
-
-            this.emitEvent({
-                type: 'task.executed',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: { duration, entitiesProcessed: entities.length, success: true }
-            });
-
-        } catch (error) {
-            const duration = Date.now() - startTime;
-            this.metrics.failedExecutions++;
-
-            // Handle retry logic
-            await this.handleTaskFailure(taskInfo, error instanceof Error ? error : new Error(String(error)), duration);
-
-            if (this.config.enableLogging) {
-                loggerInstance.error(`Task ${taskInfo.name} failed after ${duration}ms: ${error instanceof Error ? error.message : String(error)}`);
-            }
-
-            this.emitEvent({
-                type: 'task.failed',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: { duration, error: error instanceof Error ? error.message : String(error) }
-            });
-
-        } finally {
-            taskInfo.isRunning = false;
-            this.metrics.runningTasks--;
-
-            // Release the distributed lock
-            await this.distributedLock.release(taskId);
-
-            this.emitEvent({
-                type: 'task.lock.released',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: { lockKey: lockResult.lockKey.toString() }
-            });
-        }
+        return doExecuteTask(this, taskId);
     }
 
     public start(): void {
@@ -510,7 +174,7 @@ export class SchedulerManager {
 
         // Schedule all registered tasks in priority order
         for (const taskInfo of sortedTasks) {
-            this.scheduleTask(taskInfo);
+            scheduleTask(this, taskInfo);
         }
 
         const lockStatus = this.config.distributedLocking !== false ? 'enabled' : 'disabled';
@@ -577,7 +241,7 @@ export class SchedulerManager {
     }
 
     public getMetrics(): SchedulerMetrics {
-        return { ...this.metrics };
+        return getMetrics(this);
     }
 
     public getTasks(): ScheduledTaskInfo[] {
@@ -592,7 +256,7 @@ export class SchedulerManager {
 
         task.enabled = true;
         if (this.isRunning) {
-            this.scheduleTask(task);
+            scheduleTask(this, task);
         }
         return true;
     }
@@ -624,7 +288,7 @@ export class SchedulerManager {
         }
     }
 
-    private emitEvent(event: SchedulerEvent): void {
+    public emitEvent(event: SchedulerEvent): void {
         for (const listener of this.eventListeners) {
             try {
                 listener(event);
@@ -638,12 +302,7 @@ export class SchedulerManager {
         this.config = { ...this.config, ...config };
 
         // Sync distributed lock configuration
-        this.distributedLock.updateConfig({
-            enabled: this.config.distributedLocking ?? true,
-            enableLogging: this.config.enableLogging,
-            lockTimeout: this.config.lockTimeout ?? 0,
-            retryInterval: this.config.lockRetryInterval ?? 100,
-        });
+        syncLockConfig(this);
 
         if (this.config.enableLogging) {
             loggerInstance.info(`Scheduler configuration updated: ${JSON.stringify(config)}`);
@@ -662,187 +321,28 @@ export class SchedulerManager {
         heldLocks: number;
         config: DistributedLockConfig;
     } {
-        return {
-            enabled: this.config.distributedLocking !== false,
-            heldLocks: this.distributedLock.getHeldLockCount(),
-            config: this.distributedLock.getConfig(),
-        };
+        return getDistributedLockInfo(this);
     }
 
     /**
      * Check if distributed locking is enabled
      */
     public isDistributedLockingEnabled(): boolean {
-        return this.config.distributedLocking !== false;
-    }
-
-    /**
-     * Execute a task with timeout enforcement.
-     *
-     * Note: JS has no way to cancel an arbitrary Promise — on timeout the
-     * wrapper rejects but the underlying task continues. The second .catch
-     * below captures a late rejection after the wrapper already rejected,
-     * preventing an unhandled-rejection process crash (H-SCHED-5). The
-     * `settled` flag guards against double-settle.
-     */
-    private async executeWithTimeout<T>(task: Promise<T>, timeoutMs: number, taskInfo: ScheduledTaskInfo): Promise<T> {
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            const timeoutId = setTimeout(() => {
-                if (settled) return;
-                settled = true;
-                this.metrics.timedOutTasks++;
-                this.updateTaskMetrics(taskInfo.id, {
-                    timeoutCount: (this.metrics.taskMetrics[taskInfo.id]?.timeoutCount || 0) + 1
-                });
-                const error = new Error(`Task ${taskInfo.name} timed out after ${timeoutMs}ms`);
-                this.emitEvent({
-                    type: 'task.timeout',
-                    taskId: taskInfo.id,
-                    timestamp: new Date(),
-                    data: { timeoutMs, taskName: taskInfo.name }
-                });
-                reject(error);
-            }, timeoutMs);
-
-            task
-                .then((result) => {
-                    if (settled) return;
-                    settled = true;
-                    clearTimeout(timeoutId);
-                    resolve(result);
-                })
-                .catch((error) => {
-                    if (settled) {
-                        // Late rejection after timeout. Log only — the wrapper
-                        // promise is already settled, so re-rejecting would be
-                        // a no-op but the rejection would escape as unhandled.
-                        loggerInstance.warn({ taskId: taskInfo.id, err: error }, 'Late rejection from scheduled task after timeout');
-                        return;
-                    }
-                    settled = true;
-                    clearTimeout(timeoutId);
-                    reject(error);
-                });
-        });
-    }
-
-    /**
-     * Handle task failure with retry logic
-     */
-    private async handleTaskFailure(taskInfo: ScheduledTaskInfo, error: Error, duration: number): Promise<void> {
-        taskInfo.lastError = error.message;
-
-        const maxRetries = taskInfo.options?.maxRetries || taskInfo.maxRetries || 0;
-        const retryDelay = taskInfo.options?.retryDelay || 1000; // Default 1 second
-
-        if (taskInfo.retryCount === undefined) {
-            taskInfo.retryCount = 0;
-        }
-
-        if (taskInfo.retryCount < maxRetries) {
-            taskInfo.retryCount++;
-            this.metrics.retriedTasks++;
-
-            this.updateTaskMetrics(taskInfo.id, {
-                retryCount: taskInfo.retryCount
-            });
-
-            if (this.config.enableLogging) {
-                loggerInstance.warn(`Task ${taskInfo.name} failed (attempt ${taskInfo.retryCount}/${maxRetries}), retrying in ${retryDelay}ms: ${error.message}`);
-            }
-
-            // Schedule retry. Track the timer handle in `intervals` under a
-            // unique key so `stop()` can clear it (H-SCHED-3); without this
-            // the retry fires post-shutdown against a closed DB pool. Also
-            // skip the retry if the scheduler is no longer running by the
-            // time the timer fires, and rely on the new isRunning guard in
-            // doExecuteTask (H-SCHED-1) to prevent retry/tick overlap.
-            const retryKey = `${taskInfo.id}:retry:${taskInfo.retryCount}`;
-            const retryHandle = setTimeout(async () => {
-                this.intervals.delete(retryKey);
-                if (!this.isRunning) return;
-                await this.executeTask(taskInfo.id);
-            }, retryDelay);
-            this.intervals.set(retryKey, retryHandle as any);
-
-            this.emitEvent({
-                type: 'task.retry',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: {
-                    attempt: taskInfo.retryCount,
-                    maxRetries,
-                    retryDelay,
-                    error: error.message
-                }
-            });
-        } else {
-            // Max retries reached or no retries configured
-            this.updateTaskMetrics(taskInfo.id, {
-                failedExecutions: (this.metrics.taskMetrics[taskInfo.id]?.failedExecutions || 0) + 1
-            });
-
-            if (this.config.enableLogging) {
-                loggerInstance.error(`Task ${taskInfo.name} failed permanently after ${taskInfo.retryCount} attempts: ${error.message}`);
-            }
-
-            this.emitEvent({
-                type: 'task.failed',
-                taskId: taskInfo.id,
-                timestamp: new Date(),
-                data: {
-                    duration,
-                    error: error.message,
-                    attempts: taskInfo.retryCount,
-                    maxRetries
-                }
-            });
-        }
-    }
-
-    /**
-     * Update task-specific metrics
-     */
-    private updateTaskMetrics(taskId: string, updates: Partial<TaskMetrics>): void {
-        if (!this.metrics.taskMetrics[taskId]) {
-            const taskInfo = this.tasks.get(taskId);
-            this.metrics.taskMetrics[taskId] = {
-                taskId,
-                taskName: taskInfo?.name || 'Unknown',
-                totalExecutions: 0,
-                successfulExecutions: 0,
-                failedExecutions: 0,
-                averageExecutionTime: 0,
-                totalEntitiesProcessed: 0,
-                retryCount: 0,
-                timeoutCount: 0
-            };
-        }
-
-        const metrics = this.metrics.taskMetrics[taskId];
-        Object.assign(metrics, updates);
-
-        // Update rolling averages
-        if (updates.averageExecutionTime !== undefined) {
-            const currentAvg = metrics.averageExecutionTime;
-            const newCount = metrics.totalExecutions;
-            metrics.averageExecutionTime = ((currentAvg * (newCount - 1)) + updates.averageExecutionTime) / newCount;
-        }
+        return isDistributedLockingEnabled(this);
     }
 
     /**
      * Get detailed metrics for a specific task
      */
     public getTaskMetrics(taskId: string): TaskMetrics | null {
-        return this.metrics.taskMetrics[taskId] || null;
+        return getTaskMetrics(this, taskId);
     }
 
     /**
      * Get all task metrics
      */
     public getAllTaskMetrics(): Record<string, TaskMetrics> {
-        return { ...this.metrics.taskMetrics };
+        return getAllTaskMetrics(this);
     }
 
     /**
@@ -858,76 +358,4 @@ export class SchedulerManager {
         await this.executeTask(taskId);
         return true;
     }
-
-    /**
-     * Build a Query object from ComponentTargetConfig
-     * @param componentTarget The component targeting configuration
-     * @returns A Query object configured with the component targeting
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    private buildQueryFromComponentTarget(componentTarget: ComponentTargetConfig): Query<any> {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        let query: Query<any> = new Query();
-
-        // Handle archetype matching first (most specific)
-        if (componentTarget.archetype) {
-            // For archetype matching, we need to include all components from the archetype
-            const archetypeComponents = this.getArchetypeComponents(componentTarget.archetype);
-            for (const component of archetypeComponents) {
-                query = query.with(component);
-            }
-        } else if (componentTarget.archetypes && componentTarget.archetypes.length > 0) {
-            // Handle multiple archetypes - for simplicity, we'll use the first valid one
-            // In a more advanced implementation, you might want to handle OR logic
-            const firstArchetype = componentTarget.archetypes.find(archetype => archetype !== undefined);
-            if (firstArchetype) {
-                const archetypeComponents = this.getArchetypeComponents(firstArchetype);
-                for (const component of archetypeComponents) {
-                    query = query.with(component);
-                }
-            }
-        }
-
-        // Handle included components
-        if (componentTarget.includeComponents && componentTarget.includeComponents.length > 0) {
-            const requireAll = componentTarget.requireAllIncluded ?? true;
-            if (requireAll) {
-                // ALL included components must be present (AND logic)
-                for (const component of componentTarget.includeComponents) {
-                    query = query.with(component);
-                }
-            } else {
-                // ANY included component must be present (OR logic)
-                // For OR logic with Query API, we need to use a different approach
-                // This is a simplified implementation - in practice, you might need custom query logic
-                for (const component of componentTarget.includeComponents) {
-                    query = query.with(component);
-                    break; // Just use the first one for simplicity
-                }
-            }
-        }
-
-        // Handle excluded components
-        if (componentTarget.excludeComponents && componentTarget.excludeComponents.length > 0) {
-            for(const component of componentTarget.excludeComponents){
-                query = query.without(component);
-            }
-        }
-
-        return query;
-    }
-
-    /**
-     * Extract component classes from an ArcheType
-     * @param archetype The archetype to extract components from
-     * @returns Array of component classes
-     */
-    private getArchetypeComponents(archetype: ArcheType): (new () => BaseComponent)[] {
-        // Access the private componentMap from ArcheType
-        const componentMap = (archetype as any).componentMap as Record<string, new () => BaseComponent>;
-        if (!componentMap) {
-            return [];
-        }
-        return Object.values(componentMap);
-    }
-}
+}