@morojs/moro 1.5.16 → 1.6.0

package/src/moro.ts

@@ -1,34 +1,40 @@
 // Moro Framework - Modern TypeScript API Framework
 // Built for developers who demand performance, elegance, and zero compromises
 // Event-driven • Modular • Enterprise-ready • Developer-first
-import { Moro as MoroCore } from './core/framework';
-import { HttpRequest, HttpResponse, middleware } from './core/http';
-import { ModuleConfig, InternalRouteDefinition } from './types/module';
-import { MoroOptions } from './types/core';
-import { ModuleDefaultsConfig } from './types/config';
-import { MoroEventBus } from './core/events';
-import { createFrameworkLogger, applyLoggingConfiguration } from './core/logger';
-import { Logger } from './types/logger';
-import { MiddlewareManager } from './core/middleware';
-import { IntelligentRoutingManager } from './core/routing/app-integration';
-import { RouteBuilder, RouteSchema, CompiledRoute } from './core/routing';
-import { AppDocumentationManager, DocsConfig } from './core/docs';
+import { Moro as MoroCore } from './core/framework.js';
+import { HttpRequest, HttpResponse, middleware } from './core/http/index.js';
+import { ModuleConfig, InternalRouteDefinition } from './types/module.js';
+import { MoroOptions } from './types/core.js';
+import { ModuleDefaultsConfig } from './types/config.js';
+import { MoroEventBus } from './core/events/index.js';
+import { createFrameworkLogger, applyLoggingConfiguration } from './core/logger/index.js';
+import { Logger } from './types/logger.js';
+import { MiddlewareManager } from './core/middleware/index.js';
+import { IntelligentRoutingManager } from './core/routing/app-integration.js';
+import { RouteBuilder, RouteSchema, CompiledRoute } from './core/routing/index.js';
+import { AppDocumentationManager, DocsConfig } 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
-import { initializeConfig, type AppConfig } from './core/config';
+import { initializeConfig, type AppConfig } from './core/config/index.js';
 // Runtime System Integration
