@morojs/moro 1.6.1 → 1.6.3

package/dist/moro.js

@@ -1,154 +1,99 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Moro = void 0;
-exports.createApp = createApp;
-exports.createAppNode = createAppNode;
-exports.createAppEdge = createAppEdge;
-exports.createAppLambda = createAppLambda;
-exports.createAppWorker = createAppWorker;
 // Moro Framework - Modern TypeScript API Framework
 // Built for developers who demand performance, elegance, and zero compromises
 // Event-driven • Modular • Enterprise-ready • Developer-first
-const framework_1 = require("./core/framework");
-const http_1 = require("./core/http");
-const logger_1 = require("./core/logger");
-const middleware_1 = require("./core/middleware");
-const app_integration_1 = require("./core/routing/app-integration");
-const docs_1 = require("./core/docs");
-const fs_1 = require("fs");
-const path_1 = require("path");
-const events_1 = require("events");
+import { Moro as MoroCore } from './core/framework.js';
+import { middleware } from './core/http/index.js';
+import { createFrameworkLogger, applyLoggingConfiguration } from './core/logger/index.js';
+import { MiddlewareManager } from './core/middleware/index.js';
+import { IntelligentRoutingManager } from './core/routing/app-integration.js';
+import { UnifiedRouter, } from './core/routing/unified-router.js';
+import { AppDocumentationManager } from './core/docs/index.js';
+import { EventEmitter } from 'events';
+import cluster from 'cluster';
+import os from 'os';
+import { normalizeValidationError } from './core/validation/schema-interface.js';
 // Configuration System Integration
-const config_1 = require("./core/config");
+import { initializeConfig } from './core/config/index.js';
 // Runtime System Integration
