@morojs/moro 1.6.5 → 1.6.8

package/dist/moro.js

@@ -7,6 +7,7 @@ import { createFrameworkLogger, applyLoggingConfiguration } from './core/logger/
 import { MiddlewareManager } from './core/middleware/index.js';
 import { IntelligentRoutingManager } from './core/routing/app-integration.js';
 import { UnifiedRouter, } from './core/routing/unified-router.js';
+import { PathMatcher } from './core/routing/path-matcher.js';
 import { AppDocumentationManager } from './core/docs/index.js';
 import { EventEmitter } from 'events';
 import cluster from 'cluster';
@@ -16,6 +17,16 @@ import { normalizeValidationError } from './core/validation/schema-interface.js'
 import { initializeConfig } from './core/config/index.js';
 // Runtime System Integration
 import { createRuntimeAdapter } from './core/runtime/index.js';
+// uWebSockets Worker Thread Clustering
+import { UWSWorkerClusterManager } from './core/http/utils/uws-worker-clustering.js';
+import { isMainThread } from 'worker_threads';
+// Job System Integration
+import { JobScheduler, JobHealthChecker, everyInterval, cronSchedule, } from './core/jobs/index.js';
+// Lazy imports for GraphQL to avoid crashes when not installed
+let GraphQLCore;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+let GraphQLSubscriptionManager;
+let setupGraphQLSubscriptions;
 export class Moro extends EventEmitter {
     coreFramework;
     routes = [];
@@ -48,6 +59,14 @@ export class Moro extends EventEmitter {
     middlewareManager;
     // Queued WebSocket registrations (for async adapter detection)
     queuedWebSocketRegistrations = [];
+    // Job scheduling system
+    jobScheduler;
+    jobHealthChecker;
+    jobsStarted = false;
+    // GraphQL system
+    graphqlCore; // Use any to avoid import dependency
+    graphqlSubscriptionManager;
+    graphqlInitPromise;
     constructor(options = {}) {
         super(); // Call EventEmitter constructor
         // Track if user explicitly set logger/logging options
@@ -109,6 +128,33 @@ export class Moro extends EventEmitter {
         }
         // Access enterprise event bus from core framework
         this.eventBus = this.coreFramework.eventBus;
+        // Initialize job scheduler if enabled in config
+        // Default to enabled (true) unless explicitly disabled
+        const jobsEnabled = this.config.jobs?.enabled !== false && options.jobs?.enabled !== false;
+        if (jobsEnabled) {
+            const leaderElectionOptions = this.config.jobs?.leaderElection?.enabled !== false
+                ? {
+                    strategy: this.config.jobs?.leaderElection?.strategy ?? 'file',
+                    lockPath: this.config.jobs?.leaderElection?.lockPath,
+                    lockTimeout: this.config.jobs?.leaderElection?.lockTimeout,
+                    heartbeatInterval: this.config.jobs?.leaderElection?.heartbeatInterval,
+                }
+                : undefined;
+            const jobSchedulerOptions = {
+                maxConcurrentJobs: this.config.jobs?.maxConcurrentJobs,
+                enableLeaderElection: this.config.jobs?.leaderElection?.enabled !== false,
+                leaderElection: leaderElectionOptions,
+                executor: this.config.jobs?.executor,
+                stateManager: this.config.jobs?.stateManager,
+                gracefulShutdownTimeout: this.config.jobs?.gracefulShutdownTimeout,
+            };
+            this.jobScheduler = new JobScheduler(createFrameworkLogger('Jobs'), jobSchedulerOptions);
+            this.jobHealthChecker = new JobHealthChecker(this.jobScheduler, createFrameworkLogger('JobHealth'));
+            this.logger.info('Job scheduler initialized', 'Jobs', {
+                maxConcurrentJobs: jobSchedulerOptions.maxConcurrentJobs,
+                leaderElection: jobSchedulerOptions.enableLeaderElection,
+            });
+        }
         // Setup default middleware if enabled - use config defaults with options override
         this.setupDefaultMiddleware({
             ...this.getDefaultOptionsFromConfig(),
@@ -411,15 +457,16 @@ export class Moro extends EventEmitter {
             throw new Error('Port not specified and not found in configuration. Please provide a port number or configure it in moro.config.js/ts');
         }
         // Check if clustering is enabled for massive performance gains
-        // NOTE: uWebSockets.js does NOT support Node.js clustering - it's single-threaded only
         const usingUWebSockets = this.config.server?.useUWebSockets || false;
         if (this.config.performance?.clustering?.enabled) {
             if (usingUWebSockets) {
-                this.logger.warn('Clustering is not supported with uWebSockets.js - running in single-threaded mode. ' +
-                    'uWebSockets is so fast that single-threaded performance often exceeds multi-threaded Node.js!', 'Cluster');
-                // Continue without clustering
+                // Use worker thread clustering for uWebSockets
+                this.logger.info('uWebSockets clustering enabled - using worker threads with acceptor pattern', 'Cluster');
+                this.startWithUWSClustering(port, host, callback);
+                return;
             }
             else {
+                // Use traditional Node.js cluster module for standard HTTP
                 this.startWithClustering(port, host, callback);
                 return;
             }
@@ -431,7 +478,7 @@ export class Moro extends EventEmitter {
             this.coreFramework.addMiddleware(docsMiddleware);
             this.logger.debug('Documentation middleware added', 'Documentation');
         }
-        catch (error) {
+        catch {
             // Documentation not enabled, that's fine
             this.logger.debug('Documentation not enabled', 'Documentation');
         }
@@ -477,6 +524,10 @@ export class Moro extends EventEmitter {
                     this.unifiedRouter.logPerformanceStats();
                 }
                 this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
+                // Start job scheduler after server starts
+                this.startJobScheduler().catch(err => {
+                    this.logger.error(`Failed to start job scheduler: ${String(err)}`);
+                });
                 if (callback)
                     callback();
             };
@@ -603,7 +654,7 @@ export class Moro extends EventEmitter {
                 if (res.headersSent)
                     return;
             }
-            catch (error) {
+            catch {
                 // Documentation not enabled, that's fine
             }
             // Try unified router first (handles all routes)
@@ -621,6 +672,7 @@ export class Moro extends EventEmitter {
     // Handle direct routes for runtime adapters
     async handleDirectRoutes(req, res) {
         // Find matching route
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const route = this.findMatchingRoute(req.method, req.path);
         if (!route) {
             res.status(404).json({ success: false, error: 'Not found' });
@@ -707,8 +759,7 @@ export class Moro extends EventEmitter {
             };
         }
         // Phase 2: Optimized dynamic route matching by segment count
-        const segments = path.split('/').filter(s => s.length > 0);
-        const segmentCount = segments.length;
+        const segmentCount = PathMatcher.countSegments(path);
         const candidateRoutes = this.dynamicRoutesBySegments.get(segmentCount) || [];
         for (const route of candidateRoutes) {
             if (route.method === method) {
@@ -786,11 +837,11 @@ export class Moro extends EventEmitter {
         }
         else {
             // Dynamic route - organize by segment count
-            const segments = route.path.split('/').filter((s) => s.length > 0);
-            const segmentCount = segments.length;
+            const segmentCount = PathMatcher.countSegments(route.path);
             if (!this.dynamicRoutesBySegments.has(segmentCount)) {
                 this.dynamicRoutesBySegments.set(segmentCount, []);
             }
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             this.dynamicRoutesBySegments.get(segmentCount).push(route);
         }
     }
@@ -1147,6 +1198,7 @@ export class Moro extends EventEmitter {
             const gracefulShutdown = () => {
                 this.logger.info('Gracefully shutting down cluster...', 'Cluster');
                 // Clean up all workers
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
                 for (const [pid, worker] of this.clusterWorkers) {
                     worker.removeAllListeners();
                     worker.kill('SIGTERM');
@@ -1161,6 +1213,7 @@ export class Moro extends EventEmitter {
             // Fork workers with basic tracking
             for (let i = 0; i < workerCount; i++) {
                 const worker = cluster.fork();
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 this.clusterWorkers.set(worker.process.pid, worker);
                 this.logger.info(`Worker ${worker.process.pid} started`, 'Cluster');
                 // Handle individual worker messages
@@ -1174,6 +1227,7 @@ export class Moro extends EventEmitter {
                     this.logger.warn(`Worker ${pid} died unexpectedly (${signal || code}). Restarting...`, 'Cluster');
                     // Simple restart
                     const newWorker = cluster.fork();
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     this.clusterWorkers.set(newWorker.process.pid, newWorker);
                     this.logger.info(`Worker ${newWorker.process.pid} restarted`, 'Cluster');
                 }
@@ -1212,7 +1266,7 @@ export class Moro extends EventEmitter {
                     '--turbo-fast-api-calls', // Optimize API calls
                     '--turbo-escape-analysis', // Escape analysis optimization
                     '--turbo-inline-api-calls', // Inline API calls
-                    '--max-old-space-size=1024', // Limit memory to prevent GC pressure
+                    `--max-old-space-size=${heapSizePerWorkerMB}`, // Limit memory to prevent GC pressure
                 ];
                 process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS || '') + ' ' + v8Flags.join(' ');
             }
@@ -1255,7 +1309,7 @@ export class Moro extends EventEmitter {
                 const docsMiddleware = this.documentation.getDocsMiddleware();
                 this.coreFramework.addMiddleware(docsMiddleware);
             }
-            catch (error) {
+            catch {
                 // Documentation not enabled, that's fine
             }
             // Add unified routing middleware (handles both chainable and direct routes)
@@ -1330,18 +1384,209 @@ export class Moro extends EventEmitter {
         // Log other worker messages
         this.logger.debug(`Worker message: ${JSON.stringify(message)}`, 'Cluster');
     }
+    /**
+     * uWebSockets Worker Thread Clustering Implementation
+     * Uses worker threads with acceptor pattern for maximum performance
+     */
+    async startWithUWSClustering(port, host, callback) {
+        // Check if we're in a worker thread spawned by UWSWorkerClusterManager
+        if (UWSWorkerClusterManager.isUWSWorker()) {
+            // Worker thread mode - setup the app and send descriptor to acceptor
+            await this.startUWSWorker(port, host, callback);
+            return;
+        }
+        // Main thread mode - create acceptor and spawn workers
+        if (isMainThread) {
+            await this.startUWSAcceptor(port, host, callback);
+            return;
+        }
+    }
+    async startUWSAcceptor(port, host, callback) {
+        const clusterManager = new UWSWorkerClusterManager({
+            workers: this.config.performance?.clustering?.workers,
+            memoryPerWorkerGB: this.config.performance?.clustering?.memoryPerWorkerGB,
+            port,
+            host,
+            ssl: this.config.server?.ssl,
+        });
+        try {
+            await clusterManager.startAcceptorAndWorkers(() => {
+                // This factory function is not used in our implementation
+                // as we're using process.argv[1] to spawn workers
+                return null;
+            });
+            if (callback) {
+                callback();
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to start uWebSockets cluster', 'UWSCluster', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async startUWSWorker(port, host, callback) {
+        this.logger.info(`UWS Worker thread ${process.pid} initializing`, 'UWSWorker');
+        // Reduce logging contention in workers
+        if (!this.userSetLogger) {
+            applyLoggingConfiguration(undefined, { level: 'warn' });
+        }
+        // Worker-specific optimizations
+        process.env.UV_THREADPOOL_SIZE = '64';
+        // Setup graceful shutdown for worker
+        let isShuttingDown = false;
+        const shutdownWorker = async () => {
+            if (isShuttingDown)
+                return;
+            isShuttingDown = true;
+            this.logger.info(`UWS Worker thread ${process.pid} shutting down...`, 'UWSWorker');
+            // Close the server to clean up handles
+            const httpServer = this.coreFramework.httpServer;
+            if (httpServer && typeof httpServer.close === 'function') {
+                // Convert callback-based close to Promise
+                await new Promise(resolve => {
+                    httpServer.close(() => {
+                        resolve();
+                    });
+                    // Timeout after 1.5 seconds
+                    setTimeout(() => {
+                        this.logger.warn('HTTP server close timeout', 'UWSWorker');
+                        resolve();
+                    }, 1500);
+                });
+            }
+            // Clean up ALL event listeners
+            try {
+                this.eventBus.removeAllListeners();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            try {
+                this.removeAllListeners();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            // Remove all signal handlers
+            process.removeAllListeners('SIGINT');
+            process.removeAllListeners('SIGTERM');
+            this.logger.info(`UWS Worker thread ${process.pid} cleanup complete`, 'UWSWorker');
+        };
+        // Handle shutdown messages from parent
+        UWSWorkerClusterManager.setupWorkerShutdownHandler(shutdownWorker);
+        // Also handle direct signals
+        process.once('SIGINT', shutdownWorker);
+        process.once('SIGTERM', shutdownWorker);
+        // Emit worker starting event
+        this.eventBus.emit('server:starting', {
+            port,
+            runtime: this.runtimeType,
+            worker: process.pid,
+            workerType: 'thread',
+        });
+        // Add documentation middleware first (if enabled)
+        try {
+            const docsMiddleware = this.documentation.getDocsMiddleware();
+            this.coreFramework.addMiddleware(docsMiddleware);
+        }
+        catch {
+            // Documentation not enabled, that's fine
+        }
+        // Add unified routing middleware
+        this.coreFramework.addMiddleware(async (req, res, next) => {
+            const handled = this.unifiedRouter.handleRequest(req, res);
+            if (handled && typeof handled.then === 'function') {
+                const isHandled = await handled;
+                if (!isHandled) {
+                    next();
+                }
+            }
+            else {
+                if (!handled) {
+                    next();
+                }
+            }
+        });
+        // Register legacy direct routes with the HTTP server
+        if (this.routes.length > 0) {
+            this.registerDirectRoutes();
+        }
+        const workerCallback = () => {
+            const displayHost = host || 'localhost';
+            this.logger.info(`UWS Worker thread ${process.pid} ready on ${displayHost}:${port}`, 'UWSWorker');
+            this.eventBus.emit('server:started', {
+                port,
+                runtime: this.runtimeType,
+                worker: process.pid,
+                workerType: 'thread',
+            });
+            // Send descriptor to acceptor
+            const httpServer = this.coreFramework.httpServer;
+            if (httpServer && typeof httpServer.getDescriptor === 'function') {
+                UWSWorkerClusterManager.sendDescriptorToAcceptor(httpServer.getApp())
+                    .then(() => {
+                    if (callback) {
+                        callback();
+                    }
+                })
+                    .catch((error) => {
+                    this.logger.error('Failed to send descriptor to acceptor', 'UWSWorker', {
+                        error: error.message,
+                    });
+                });
+            }
+            else {
+                this.logger.error('HTTP server does not support getDescriptor()', 'UWSWorker');
+            }
+        };
+        // Ensure WebSocket setup is complete before starting worker
+        await this.processQueuedWebSocketRegistrations();
+        // Start listening on worker-specific port (4000 range)
+        const workerPort = 4000 + parseInt(process.env.UWS_WORKER_INDEX || '0', 10);
+        if (host) {
+            this.coreFramework.listen(workerPort, host, workerCallback);
+        }
+        else {
+            this.coreFramework.listen(workerPort, workerCallback);
+        }
+    }
     /**
      * Gracefully close the application and clean up resources
      * This should be called in tests and during shutdown
      */
     async close() {
         this.logger.debug('Closing Moro application...');
+        // Shutdown job scheduler first
+        if (this.jobScheduler) {
+            try {
+                this.logger.info('Shutting down job scheduler...');
+                await this.jobScheduler.shutdown();
+                this.jobsStarted = false;
+            }
+            catch (err) {
+                this.logger.error(`Error shutting down job scheduler: ${String(err)}`);
+            }
+        }
+        // Cleanup GraphQL executor timers
+        if (this.graphqlCore) {
+            try {
+                const executor = this.graphqlCore.getExecutor();
+                if (executor) {
+                    executor.cleanup();
+                }
+            }
+            catch (err) {
+                this.logger.error(`Error cleaning up GraphQL: ${String(err)}`);
+            }
+        }
         // Flush logger buffer before shutdown
         try {
             // Use flushBuffer for immediate synchronous flush
             this.logger.flushBuffer();
         }
-        catch (error) {
+        catch {
             // Ignore flush errors during shutdown
         }
         // Close the core framework with timeout
@@ -1356,7 +1601,7 @@ export class Moro extends EventEmitter {
                     new Promise(resolve => setTimeout(resolve, 2000)), // 2 second timeout
                 ]);
             }
-            catch (error) {
+            catch {
                 // Force close if graceful close fails
                 this.logger.warn('Force closing HTTP server due to timeout');
             }
@@ -1366,7 +1611,7 @@ export class Moro extends EventEmitter {
             try {
                 this.moduleDiscovery.cleanup();
             }
-            catch (error) {
+            catch {
                 // Ignore cleanup errors
             }
         }
@@ -1375,11 +1620,342 @@ export class Moro extends EventEmitter {
             this.eventBus.removeAllListeners();
             this.removeAllListeners();
         }
-        catch (error) {
+        catch {
             // Ignore cleanup errors
         }
         this.logger.debug('Moro application closed successfully');
     }
+    // ========================================
+    // Job Scheduling API
+    // ========================================
+    /**
+     * Register a background job with cron or interval schedule
+     * @param name - Job name (used for identification)
+     * @param schedule - Cron expression, interval string ('5m', '1h'), or schedule object
+     * @param handler - Job function to execute
+     * @param options - Job configuration options
+     * @returns Job ID for management
+     *
+     * @example
+     * // Cron schedule
+     * app.job('cleanup', '0 2 * * *', async () => {
+     *   await cleanupOldData();
+     * });
+     *
+     * // Interval schedule
+     * app.job('health-check', '5m', async (ctx) => {
+     *   console.log('Health check', ctx.executionId);
+     * });
+     *
+     * // Advanced options
+     * app.job('report', '@daily', generateReport, {
+     *   timeout: 60000,
+     *   maxRetries: 3,
+     *   onError: (ctx, error) => console.error('Job failed', error)
+     * });
+     */
+    job(name, schedule, handler, options = {}) {
+        if (!this.jobScheduler) {
+            throw new Error('Job scheduler is not enabled. Set config.jobs.enabled = true');
+        }
+        let jobSchedule;
+        // Parse schedule input
+        if (typeof schedule === 'string') {
+            // Check if it's a cron expression or interval
+            if (schedule.match(/^(\d+[smhd]|\d+\s*(seconds?|minutes?|hours?|days?))$/i)) {
+                // Interval format
+                jobSchedule = everyInterval(schedule);
+            }
+            else {
+                // Cron format
+                jobSchedule = cronSchedule(schedule, options.timezone);
+            }
+        }
+        else {
+            jobSchedule = schedule;
+        }
+        const jobOptions = {
+            name: options.name || name,
+            enabled: options.enabled,
+            priority: options.priority,
+            timezone: options.timezone,
+            maxConcurrent: options.maxConcurrent,
+            timeout: options.timeout,
+            maxRetries: options.maxRetries,
+            retryDelay: options.retryDelay,
+            retryBackoff: options.retryBackoff,
+            enableCircuitBreaker: options.enableCircuitBreaker,
+            metadata: options.metadata,
+            onStart: options.onStart,
+            onComplete: options.onComplete,
+            onError: options.onError,
+        };
+        const jobId = this.jobScheduler.registerJob(name, jobSchedule, handler, jobOptions);
+        this.logger.info(`Job registered: ${name} (${jobId})`);
+        return jobId;
+    }
+    /**
+     * Enable or disable a registered job
+     */
+    setJobEnabled(jobId, enabled) {
+        if (!this.jobScheduler) {
+            return false;
+        }
+        return this.jobScheduler.setJobEnabled(jobId, enabled);
+    }
+    /**
+     * Manually trigger a job execution
+     */
+    async triggerJob(jobId, metadata) {
+        if (!this.jobScheduler) {
+            throw new Error('Job scheduler is not enabled');
+        }
+        return this.jobScheduler.triggerJob(jobId, metadata);
+    }
+    /**
+     * Unregister a job
+     */
+    unregisterJob(jobId) {
+        if (!this.jobScheduler) {
+            throw new Error('Job scheduler is not enabled');
+        }
+        return this.jobScheduler.unregisterJob(jobId);
+    }
+    /**
+     * Get job metrics
+     */
+    getJobMetrics(jobId) {
+        if (!this.jobScheduler) {
+            return null;
+        }
+        return this.jobScheduler.getJobMetrics(jobId);
+    }
+    /**
+     * Get job health status
+     */
+    getJobHealth(jobId) {
+        if (!this.jobHealthChecker) {
+            if (jobId) {
+                return {
+                    jobId,
+                    name: 'Unknown',
+                    status: 'unknown',
+                    enabled: false,
+                    consecutiveFailures: 0,
+                    message: 'Job scheduler not enabled',
+                };
+            }
+            return [];
+        }
+        if (jobId) {
+            return this.jobHealthChecker.checkJobHealth(jobId);
+        }
+        return this.jobHealthChecker.checkAllJobs();
+    }
+    /**
+     * Get scheduler statistics
+     */
+    getJobStats() {
+        if (!this.jobScheduler) {
+            return null;
+        }
+        return this.jobScheduler.getStats();
+    }
+    /**
+     * Get overall scheduler health
+     */
+    getSchedulerHealth() {
+        if (!this.jobHealthChecker) {
+            return {
+                status: 'unknown',
+                message: 'Job scheduler not enabled',
+                stats: null,
+                jobs: [],
+                unhealthyJobCount: 0,
+            };
+        }
+        return this.jobHealthChecker.getSchedulerHealth();
+    }
+    /**
+     * Start the job scheduler (called automatically on listen)
+     */
+    async startJobScheduler() {
+        if (!this.jobScheduler || this.jobsStarted) {
+            return;
+        }
+        try {
+            await this.jobScheduler.start();
+            this.jobsStarted = true;
+            this.logger.info('Job scheduler started');
+        }
+        catch (err) {
+            this.logger.error(`Failed to start job scheduler: ${String(err)}`);
+        }
+    }
+    // ========================================
+    // GraphQL API
+    // ========================================
+    /**
+     * Configure GraphQL endpoint with schema, resolvers, and options
+     *
+     * @param options - GraphQL configuration options
+     *
+     * @example
+     * ```ts
+     * // Using type definitions and resolvers
+     * app.graphql({
+     *   typeDefs: `
+     *     type Query {
+     *       hello: String
+     *       users: [User]
+     *     }
+     *     type User {
+     *       id: ID!
+     *       name: String!
+     *     }
+     *   `,
+     *   resolvers: {
+     *     Query: {
+     *       hello: () => 'Hello World!',
+     *       users: () => [{ id: '1', name: 'Alice' }]
+     *     }
+     *   }
+     * });
+     *
+     * // Using Pothos schema builder
+     * import SchemaBuilder from '@pothos/core';
+     *
+     * const builder = new SchemaBuilder();
+     * builder.queryType({
+     *   fields: (t) => ({
+     *     hello: t.string({ resolve: () => 'Hello World!' })
+     *   })
+     * });
+     *
+     * app.graphql({
+     *   pothosSchema: builder
+     * });
+     * ```
+     */
+    graphql(options) {
+        if (this.graphqlCore || this.graphqlInitPromise) {
+            throw new Error('GraphQL has already been configured. Call graphql() only once.');
+        }
+        // Check if graphql package is available
+        if (!this.isGraphQLAvailable()) {
+            throw new Error('GraphQL support requires the graphql package to be installed.\n' +
+                'Install it with: npm install graphql\n' +
+                'For TypeScript-first GraphQL, also consider: npm install @pothos/core\n' +
+                'For performance boost: npm install graphql-jit');
+        }
+        this.logger.info('Configuring GraphQL', 'GraphQL', {
+            path: options.path || '/graphql',
+            jit: options.enableJIT !== false,
+            playground: options.enablePlayground !== false,
+        });
+        // Initialize GraphQL asynchronously (like WebSocket registration pattern)
+        this.graphqlInitPromise = this.initializeGraphQL(options);
+        // Add to initialization promises
+        const originalEnsure = this.ensureAutoDiscoveryComplete.bind(this);
+        this.ensureAutoDiscoveryComplete = async () => {
+            await originalEnsure();
+            await this.graphqlInitPromise;
+        };
+        return this;
+    }
+    /**
+     * Initialize GraphQL system asynchronously
+     */
+    async initializeGraphQL(options) {
+        try {
+            // Lazy load GraphQL modules
+            await this.loadGraphQLModules();
+            // Create GraphQL core
+            this.graphqlCore = new GraphQLCore(options);
+            // Initialize GraphQL
+            await this.graphqlCore.initialize();
+            this.logger.info('GraphQL initialized successfully', 'GraphQL');
+            // Setup subscriptions if enabled
+            if (options.enableSubscriptions !== false && this.config.websocket.enabled) {
+                this.setupGraphQLSubscriptions(options);
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to initialize GraphQL', 'GraphQL', { error });
+            throw error;
+        }
+    }
+    /**
+     * Check if GraphQL package is available
+     */
+    isGraphQLAvailable() {
+        try {
+            require.resolve('graphql');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Lazy load GraphQL modules
+     */
+    async loadGraphQLModules() {
+        if (GraphQLCore) {
+            return; // Already loaded
+        }
+        try {
+            // GraphQL core now uses adapters with no static imports from 'graphql'
+            const coreModule = await import('./core/graphql/core.js');
+            GraphQLCore = coreModule.GraphQLCore;
+            const subsModule = await import('./core/middleware/built-in/graphql/subscriptions.js');
+            GraphQLSubscriptionManager = subsModule.GraphQLSubscriptionManager;
+            setupGraphQLSubscriptions = subsModule.setupGraphQLSubscriptions;
+        }
+        catch (error) {
+            this.logger.error('Failed to load GraphQL modules', 'GraphQL', { error });
+            throw new Error('Failed to load GraphQL modules. Please ensure graphql is installed.');
+        }
+    }
+    /**
+     * Setup GraphQL subscriptions
+     */
+    setupGraphQLSubscriptions(options) {
+        const websocketAdapter = this.coreFramework.getWebSocketAdapter();
+        if (!websocketAdapter) {
+            this.logger.warn('GraphQL subscriptions require WebSocket to be enabled', 'GraphQL');
+            return;
+        }
+        if (!this.graphqlCore) {
+            return;
+        }
+        const schema = this.graphqlCore.getSchema();
+        this.graphqlSubscriptionManager = setupGraphQLSubscriptions(websocketAdapter, schema, {
+            path: options.path ? `${options.path}/subscriptions` : '/graphql/subscriptions',
+            contextFactory: options.context,
+        });
+        this.logger.info('GraphQL subscriptions enabled', 'GraphQL', {
+            path: options.path ? `${options.path}/subscriptions` : '/graphql/subscriptions',
+        });
+    }
+    /**
+     * Get GraphQL schema (if configured)
+     */
+    getGraphQLSchema() {
+        return this.graphqlCore?.getSchema();
+    }
+    /**
+     * Get GraphQL stats
+     */
+    getGraphQLStats() {
+        if (!this.graphqlCore) {
+            return null;
+        }
+        return {
+            ...this.graphqlCore.getStats(),
+            subscriptions: this.graphqlSubscriptionManager?.getSubscriptionCount() || 0,
+        };
+    }
 }
 // Export convenience function
 export function createApp(options) {