-import { RuntimeAdapter, RuntimeType, createRuntimeAdapter } from './core/runtime';
+import { RuntimeAdapter, RuntimeType, createRuntimeAdapter } from './core/runtime/index.js';
 
 export class Moro extends EventEmitter {
-  private coreFramework: MoroCore;
+  private coreFramework!: MoroCore;
   private routes: InternalRouteDefinition[] = [];
   private moduleCounter = 0;
   private loadedModules = new Set<string>();
   private lazyModules = new Map<string, ModuleConfig>();
   private routeHandlers: Record<string, Function> = {};
   private moduleDiscovery?: any; // Store for cleanup
+  private autoDiscoveryOptions: MoroOptions | null = null;
+  private autoDiscoveryInitialized = false;
+  private autoDiscoveryPromise: Promise<void> | null = null;
   // Enterprise event system integration
-  private eventBus: MoroEventBus;
+  private eventBus!: MoroEventBus;
   // Application logger
   private logger!: Logger;
   // Intelligent routing system
@@ -36,12 +42,18 @@ export class Moro extends EventEmitter {
   // Documentation system
   private documentation = new AppDocumentationManager();
   // Configuration system
-  private config: AppConfig;
+  private config!: AppConfig;
   // Runtime system
-  private runtimeAdapter: RuntimeAdapter;
-  private runtimeType: RuntimeType;
+  private runtimeAdapter!: RuntimeAdapter;
+  private runtimeType!: RuntimeType;
   // Middleware system
-  private middlewareManager: MiddlewareManager;
+  private middlewareManager!: MiddlewareManager;
+  // Queued WebSocket registrations (for async adapter detection)
+  private queuedWebSocketRegistrations: Array<{
+    namespace: string;
+    handlers: Record<string, Function>;
+    processed: boolean;
+  }> = [];
 
   constructor(options: MoroOptions = {}) {
     super(); // Call EventEmitter constructor
@@ -85,7 +97,11 @@ export class Moro extends EventEmitter {
     const frameworkOptions: any = {
       ...options,
       logger: this.config.logging,
-      websocket: this.config.websocket.enabled ? options.websocket || {} : false,
+      // 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,
     };
 
@@ -118,15 +134,10 @@ export class Moro extends EventEmitter {
       ...options,
     });
 
-    // Auto-discover modules if enabled
-    if (options.autoDiscover !== false) {
-      // Initialize auto-discovery asynchronously
-      this.initializeAutoDiscovery(options).catch(error => {
-        this.logger.error('Auto-discovery initialization failed', 'Framework', {
-          error: error instanceof Error ? error.message : String(error),
-        });
-      });
-    }
+    // 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', {
@@ -355,6 +366,13 @@ export class Moro extends 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;
   }
 
@@ -370,34 +388,45 @@ export class Moro extends EventEmitter {
 
   // WebSocket helper with events
   websocket(namespace: string, handlers: Record<string, Function>) {
+    // 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;
+  }
+
+  private processWebSocketRegistration(
+    namespace: string,
+    handlers: Record<string, Function>,
+    adapter: any
+  ) {
     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: any) => {
         this.emit('websocket:connection', { namespace, event, socket });
 
-        socket.on(event, (data, callback) => {
+        socket.on(event, (data: any, callback: any) => {
           this.emit('websocket:event', { namespace, event, data });
 
           Promise.resolve(handler(socket, data))
-            .then(result => {
+            .then((result: any) => {
               this.emit('websocket:response', { namespace, event, result });
               if (callback) callback(result);
               else if (result) socket.emit(`${event}:response`, result);
             })
-            .catch(error => {
+            .catch((error: any) => {
               this.emit('websocket:error', { namespace, event, error });
               const errorResponse = { success: false, error: error.message };
               if (callback) callback(errorResponse);
@@ -408,7 +437,40 @@ export class Moro extends EventEmitter {
     });
 
     this.emit('websocket:registered', { namespace, handlers });
-    return this;
+  }
+
+  private 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;
+        }
+      }
+    }
   }
 
   // Start server with events (Node.js only)
@@ -464,9 +526,21 @@ export class Moro extends EventEmitter {
     }
 
     // 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 as string, 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 as string, callback);
+        return;
+      }
     }
     this.eventBus.emit('server:starting', { port, runtime: this.runtimeType });
 
@@ -496,35 +570,169 @@ export class Moro extends EventEmitter {
       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');
-      if (this.config.websocket.enabled) {
-        this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
-      }
-      this.logger.info('Learn more at https://morojs.com', '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 intelligent routes info
+        const intelligentRoutes = this.intelligentRouting.getIntelligentRoutes();
+        if (intelligentRoutes.length > 0) {
+          this.logger.info(`Intelligent Routes: ${intelligentRoutes.length} registered`, 'Server');
+        }
+
+        this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
+        if (callback) callback();
+      };
 
-      // Log intelligent routes info
-      const intelligentRoutes = this.intelligentRouting.getIntelligentRoutes();
-      if (intelligentRoutes.length > 0) {
-        this.logger.info(`Intelligent Routes: ${intelligentRoutes.length} registered`, 'Server');
+      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();
+    // 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(): Promise<void> {
+    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?: {
+    paths?: string[];
+    patterns?: string[];
+    recursive?: boolean;
+    loadingStrategy?: 'eager' | 'lazy' | 'conditional';
+    watchForChanges?: boolean;
+    ignorePatterns?: string[];
+    loadOrder?: 'alphabetical' | 'dependency' | 'custom';
+    failOnError?: boolean;
+    maxDepth?: number;
+  }): void {
+    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;
+    }
+
+    // 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' as const),
+        watchForChanges: options?.watchForChanges ?? false,
+        ignorePatterns: options?.ignorePatterns || [
+          '**/*.test.{ts,js}',
+          '**/*.spec.{ts,js}',
+          '**/node_modules/**',
+        ],
+        loadOrder: options?.loadOrder || ('dependency' as const),
+        failOnError: options?.failOnError ?? false,
+        maxDepth: options?.maxDepth ?? 5,
+      },
     };
 
-    if (host && typeof host === 'string') {
-      this.coreFramework.listen(port, host, actualCallback);
-    } else {
-      this.coreFramework.listen(port, actualCallback);
+    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
+  private async ensureAutoDiscoveryComplete(): Promise<void> {
+    // 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
+  private async performAutoDiscovery(optionsOverride?: MoroOptions): Promise<void> {
+    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: HttpRequest, res: HttpResponse) => {
       // Add documentation middleware first (if enabled)
@@ -769,7 +977,6 @@ export class Moro extends EventEmitter {
               req.body = validated;
             } catch (error: any) {
               // Handle universal validation errors
-              const { normalizeValidationError } = require('./core/validation/schema-interface');
               const normalizedError = normalizeValidationError(error);
               res.status(400).json({
                 success: false,
@@ -884,7 +1091,7 @@ export class Moro extends EventEmitter {
 
   // Enhanced auto-discovery initialization
   private async initializeAutoDiscovery(options: MoroOptions): Promise<void> {
-    const { ModuleDiscovery } = await import('./core/modules/auto-discovery');
+    const { ModuleDiscovery } = await import('./core/modules/auto-discovery.js');
 
     // Merge auto-discovery configuration
     const autoDiscoveryConfig = this.mergeAutoDiscoveryConfig(options);
@@ -902,6 +1109,9 @@ export class Moro extends EventEmitter {
       // 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(
@@ -1116,9 +1326,6 @@ export class Moro extends EventEmitter {
   private clusterWorkers = new Map<number, any>();
 
   private startWithClustering(port: number, host?: string, callback?: () => void): void {
-    const cluster = require('cluster');
-    const os = require('os');
-
     // Worker count calculation - respect user choice
     let workerCount = this.config.performance?.clustering?.workers || os.cpus().length;
 
@@ -1239,9 +1446,8 @@ export class Moro extends EventEmitter {
       }
 
       // Research-based memory optimization for workers
-      const os = require('os');
       const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
-      const workerCount = Object.keys(require('cluster').workers || {}).length || 1;
+      const workerCount = Object.keys(cluster.workers || {}).length || 1;
 
       // Conservative memory allocation
       const heapSizePerWorkerMB = Math.min(
@@ -1342,11 +1548,33 @@ export class Moro extends EventEmitter {
         });
       };
 
-      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);
+          }
+        });
     }
   }
 

package/src/types/config.ts

@@ -12,6 +12,12 @@ export interface ServerConfig {
   errorBoundary: {
     enabled: boolean;
   };
+  useUWebSockets?: boolean; // Enable uWebSockets for both HTTP and WebSocket
+  ssl?: {
+    key_file_name?: string;
+    cert_file_name?: string;
+    passphrase?: string;
+  };
 }
 
 export interface ServiceDiscoveryConfig {
@@ -187,7 +193,7 @@ export interface PerformanceConfig {
 
 export interface WebSocketConfig {
   enabled: boolean;
-  adapter?: string | 'socket.io' | 'ws';
+  adapter?: string | 'socket.io' | 'ws' | 'uws';
   compression?: boolean;
   customIdGenerator?: () => string;
   options?: {
@@ -197,6 +203,12 @@ export interface WebSocketConfig {
     };
     path?: string;
     maxPayloadLength?: number;
+    idleTimeout?: number;
+    ssl?: {
+      key_file_name?: string;
+      cert_file_name?: string;
+      passphrase?: string;
+    };
   };
 }
 

package/src/types/core.ts

@@ -1,7 +1,7 @@
 // Core Framework Types
-import { RuntimeConfig } from './runtime';
-import { LogLevel, LoggerOptions } from './logger';
-import { AppConfig } from './config';
+import { RuntimeConfig } from './runtime.js';
+import { LogLevel, LoggerOptions } from './logger.js';
+import { AppConfig } from './config.js';
 
 export interface MoroOptions {
   autoDiscover?:

package/src/types/hooks.ts

@@ -1,5 +1,5 @@
 // Hooks and Middleware Types
-import { HttpRequest, HttpResponse } from './http';
+import { HttpRequest, HttpResponse } from '../core/http/index.js';
 
 export type HookFunction = (...args: any[]) => Promise<any> | any;
 

package/src/types/runtime.ts

@@ -1,5 +1,5 @@
 // Runtime abstraction types for multi-environment support
-import { HttpRequest, HttpResponse } from './http';
+import { HttpRequest, HttpResponse } from '../core/http/index.js';
 
 export type RuntimeType = 'node' | 'vercel-edge' | 'aws-lambda' | 'cloudflare-workers';
 

package/tsconfig.json

@@ -2,7 +2,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "commonjs",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "lib": ["ES2022"],
     "outDir": "./dist",
     "rootDir": "./src",
@@ -14,7 +15,8 @@
     "emitDecoratorMetadata": true,
     "resolveJsonModule": true,
     "declaration": true,
-    "sourceMap": true
+    "sourceMap": true,
+    "isolatedModules": true
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]