-const runtime_1 = require("./core/runtime");
-class Moro extends events_1.EventEmitter {
+import { createRuntimeAdapter } from './core/runtime/index.js';
+export class Moro extends EventEmitter {
     coreFramework;
     routes = [];
     moduleCounter = 0;
     loadedModules = new Set();
+    lazyModules = new Map();
     routeHandlers = {};
+    moduleDiscovery; // Store for cleanup
+    autoDiscoveryOptions = null;
+    autoDiscoveryInitialized = false;
+    autoDiscoveryPromise = null;
     // Enterprise event system integration
     eventBus;
     // Application logger
-    logger = (0, logger_1.createFrameworkLogger)('App');
-    // Intelligent routing system
-    intelligentRouting = new app_integration_1.IntelligentRoutingManager();
+    logger;
+    // Unified routing system (singleton - shared across all routers)
+    unifiedRouter;
+    // Legacy intelligent routing (kept for backward compatibility, now a facade)
+    intelligentRouting;
     // Documentation system
-    documentation = new docs_1.AppDocumentationManager();
+    documentation = new AppDocumentationManager();
     // Configuration system
     config;
+    // Track if user explicitly set logger options (for worker log level handling)
+    userSetLogger = false;
     // Runtime system
     runtimeAdapter;
     runtimeType;
     // Middleware system
     middlewareManager;
+    // Queued WebSocket registrations (for async adapter detection)
+    queuedWebSocketRegistrations = [];
     constructor(options = {}) {
         super(); // Call EventEmitter constructor
-        // Configure logger from environment variables BEFORE config system initialization
-        // This ensures the config loading process respects the log level
+        // Track if user explicitly set logger/logging options
+        this.userSetLogger = !!(options.logger || options.logging);
+        // Apply logging configuration BEFORE config loading to avoid DEBUG spam
+        // 1. Environment variables (base level)
         const envLogLevel = process.env.LOG_LEVEL || process.env.MORO_LOG_LEVEL;
         if (envLogLevel) {
-            (0, logger_1.applyLoggingConfiguration)({ level: envLogLevel }, undefined);
-        }
-        // Initialize configuration system - create a deep copy for this instance
-        this.config = JSON.parse(JSON.stringify((0, config_1.initializeConfig)()));
-        // Apply logging configuration from the loaded config (this happens after config file processing)
-        if (this.config.logging) {
-            (0, logger_1.applyLoggingConfiguration)(this.config.logging, undefined);
+            applyLoggingConfiguration({ level: envLogLevel }, undefined);
         }
-        // Apply additional logging configuration from createApp options (takes precedence)
+        // 2. createApp logger options (highest precedence)
         if (options.logger !== undefined) {
-            (0, logger_1.applyLoggingConfiguration)(undefined, options.logger);
-        }
-        // Apply performance configuration from createApp options (takes precedence)
-        if (options.performance) {
-            if (options.performance.clustering) {
-                this.config.performance.clustering = {
-                    ...this.config.performance.clustering,
-                    ...options.performance.clustering,
-                };
-            }
-            if (options.performance.compression) {
-                this.config.performance.compression = {
-                    ...this.config.performance.compression,
-                    ...options.performance.compression,
-                };
-            }
-            if (options.performance.circuitBreaker) {
-                this.config.performance.circuitBreaker = {
-                    ...this.config.performance.circuitBreaker,
-                    ...options.performance.circuitBreaker,
-                };
-            }
+            applyLoggingConfiguration(undefined, options.logger);
         }
-        // Apply modules configuration from createApp options (takes precedence)
-        if (options.modules) {
-            if (options.modules.cache) {
-                this.config.modules.cache = {
-                    ...this.config.modules.cache,
-                    ...options.modules.cache,
-                };
-            }
-            if (options.modules.rateLimit) {
-                this.config.modules.rateLimit = {
-                    ...this.config.modules.rateLimit,
-                    ...options.modules.rateLimit,
-                };
-            }
-            if (options.modules.validation) {
-                this.config.modules.validation = {
-                    ...this.config.modules.validation,
-                    ...options.modules.validation,
-                };
-            }
+        // Create logger AFTER initial configuration
+        this.logger = createFrameworkLogger('App');
+        // Use simplified global configuration system
+        this.config = initializeConfig(options);
+        // Apply final config logging (this includes normalized logger → logging conversion)
+        // Always apply this as it's the authoritative merged config
+        if (this.config.logging) {
+            applyLoggingConfiguration(this.config.logging, undefined);
+            // Recreate logger with updated config
+            this.logger = createFrameworkLogger('App');
         }
-        this.logger.info(`Configuration system initialized: ${this.config.server.environment}:${this.config.server.port}`);
+        // NOW initialize routing systems AFTER logger is configured
+        this.unifiedRouter = UnifiedRouter.getInstance();
+        this.intelligentRouting = new IntelligentRoutingManager();
+        this.logger.info(`Configuration system initialized: ${process.env.NODE_ENV || 'development'}:${this.config.server.port}`);
         // Initialize runtime system
         this.runtimeType = options.runtime?.type || 'node';
-        this.runtimeAdapter = options.runtime?.adapter || (0, runtime_1.createRuntimeAdapter)(this.runtimeType);
+        this.runtimeAdapter = options.runtime?.adapter || createRuntimeAdapter(this.runtimeType);
         this.logger.info(`Runtime system initialized: ${this.runtimeType}`, 'Runtime');
-        // Pass logging configuration from config to framework
+        // Pass configuration from config to framework
         const frameworkOptions = {
             ...options,
             logger: this.config.logging,
+            // Enable websockets if either config has it enabled OR user passed websocket options
+            websocket: this.config.websocket.enabled || options.websocket
+                ? options.websocket || this.config.websocket || {}
+                : false,
+            config: this.config,
         };
-        this.coreFramework = new framework_1.Moro(frameworkOptions);
+        this.coreFramework = new MoroCore(frameworkOptions);
         // Initialize middleware system
-        this.middlewareManager = new middleware_1.MiddlewareManager();
+        this.middlewareManager = new MiddlewareManager();
         // Integrate hooks system with HTTP server
         const httpServer = this.coreFramework.httpServer;
         if (httpServer && httpServer.setHookManager) {
@@ -169,10 +114,10 @@ class Moro extends events_1.EventEmitter {
             ...this.getDefaultOptionsFromConfig(),
             ...options,
         });
-        // Auto-discover modules if enabled
-        if (options.autoDiscover !== false) {
-            this.autoDiscoverModules(options.modulesPath || './modules');
-        }
+        // Store auto-discovery options for later initialization
+        // IMPORTANT: Auto-discovery is deferred to ensure user middleware (like auth)
+        // is registered before module middleware that might bypass it
+        this.autoDiscoveryOptions = options.autoDiscover !== false ? options : null;
         // Emit initialization event through enterprise event bus
         this.eventBus.emit('framework:initialized', {
             options,
@@ -213,44 +158,45 @@ class Moro extends events_1.EventEmitter {
             // Direct route registration
             return this.addRoute('GET', path, handler, options);
         }
-        // Chainable route builder
-        return this.intelligentRouting.get(path);
+        // Use unified router for chainable API
+        return this.unifiedRouter.get(path);
     }
     post(path, handler, options) {
         if (handler) {
             // Direct route registration
             return this.addRoute('POST', path, handler, options);
         }
-        // Chainable route builder
-        return this.intelligentRouting.post(path);
+        // Use unified router for chainable API
+        return this.unifiedRouter.post(path);
     }
     put(path, handler, options) {
         if (handler) {
             // Direct route registration
             return this.addRoute('PUT', path, handler, options);
         }
-        // Chainable route builder
-        return this.intelligentRouting.put(path);
+        // Use unified router for chainable API
+        return this.unifiedRouter.put(path);
     }
     delete(path, handler, options) {
         if (handler) {
             // Direct route registration
             return this.addRoute('DELETE', path, handler, options);
         }
-        // Chainable route builder
-        return this.intelligentRouting.delete(path);
+        // Use unified router for chainable API
+        return this.unifiedRouter.delete(path);
     }
     patch(path, handler, options) {
         if (handler) {
             // Direct route registration
             return this.addRoute('PATCH', path, handler, options);
         }
-        // Chainable route builder
-        return this.intelligentRouting.patch(path);
+        // Use unified router for chainable API
+        return this.unifiedRouter.patch(path);
     }
     // Schema-first route method
     route(schema) {
-        return this.intelligentRouting.route(schema);
+        // Use unified router for schema-first registration
+        this.unifiedRouter.route(schema);
     }
     // Enable automatic API documentation
     enableDocs(config) {
@@ -338,6 +284,11 @@ class Moro extends events_1.EventEmitter {
                 version: moduleOrPath.version || '1.0.0',
             });
         }
+        // IMPORTANT: If modules are loaded manually after auto-discovery,
+        // ensure the final module handler is set up to maintain middleware order
+        if (this.autoDiscoveryInitialized) {
+            this.coreFramework.setupFinalModuleHandler();
+        }
         return this;
     }
     // Database helper with events
@@ -351,29 +302,36 @@ class Moro extends events_1.EventEmitter {
     }
     // WebSocket helper with events
     websocket(namespace, handlers) {
+        // Queue the registration to be processed after adapter initialization
+        const registration = { namespace, handlers, processed: false };
+        this.queuedWebSocketRegistrations.push(registration);
+        // Try to process immediately if adapter is already ready
         const adapter = this.coreFramework.getWebSocketAdapter();
-        if (!adapter) {
-            throw new Error('WebSocket features require a WebSocket adapter. Install socket.io or configure an adapter:\n' +
-                'npm install socket.io\n' +
-                'or\n' +
-                'new Moro({ websocket: { adapter: new SocketIOAdapter() } })');
+        if (adapter && !registration.processed) {
+            // Adapter is ready, process immediately
+            this.processWebSocketRegistration(namespace, handlers, adapter);
+            registration.processed = true;
         }
+        // Otherwise, it will be processed when the server starts
+        return this;
+    }
+    processWebSocketRegistration(namespace, handlers, adapter) {
         this.emit('websocket:registering', { namespace, handlers });
         const ns = adapter.createNamespace(namespace);
         Object.entries(handlers).forEach(([event, handler]) => {
-            ns.on('connection', socket => {
+            ns.on('connection', (socket) => {
                 this.emit('websocket:connection', { namespace, event, socket });
                 socket.on(event, (data, callback) => {
                     this.emit('websocket:event', { namespace, event, data });
                     Promise.resolve(handler(socket, data))
-                        .then(result => {
+                        .then((result) => {
                         this.emit('websocket:response', { namespace, event, result });
                         if (callback)
                             callback(result);
                         else if (result)
                             socket.emit(`${event}:response`, result);
                     })
-                        .catch(error => {
+                        .catch((error) => {
                         this.emit('websocket:error', { namespace, event, error });
                         const errorResponse = { success: false, error: error.message };
                         if (callback)
@@ -385,7 +343,33 @@ class Moro extends events_1.EventEmitter {
             });
         });
         this.emit('websocket:registered', { namespace, handlers });
-        return this;
+    }
+    async processQueuedWebSocketRegistrations() {
+        // Wait for WebSocket adapter to be ready
+        await this.coreFramework.ensureWebSocketReady();
+        const adapter = this.coreFramework.getWebSocketAdapter();
+        // Check if any unprocessed registrations exist
+        const unprocessedRegistrations = this.queuedWebSocketRegistrations.filter(r => !r.processed);
+        if (!adapter && unprocessedRegistrations.length > 0) {
+            throw new Error('WebSocket features require a WebSocket adapter.\n\n' +
+                'Option 1: Install socket.io (auto-detected):\n' +
+                '  npm install socket.io\n' +
+                '  const app = new Moro({ websocket: {} });\n\n' +
+                'Option 2: Configure a specific adapter:\n' +
+                "  import { SocketIOAdapter } from '@morojs/moro';\n" +
+                '  const app = new Moro({ websocket: { adapter: new SocketIOAdapter() } });\n\n' +
+                'Option 3: Enable in config file (moro.config.js):\n' +
+                '  export default { websocket: { enabled: true } };');
+        }
+        if (adapter) {
+            // Process all unprocessed registrations
+            for (const registration of this.queuedWebSocketRegistrations) {
+                if (!registration.processed) {
+                    this.processWebSocketRegistration(registration.namespace, registration.handlers, adapter);
+                    registration.processed = true;
+                }
+            }
+        }
     }
     listen(portOrCallback, hostOrCallback, callback) {
         // Only available for Node.js runtime
@@ -427,9 +411,18 @@ class Moro extends events_1.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) {
-            this.startWithClustering(port, host, callback);
-            return;
+            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
+            }
+            else {
+                this.startWithClustering(port, host, callback);
+                return;
+            }
         }
         this.eventBus.emit('server:starting', { port, runtime: this.runtimeType });
         // Add documentation middleware first (if enabled)
@@ -442,44 +435,165 @@ class Moro extends events_1.EventEmitter {
             // Documentation not enabled, that's fine
             this.logger.debug('Documentation not enabled', 'Documentation');
         }
-        // Add intelligent routing middleware to handle chainable routes
+        // Add unified routing middleware (handles both chainable and direct routes)
+        // Optimized: call router without extra async wrapper when possible
         this.coreFramework.addMiddleware(async (req, res, next) => {
-            // Try intelligent routing first
-            const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
-            if (!handled) {
-                next(); // Fall back to direct routes
+            // Try unified router first (handles all route types)
+            const handled = this.unifiedRouter.handleRequest(req, res);
+            // Check if it's a promise (async route) or sync (fast-path)
+            if (handled && typeof handled.then === 'function') {
+                // Async - await the result
+                const isHandled = await handled;
+                if (!isHandled) {
+                    next();
+                }
+            }
+            else {
+                // Sync - check immediately
+                if (!handled) {
+                    next();
+                }
             }
         });
-        // Register direct routes with the HTTP server
+        // Register legacy direct routes with the HTTP server (for backward compatibility)
         if (this.routes.length > 0) {
             this.registerDirectRoutes();
         }
-        const actualCallback = () => {
-            const displayHost = host || 'localhost';
-            this.logger.info('Moro Server Started', 'Server');
-            this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
-            this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
-            this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
-            this.logger.info('Native Node.js HTTP • Zero Dependencies • Maximum Performance', 'Server');
-            this.logger.info('Learn more at https://morojs.com', 'Server');
-            // Log intelligent routes info
-            const intelligentRoutes = this.intelligentRouting.getIntelligentRoutes();
-            if (intelligentRoutes.length > 0) {
-                this.logger.info(`Intelligent Routes: ${intelligentRoutes.length} registered`, 'Server');
+        const startServer = () => {
+            const actualCallback = () => {
+                const displayHost = host || 'localhost';
+                this.logger.info('Moro Server Started', 'Server');
+                this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
+                this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
+                if (this.config.websocket.enabled) {
+                    this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
+                }
+                this.logger.info('Learn more at https://morojs.com', 'Server');
+                // Log unified router stats
+                const routeCount = this.unifiedRouter.getRouteCount();
+                if (routeCount > 0) {
+                    this.logger.info(`Unified Router: ${routeCount} routes registered`, 'Server');
+                    // Log performance stats
+                    this.unifiedRouter.logPerformanceStats();
+                }
+                this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
+                if (callback)
+                    callback();
+            };
+            if (host && typeof host === 'string') {
+                this.coreFramework.listen(port, host, actualCallback);
+            }
+            else {
+                this.coreFramework.listen(port, actualCallback);
             }
-            this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
-            if (callback)
-                callback();
         };
-        if (host && typeof host === 'string') {
-            this.coreFramework.listen(port, host, actualCallback);
+        // Ensure auto-discovery and WebSocket setup is complete before starting server
+        Promise.all([this.ensureAutoDiscoveryComplete(), this.processQueuedWebSocketRegistrations()])
+            .then(() => {
+            startServer();
+        })
+            .catch(error => {
+            this.logger.error('Initialization failed during server start', 'Framework', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // For auto-discovery failures, start server anyway
+            // For WebSocket failures with queued registrations, error will propagate
+            if (error instanceof Error &&
+                error.message.includes('WebSocket features require a WebSocket adapter')) {
+                throw error;
+            }
+            startServer();
+        });
+    }
+    // Public method to manually initialize auto-discovery
+    // Useful for ensuring auth middleware is registered before auto-discovery
+    async initializeAutoDiscoveryNow() {
+        return this.ensureAutoDiscoveryComplete();
+    }
+    // Public API: Initialize modules explicitly after middleware setup
+    // This provides users with explicit control over module loading timing
+    // IMPORTANT: This forces module loading even if autoDiscovery.enabled is false
+    // Usage: app.initModules() or app.initModules({ paths: ['./my-modules'] })
+    initModules(options) {
+        this.logger.info('User-requested module initialization', 'ModuleSystem');
+        // If already initialized, do nothing
+        if (this.autoDiscoveryInitialized) {
+            this.logger.debug('Auto-discovery already completed, skipping', 'ModuleSystem');
+            return;
         }
-        else {
-            this.coreFramework.listen(port, actualCallback);
+        // Store the options and mark that we want to force initialization
+        this.autoDiscoveryOptions = {
+            autoDiscover: {
+                enabled: true, // Force enabled regardless of original config
+                paths: options?.paths || ['./modules', './src/modules'],
+                patterns: options?.patterns || [
+                    '**/*.module.{ts,js}',
+                    '**/index.{ts,js}',
+                    '**/*.config.{ts,js}',
+                ],
+                recursive: options?.recursive ?? true,
+                loadingStrategy: options?.loadingStrategy || 'eager',
+                watchForChanges: options?.watchForChanges ?? false,
+                ignorePatterns: options?.ignorePatterns || [
+                    '**/*.test.{ts,js}',
+                    '**/*.spec.{ts,js}',
+                    '**/node_modules/**',
+                ],
+                loadOrder: options?.loadOrder || 'dependency',
+                failOnError: options?.failOnError ?? false,
+                maxDepth: options?.maxDepth ?? 5,
+            },
+        };
+        this.logger.debug('Module initialization options stored, will execute on next listen/getHandler call', 'ModuleSystem');
+    }
+    // Robust method to ensure auto-discovery is complete, handling race conditions
+    async ensureAutoDiscoveryComplete() {
+        // If already initialized, nothing to do
+        if (this.autoDiscoveryInitialized) {
+            return;
+        }
+        // If auto-discovery is disabled, mark as initialized
+        if (!this.autoDiscoveryOptions) {
+            this.autoDiscoveryInitialized = true;
+            return;
+        }
+        // If already in progress, wait for it to complete
+        if (this.autoDiscoveryPromise) {
+            return this.autoDiscoveryPromise;
+        }
+        // Start auto-discovery
+        this.autoDiscoveryPromise = this.performAutoDiscovery();
+        try {
+            await this.autoDiscoveryPromise;
+            this.autoDiscoveryInitialized = true;
+        }
+        catch (error) {
+            // Reset promise on error so it can be retried
+            this.autoDiscoveryPromise = null;
+            throw error;
+        }
+        finally {
+            this.autoDiscoveryOptions = null; // Clear after attempt
         }
     }
+    // Perform the actual auto-discovery work
+    async performAutoDiscovery(optionsOverride) {
+        const optionsToUse = optionsOverride || this.autoDiscoveryOptions;
+        if (!optionsToUse)
+            return;
+        this.logger.debug('Starting auto-discovery initialization', 'AutoDiscovery');
+        await this.initializeAutoDiscovery(optionsToUse);
+        this.logger.debug('Auto-discovery initialization completed', 'AutoDiscovery');
+    }
     // Get handler for non-Node.js runtimes
     getHandler() {
+        // Ensure auto-discovery is complete for non-Node.js runtimes
+        // This handles the case where users call getHandler() immediately after createApp()
+        this.ensureAutoDiscoveryComplete().catch(error => {
+            this.logger.error('Auto-discovery initialization failed for runtime handler', 'Framework', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
         // Create a unified request handler that works with the runtime adapter
         const handler = async (req, res) => {
             // Add documentation middleware first (if enabled)
@@ -492,11 +606,11 @@ class Moro extends events_1.EventEmitter {
             catch (error) {
                 // Documentation not enabled, that's fine
             }
-            // Try intelligent routing first
-            const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
+            // Try unified router first (handles all routes)
+            const handled = await this.unifiedRouter.handleRequest(req, res);
             if (handled)
                 return;
-            // Handle direct routes
+            // Handle legacy direct routes (backward compatibility)
             if (this.routes.length > 0) {
                 await this.handleDirectRoutes(req, res);
             }
@@ -644,6 +758,9 @@ class Moro extends events_1.EventEmitter {
     }
     // Private methods
     addRoute(method, path, handler, options = {}) {
+        // Register with unified router (primary routing system)
+        this.unifiedRouter.addRoute(method, path, handler, options.middleware || []);
+        // Also store in legacy routes array for backward compatibility
         const handlerName = `handler_${this.routes.length}`;
         const route = {
             method: method,
@@ -655,9 +772,9 @@ class Moro extends events_1.EventEmitter {
             middleware: options.middleware,
         };
         this.routes.push(route);
-        // Organize routes for optimal lookup
+        // Organize routes for optimal lookup (legacy)
         this.organizeRouteForLookup(route);
-        // Store handler for later module creation
+        // Store handler for later module creation (legacy)
         this.routeHandlers[handlerName] = handler;
         return this;
     }
@@ -697,7 +814,6 @@ class Moro extends events_1.EventEmitter {
                         }
                         catch (error) {
                             // Handle universal validation errors
-                            const { normalizeValidationError } = require('./core/validation/schema-interface');
                             const normalizedError = normalizeValidationError(error);
                             res.status(400).json({
                                 success: false,
@@ -767,91 +883,266 @@ class Moro extends events_1.EventEmitter {
         return true;
     }
     setupDefaultMiddleware(options) {
-        // CORS
-        if (options.cors !== false) {
-            const corsOptions = typeof options.cors === 'object' ? options.cors : {};
-            this.use(http_1.middleware.cors(corsOptions));
+        // CORS - check config enabled property OR options.security.cors.enabled === true
+        if (this.config.security.cors.enabled || options.security?.cors?.enabled === true) {
+            const corsOptions = typeof options.cors === 'object'
+                ? options.cors
+                : this.config.security.cors
+                    ? this.config.security.cors
+                    : {};
+            this.use(middleware.cors(corsOptions));
         }
-        // Helmet
-        if (options.helmet !== false) {
-            this.use(http_1.middleware.helmet());
+        // Helmet - check config enabled property OR options.security.helmet.enabled === true
+        if (this.config.security.helmet.enabled || options.security?.helmet?.enabled === true) {
+            this.use(middleware.helmet());
         }
-        // Compression
-        if (options.compression !== false) {
-            const compressionOptions = typeof options.compression === 'object' ? options.compression : {};
-            this.use(http_1.middleware.compression(compressionOptions));
+        // Compression - check config enabled property OR options.performance.compression.enabled === true
+        if (this.config.performance.compression.enabled ||
+            options.performance?.compression?.enabled === true) {
+            const compressionOptions = typeof options.compression === 'object'
+                ? options.compression
+                : this.config.performance.compression
+                    ? this.config.performance.compression
+                    : {};
+            this.use(middleware.compression(compressionOptions));
         }
         // Body size limiting
-        this.use(http_1.middleware.bodySize({ limit: '10mb' }));
+        this.use(middleware.bodySize({ limit: '10mb' }));
     }
-    autoDiscoverModules(modulesPath) {
+    // Enhanced auto-discovery initialization
+    async initializeAutoDiscovery(options) {
+        const { ModuleDiscovery } = await import('./core/modules/auto-discovery.js');
+        // Merge auto-discovery configuration
+        const autoDiscoveryConfig = this.mergeAutoDiscoveryConfig(options);
+        if (!autoDiscoveryConfig.enabled) {
+            return;
+        }
+        this.moduleDiscovery = new ModuleDiscovery(process.cwd());
         try {
-            if (!(0, fs_1.statSync)(modulesPath).isDirectory())
-                return;
-            const items = (0, fs_1.readdirSync)(modulesPath);
-            items.forEach(item => {
-                const fullPath = (0, path_1.join)(modulesPath, item);
-                if ((0, fs_1.statSync)(fullPath).isDirectory()) {
-                    const indexPath = (0, path_1.join)(fullPath, 'index.ts');
-                    try {
-                        (0, fs_1.statSync)(indexPath);
-                        // Module directory found, will be loaded later
-                        this.logger.debug(`Discovered module: ${item}`, 'ModuleDiscovery');
-                    }
-                    catch {
-                        // No index.ts, skip
-                    }
+            // Discover modules based on configuration
+            const modules = await this.moduleDiscovery.discoverModulesAdvanced(autoDiscoveryConfig);
+            // Load modules based on strategy
+            await this.loadDiscoveredModules(modules, autoDiscoveryConfig);
+            // Setup final module handler to run after user middleware (like auth)
+            this.coreFramework.setupFinalModuleHandler();
+            // Setup file watching if enabled
+            if (autoDiscoveryConfig.watchForChanges) {
+                this.moduleDiscovery.watchModulesAdvanced(autoDiscoveryConfig, async (updatedModules) => {
+                    await this.handleModuleChanges(updatedModules);
+                });
+            }
+            this.logger.info(`Auto-discovery completed: ${modules.length} modules loaded`, 'ModuleDiscovery');
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            if (autoDiscoveryConfig.failOnError) {
+                throw new Error(`Module auto-discovery failed: ${errorMsg}`);
+            }
+            else {
+                this.logger.warn(`Module auto-discovery failed: ${errorMsg}`, 'ModuleDiscovery');
+            }
+        }
+    }
+    // Merge auto-discovery configuration from multiple sources
+    mergeAutoDiscoveryConfig(options) {
+        const defaultConfig = this.config.modules.autoDiscovery;
+        // Handle legacy modulesPath option
+        if (options.modulesPath && !options.autoDiscover) {
+            return {
+                ...defaultConfig,
+                paths: [options.modulesPath],
+            };
+        }
+        // Handle boolean autoDiscover option
+        if (typeof options.autoDiscover === 'boolean') {
+            return {
+                ...defaultConfig,
+                enabled: options.autoDiscover,
+            };
+        }
+        // Handle object autoDiscover option
+        if (typeof options.autoDiscover === 'object') {
+            return {
+                ...defaultConfig,
+                ...options.autoDiscover,
+            };
+        }
+        return defaultConfig;
+    }
+    // Load discovered modules based on strategy
+    async loadDiscoveredModules(modules, config) {
+        switch (config.loadingStrategy) {
+            case 'eager':
+                // Load all modules immediately
+                for (const module of modules) {
+                    await this.loadModule(module);
+                }
+                break;
+            case 'lazy':
+                // Register modules for lazy loading
+                this.registerLazyModules(modules);
+                break;
+            case 'conditional':
+                // Load modules based on conditions
+                await this.loadConditionalModules(modules);
+                break;
+            default:
+                // Default to eager loading
+                for (const module of modules) {
+                    await this.loadModule(module);
                 }
-            });
         }
-        catch {
-            // Modules directory doesn't exist, that's fine
+    }
+    // Register modules for lazy loading
+    registerLazyModules(modules) {
+        modules.forEach(module => {
+            // Store module for lazy loading when first route is accessed
+            this.lazyModules.set(module.name, module);
+            // Register placeholder routes that trigger lazy loading
+            if (module.routes) {
+                module.routes.forEach(route => {
+                    const basePath = `/api/v${module.version}/${module.name}`;
+                    const fullPath = `${basePath}${route.path}`;
+                    // Note: Lazy loading will be implemented when route is accessed
+                    // For now, we'll store the module for later loading
+                    this.logger.debug(`Registered lazy route: ${route.method} ${fullPath}`, 'ModuleDiscovery');
+                });
+            }
+        });
+        this.logger.info(`Registered ${modules.length} modules for lazy loading`, 'ModuleDiscovery');
+    }
+    // Load modules conditionally based on environment or configuration
+    async loadConditionalModules(modules) {
+        for (const module of modules) {
+            const shouldLoad = this.shouldLoadModule(module);
+            if (shouldLoad) {
+                await this.loadModule(module);
+            }
+            else {
+                this.logger.debug(`Skipping module ${module.name} due to conditions`, 'ModuleDiscovery');
+            }
         }
     }
+    // Determine if a module should be loaded based on conditions
+    shouldLoadModule(module) {
+        const moduleConfig = module.config;
+        // Check environment conditions
+        if (moduleConfig?.conditions?.environment) {
+            const requiredEnv = moduleConfig.conditions.environment;
+            const currentEnv = process.env.NODE_ENV || 'development';
+            if (Array.isArray(requiredEnv)) {
+                if (!requiredEnv.includes(currentEnv)) {
+                    return false;
+                }
+            }
+            else if (requiredEnv !== currentEnv) {
+                return false;
+            }
+        }
+        // Check feature flags
+        if (moduleConfig?.conditions?.features) {
+            const requiredFeatures = moduleConfig.conditions.features;
+            for (const feature of requiredFeatures) {
+                if (!process.env[`FEATURE_${feature.toUpperCase()}`]) {
+                    return false;
+                }
+            }
+        }
+        // Check custom conditions
+        if (moduleConfig?.conditions?.custom) {
+            const customCondition = moduleConfig.conditions.custom;
+            if (typeof customCondition === 'function') {
+                return customCondition();
+            }
+        }
+        return true;
+    }
+    // Handle module changes during development
+    async handleModuleChanges(modules) {
+        this.logger.info('Module changes detected, reloading...', 'ModuleDiscovery');
+        // Unload existing modules (if supported)
+        // For now, just log the change
+        this.eventBus.emit('modules:changed', {
+            modules: modules.map(m => ({ name: m.name, version: m.version })),
+            timestamp: new Date(),
+        });
+    }
+    // Legacy method for backward compatibility
+    autoDiscoverModules(modulesPath) {
+        // Redirect to new system
+        this.initializeAutoDiscovery({
+            autoDiscover: {
+                enabled: true,
+                paths: [modulesPath],
+            },
+        });
+    }
     async importModule(modulePath) {
-        const module = await Promise.resolve(`${modulePath}`).then(s => __importStar(require(s)));
+        const module = await import(modulePath);
         return module.default || module;
     }
-    // Clustering support for massive performance gains with proper cleanup
+    /**
+     * Node.js Clustering Implementation
+     * This clustering algorithm is based on published research and Node.js best practices.
+     *
+     * IPC (Inter-Process Communication) Considerations:
+     * - Excessive workers create IPC bottlenecks (Source: BetterStack Node.js Guide)
+     * - Round-robin scheduling provides better load distribution (Node.js Documentation)
+     * - Message passing overhead increases significantly with worker count
+     *
+     * Memory Management:
+     * - ~2GB per worker prevents memory pressure and GC overhead
+     * - Conservative heap limits reduce memory fragmentation
+     *
+     * References:
+     * - Node.js Cluster Documentation: https://nodejs.org/api/cluster.html
+     * - BetterStack Node.js Clustering: https://betterstack.com/community/guides/scaling-nodejs/node-clustering/
+     */
     clusterWorkers = new Map();
     startWithClustering(port, host, callback) {
-        const cluster = require('cluster');
-        const os = require('os');
-        // Smart worker count calculation based on actual bottlenecks
+        // Worker count calculation - respect user choice
         let workerCount = this.config.performance?.clustering?.workers || os.cpus().length;
-        // Auto-optimize worker count based on system characteristics
-        if (workerCount === 'auto' || workerCount > 8) {
-            // For high-core machines, limit workers to prevent IPC/memory bottlenecks
+        // Only auto-optimize if user hasn't specified a number or set it to 'auto'
+        if (workerCount === 'auto') {
             const cpuCount = os.cpus().length;
             const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
-            // Optimal worker count formula based on research
-            if (cpuCount >= 16) {
-                // High-core machines: focus on memory/IPC efficiency
-                workerCount = Math.min(Math.ceil(totalMemoryGB / 2), 4); // 2GB per worker max, cap at 4
+            // Get memory per worker from config - if not set by user, calculate dynamically
+            let memoryPerWorkerGB = this.config.performance?.clustering?.memoryPerWorkerGB;
+            if (!memoryPerWorkerGB) {
+                // Dynamic calculation: (Total RAM - 4GB headroom) / CPU cores
+                const headroomGB = 4;
+                memoryPerWorkerGB = Math.max(0.5, Math.floor((totalMemoryGB - headroomGB) / cpuCount));
             }
-            else if (cpuCount >= 8) {
-                // Mid-range machines: balanced approach
-                workerCount = Math.min(cpuCount / 2, 4);
-            }
-            else {
-                // Low-core machines: use all cores
-                workerCount = cpuCount;
-            }
-            this.logger.info(`Auto-optimized workers: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB)`, 'Cluster');
+            // Conservative formula based on general guidelines:
+            // - Don't exceed CPU cores
+            // - Respect user's memory allocation preference
+            // - Let the system resources determine the limit
+            workerCount = Math.min(cpuCount, // Don't exceed CPU cores
+            Math.floor(totalMemoryGB / memoryPerWorkerGB) // User-configurable memory per worker
+            );
+            this.logger.info(`Auto-calculated worker count: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB, ${memoryPerWorkerGB}GB per worker)`, 'Cluster');
+        }
+        else if (typeof workerCount === 'number') {
+            // User specified a number - respect their choice
+            this.logger.info(`Using user-specified worker count: ${workerCount}`, 'Cluster');
         }
         if (cluster.isPrimary) {
-            this.logger.info(`🚀 Starting ${workerCount} workers for maximum performance`, 'Cluster');
+            this.logger.info(`Starting ${workerCount} workers`, 'Cluster');
             // Optimize cluster scheduling for high concurrency
-            cluster.schedulingPolicy = cluster.SCHED_RR; // Round-robin scheduling
+            // Round-robin is the default on all platforms except Windows (Node.js docs)
+            // Provides better load distribution than shared socket approach
+            cluster.schedulingPolicy = cluster.SCHED_RR;
             // Set cluster settings for better performance
             cluster.setupMaster({
-                exec: process.argv[1],
+                exec: process.argv[1] || process.execPath,
                 args: process.argv.slice(2),
                 silent: false,
             });
-            // Optimize IPC to reduce communication overhead
+            // IPC Optimization: Reduce communication overhead between master and workers
+            // Research shows excessive IPC can create bottlenecks in clustered applications
+            // (Source: BetterStack - Node.js Clustering Guide)
             process.env.NODE_CLUSTER_SCHED_POLICY = 'rr'; // Ensure round-robin
-            process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size
+            process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size by disabling color codes
             // Graceful shutdown handler
             const gracefulShutdown = () => {
                 this.logger.info('Gracefully shutting down cluster...', 'Cluster');
@@ -867,27 +1158,25 @@ class Moro extends events_1.EventEmitter {
             // Handle process signals for graceful shutdown
             process.on('SIGINT', gracefulShutdown);
             process.on('SIGTERM', gracefulShutdown);
-            // Fork workers with proper tracking and CPU affinity
+            // Fork workers with basic tracking
             for (let i = 0; i < workerCount; i++) {
-                const worker = cluster.fork({
-                    WORKER_ID: i,
-                    WORKER_CPU_AFFINITY: i % os.cpus().length, // Distribute workers across CPUs
-                });
+                const worker = cluster.fork();
                 this.clusterWorkers.set(worker.process.pid, worker);
-                this.logger.info(`Worker ${worker.process.pid} started (CPU ${i % os.cpus().length})`, 'Cluster');
-                // Handle individual worker messages (reuse handler)
+                this.logger.info(`Worker ${worker.process.pid} started`, 'Cluster');
+                // Handle individual worker messages
                 worker.on('message', this.handleWorkerMessage.bind(this));
             }
-            // Handle worker exits with cleanup
+            // Simple worker exit handling
             cluster.on('exit', (worker, code, signal) => {
-                // Clean up worker tracking
-                this.clusterWorkers.delete(worker.process.pid);
-                this.logger.warn(`Worker ${worker.process.pid} died (${signal || code}). Restarting...`, 'Cluster');
-                // Restart worker with proper tracking
-                const newWorker = cluster.fork();
-                this.clusterWorkers.set(newWorker.process.pid, newWorker);
-                newWorker.on('message', this.handleWorkerMessage.bind(this));
-                this.logger.info(`Worker ${newWorker.process.pid} started`, 'Cluster');
+                const pid = worker.process.pid;
+                this.clusterWorkers.delete(pid);
+                if (code !== 0 && !worker.exitedAfterDisconnect) {
+                    this.logger.warn(`Worker ${pid} died unexpectedly (${signal || code}). Restarting...`, 'Cluster');
+                    // Simple restart
+                    const newWorker = cluster.fork();
+                    this.clusterWorkers.set(newWorker.process.pid, newWorker);
+                    this.logger.info(`Worker ${newWorker.process.pid} restarted`, 'Cluster');
+                }
             });
             // Master process callback
             if (callback)
@@ -899,15 +1188,24 @@ class Moro extends events_1.EventEmitter {
             // Worker-specific optimizations for high concurrency
             process.env.UV_THREADPOOL_SIZE = '64';
             // Reduce logging contention in workers (major bottleneck)
-            if (this.config.logging) {
-                // Workers log less frequently to reduce I/O contention
-                this.config.logging.level = 'warn'; // Only warnings and errors
+            // Multiple workers writing to same log files creates I/O contention
+            // ONLY reduce log level if user didn't explicitly set one
+            if (!this.userSetLogger) {
+                // Workers log less frequently to reduce I/O contention (only if not explicitly configured)
+                applyLoggingConfiguration(undefined, { level: 'warn' }); // Only warnings and errors
             }
-            // Memory optimization for workers
-            process.env.NODE_OPTIONS = '--max-old-space-size=1024'; // Limit memory per worker
-            // Optimize V8 flags for better performance (Rust-level optimizations)
+            // Research-based memory optimization for workers
+            const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
+            const workerCount = Object.keys(cluster.workers || {}).length || 1;
+            // Conservative memory allocation
+            const heapSizePerWorkerMB = Math.min(Math.floor(((totalMemoryGB * 1024) / workerCount) * 0.8), // 80% of available memory
+            1536 // Cap at 1.5GB (GC efficiency threshold from research)
+            );
+            process.env.NODE_OPTIONS = `--max-old-space-size=${heapSizePerWorkerMB}`;
+            this.logger.debug(`Worker memory allocated: ${heapSizePerWorkerMB}MB heap (${workerCount} workers, ${totalMemoryGB.toFixed(1)}GB total)`, 'Worker');
+            // Optimize V8 flags for better performance
             if (process.env.NODE_ENV === 'production') {
-                // Ultra-aggressive V8 optimizations for maximum performance
+                // Aggressive V8 optimizations for maximum performance
                 const v8Flags = [
                     '--optimize-for-size', // Trade memory for speed
                     '--always-opt', // Always optimize functions
@@ -960,14 +1258,27 @@ class Moro extends events_1.EventEmitter {
             catch (error) {
                 // Documentation not enabled, that's fine
             }
-            // Add intelligent routing middleware
+            // Add unified routing middleware (handles both chainable and direct routes)
+            // Optimized: call router without extra async wrapper when possible
             this.coreFramework.addMiddleware(async (req, res, next) => {
-                const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
-                if (!handled) {
-                    next();
+                // Try unified router first (handles all route types)
+                const handled = this.unifiedRouter.handleRequest(req, res);
+                // Check if it's a promise (async route) or sync (fast-path)
+                if (handled && typeof handled.then === 'function') {
+                    // Async - await the result
+                    const isHandled = await handled;
+                    if (!isHandled) {
+                        next();
+                    }
+                }
+                else {
+                    // Sync - check immediately
+                    if (!handled) {
+                        next();
+                    }
                 }
             });
-            // Register direct routes
+            // Register legacy direct routes with the HTTP server (for backward compatibility)
             if (this.routes.length > 0) {
                 this.registerDirectRoutes();
             }
@@ -980,15 +1291,36 @@ class Moro extends events_1.EventEmitter {
                     worker: process.pid,
                 });
             };
-            if (host) {
-                this.coreFramework.listen(port, host, workerCallback);
-            }
-            else {
-                this.coreFramework.listen(port, workerCallback);
-            }
+            // Ensure WebSocket setup is complete before starting worker
+            this.processQueuedWebSocketRegistrations()
+                .then(() => {
+                if (host) {
+                    this.coreFramework.listen(port, host, workerCallback);
+                }
+                else {
+                    this.coreFramework.listen(port, workerCallback);
+                }
+            })
+                .catch(error => {
+                this.logger.error('WebSocket initialization failed in worker', 'Worker', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                // For WebSocket failures with queued registrations, error will propagate
+                if (error instanceof Error &&
+                    error.message.includes('WebSocket features require a WebSocket adapter')) {
+                    throw error;
+                }
+                // Start anyway for other errors
+                if (host) {
+                    this.coreFramework.listen(port, host, workerCallback);
+                }
+                else {
+                    this.coreFramework.listen(port, workerCallback);
+                }
+            });
         }
     }
-    // Reusable worker message handler (avoids creating new functions)
+    // Simple worker message handler
     handleWorkerMessage(message) {
         // Handle inter-worker communication if needed
         if (message.type === 'health-check') {
@@ -998,32 +1330,81 @@ class Moro extends events_1.EventEmitter {
         // Log other worker messages
         this.logger.debug(`Worker message: ${JSON.stringify(message)}`, 'Cluster');
     }
+    /**
+     * 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...');
+        // Flush logger buffer before shutdown
+        try {
+            // Use flushBuffer for immediate synchronous flush
+            this.logger.flushBuffer();
+        }
+        catch (error) {
+            // Ignore flush errors during shutdown
+        }
+        // Close the core framework with timeout
+        if (this.coreFramework && this.coreFramework.httpServer) {
+            try {
+                await Promise.race([
+                    new Promise(resolve => {
+                        this.coreFramework.httpServer.close(() => {
+                            resolve();
+                        });
+                    }),
+                    new Promise(resolve => setTimeout(resolve, 2000)), // 2 second timeout
+                ]);
+            }
+            catch (error) {
+                // Force close if graceful close fails
+                this.logger.warn('Force closing HTTP server due to timeout');
+            }
+        }
+        // Clean up module discovery watchers
+        if (this.moduleDiscovery && typeof this.moduleDiscovery.cleanup === 'function') {
+            try {
+                this.moduleDiscovery.cleanup();
+            }
+            catch (error) {
+                // Ignore cleanup errors
+            }
+        }
+        // Clean up event listeners
+        try {
+            this.eventBus.removeAllListeners();
+            this.removeAllListeners();
+        }
+        catch (error) {
+            // Ignore cleanup errors
+        }
+        this.logger.debug('Moro application closed successfully');
+    }
 }
-exports.Moro = Moro;
 // Export convenience function
-function createApp(options) {
+export function createApp(options) {
     return new Moro(options);
 }
 // Runtime-specific convenience functions
-function createAppNode(options) {
+export function createAppNode(options) {
     return new Moro({
         ...options,
         runtime: { type: 'node' },
     });
 }
-function createAppEdge(options) {
+export function createAppEdge(options) {
     return new Moro({
         ...options,
         runtime: { type: 'vercel-edge' },
     });
 }
-function createAppLambda(options) {
+export function createAppLambda(options) {
     return new Moro({
         ...options,
         runtime: { type: 'aws-lambda' },
     });
 }
-function createAppWorker(options) {
+export function createAppWorker(options) {
     return new Moro({
         ...options,
         runtime: { type: 'cloudflare-workers' },