@asenajs/hono-adapter 1.1.0 → 1.2.0

package/dist/lib/HonoAdapter.js

@@ -1,8 +1,10 @@
 import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
 import * as bun from 'bun';
 import { HonoContextWrapper } from './HonoContextWrapper';
 import { AsenaAdapter, VALIDATOR_METHODS, } from '@asenajs/asena/adapter';
-import { green, yellow } from '@asenajs/asena/logger';
+import { shouldApplyMiddleware } from '@asenajs/asena/utils/patternMatcher';
+import { blue, green, red, yellow } from '@asenajs/asena/logger';
 import { zValidator } from '@hono/zod-validator';
 import { middlewareParser } from './utils/middlewareParser';
 import { HttpMethod } from '@asenajs/asena/web-types';
@@ -14,6 +16,19 @@ export class HonoAdapter extends AsenaAdapter {
     server;
     // @ts-ignore
     options = {};
+    // Deferred route registration
+    routeQueue = [];
+    /**
+     * WebSocket route queue for deferred registration
+     * WebSocket routes are queued during initialization and registered when server starts
+     */
+    wsRouteQueue = [];
+    /**
+     * Global middlewares with optional path filtering configuration
+     * Middlewares are stored with their pattern config and applied during route registration
+     */
+    globalMiddlewares = [];
+    routesRegistered = false;
     methodMap = {
         [HttpMethod.GET]: (path, ...handlers) => this.app.get(path, ...handlers),
         [HttpMethod.POST]: (path, ...handlers) => this.app.post(path, ...handlers),
@@ -35,48 +50,62 @@ export class HonoAdapter extends AsenaAdapter {
             this.websocketAdapter.logger = this.logger;
         }
     }
-    use(middleware, path) {
-        const normalizedPath = path ? this.normalizePath(path) : undefined;
-        const preparedMiddlewares = this.prepareMiddlewares([middleware]);
-        if (normalizedPath) {
-            this.app.use(normalizedPath, ...preparedMiddlewares);
-            return;
-        }
-        this.app.use(...preparedMiddlewares);
+    /**
+     * Registers a global middleware with optional path filtering
+     *
+     * Middlewares are stored and applied during route registration based on include/exclude patterns.
+     * This enables zero-runtime-overhead pattern matching.
+     *
+     * @param middleware - The middleware to register globally
+     * @param config - Optional path filtering configuration with include/exclude patterns
+     *
+     * @example
+     * ```typescript
+     * // Apply to all routes
+     * adapter.use(authMiddleware);
+     *
+     * // Apply only to specific patterns
+     * adapter.use(authMiddleware, {
+     *   include: ['/api/*', '/admin/*'],
+     *   exclude: ['/api/health']
+     * });
+     *
+     * // Apply to all except specific patterns
+     * adapter.use(rateLimitMiddleware, {
+     *   exclude: ['/health', '/metrics']
+     * });
+     * ```
+     */
+    use(middleware, config) {
+        // Store middleware with config for deferred application during route registration
+        this.globalMiddlewares.push({ middleware, config });
     }
-    async registerRoute({ method, path, middlewares, handler, staticServe, validator, }) {
-        const prepareMiddlewares = this.prepareMiddlewares(middlewares);
-        const allMiddlewares = validator
-            ? [...(await this.prepareValidator(validator)), ...prepareMiddlewares]
-            : prepareMiddlewares;
-        const methodHandler = this.methodMap[method];
-        if (!methodHandler) {
-            throw new Error('Invalid method');
-        }
-        if (staticServe) {
-            methodHandler(path, ...allMiddlewares, serveStatic(this.prepareStaticServeOptions(staticServe)));
-            this.logger.info(`${green('Successfully')} registered ${yellow('Static Serve ' + method.toUpperCase())} route for PATH: ${green(`${path}`)}`);
-            return;
-        }
-        const routeHandler = [...allMiddlewares, this.prepareHandler(handler)];
-        methodHandler(path, ...routeHandler);
-        this.logger.info(`${green('Successfully')} registered ${yellow(method.toUpperCase())} route for PATH: ${green(`${path}`)}`);
+    async registerRoute(params) {
+        // Queue the route for deferred registration
+        this.routeQueue.push(params);
     }
-    registerWebsocketRoute({ path, websocketService, middlewares, }) {
-        const preparedMiddlewares = this.prepareMiddlewares(middlewares);
-        this.app.get(`/${path}`, ...preparedMiddlewares, async (c, next) => {
-            const websocketData = c.get('_websocketData') || {};
-            const id = bun.randomUUIDv7();
-            const data = { values: websocketData, id, path: path };
-            const upgradeResult = this.server.upgrade(c.req.raw, { data });
-            if (upgradeResult) {
-                return new Response(null);
-            }
-            await next(); // Failed
-        });
-        this.websocketAdapter.registerWebSocket(websocketService);
+    /**
+     * Registers a WebSocket route (deferred registration)
+     *
+     * Routes are queued and will be registered when the server starts.
+     * This allows for controller-based logging and optimization.
+     *
+     * @param params - WebSocket route parameters
+     */
+    registerWebsocketRoute(params) {
+        // Queue WebSocket route for building during start()
+        this.wsRouteQueue.push(params);
+        // Also register WebSocket service with adapter for namespace tracking
+        if (this.websocketAdapter && params.websocketService) {
+            this.websocketAdapter.registerWebSocket(params.websocketService);
+        }
     }
     async start() {
+        // Register all queued routes with optimization
+        if (!this.routesRegistered) {
+            await this.optimizeAndRegisterRoutes();
+            this.routesRegistered = true;
+        }
         this.websocketAdapter.prepareWebSocket(this.options?.wsOptions);
         this.server = bun.serve({
             ...this.options.serveOptions,
@@ -85,11 +114,80 @@ export class HonoAdapter extends AsenaAdapter {
             websocket: this.websocketAdapter.websocket,
         });
         this.websocketAdapter.startWebsocket(this.server);
+        // Log controller-based route information
+        if (this.routeQueue.length > 0 || this.wsRouteQueue.length > 0) {
+            this.logger.info(this.buildControllerBasedLog());
+        }
+        this.logger.info(`Server running at http://localhost:${this.server.port}`);
         return this.server;
     }
+    /**
+     * Registers global error handler with enhanced error handling capabilities
+     *
+     * Supports Hono's HTTPException for proper status code handling:
+     * - HTTPException instances are passed to user handler for custom handling
+     * - If user handler returns a response, it's used
+     * - Otherwise, HTTPException's default response is returned
+     * - Other errors follow normal error handling flow
+     *
+     * @param errorHandler - Custom error handler function
+     *
+     * @example
+     * ```typescript
+     * adapter.onError((error, context) => {
+     *   // HTTPException handling (optional custom behavior)
+     *   if (error instanceof HTTPException) {
+     *     // Add custom logging or return custom response
+     *     return context.send({ custom: 'response' }, error.status);
+     *   }
+     *
+     *   // Other errors
+     *   return context.send({ error: 'Internal error' }, 500);
+     * });
+     * ```
+     */
     onError(errorHandler) {
         this.app.onError((error, context) => {
-            return errorHandler(error, new HonoContextWrapper(context));
+            // Log error with full details
+            this.logger.error('Application error occurred:', {
+                message: error.message,
+                stack: error.stack,
+                path: context.req.path,
+                method: context.req.method,
+                timestamp: new Date().toISOString(),
+            });
+            // Wrap context for user handler
+            const wrapper = new HonoContextWrapper(context);
+            // Handle HTTPException with Hono's standard pattern
+            if (error instanceof HTTPException) {
+                try {
+                    // Allow user to customize HTTPException handling
+                    const customResponse = errorHandler(error, wrapper);
+                    // If user returned a response, use it
+                    if (customResponse) {
+                        return customResponse;
+                    }
+                }
+                catch (handlerError) {
+                    // User handler failed, log and fallback to HTTPException's default response
+                    this.logger.error('Error handler threw an error for HTTPException, using default response:', handlerError);
+                }
+                // Return HTTPException's default response (proper status code + message)
+                return error.getResponse();
+            }
+            // Handle other errors through user-defined handler
+            try {
+                return errorHandler(error, wrapper);
+            }
+            catch (handlerError) {
+                // Fallback if error handler itself throws
+                this.logger.error('Error handler threw an error:', handlerError);
+                return context.json({
+                    error: 'Internal server error',
+                    message: process.env.NODE_ENV === 'production' ? 'An unexpected error occurred' : error.message,
+                    timestamp: new Date().toISOString(),
+                }, 500);
+            }
         });
     }
     async serveOptions(options) {
@@ -104,6 +202,11 @@ export class HonoAdapter extends AsenaAdapter {
     prepareHandler(handler) {
         return (c) => handler(new HonoContextWrapper(c));
     }
+    /**
+     * Prepares static serve options with enhanced features
+     * @param staticServe - Base static serve parameters
+     * @returns Configured static serve options for Hono
+     */
     prepareStaticServeOptions(staticServe) {
         let staticServeOptions = {
             root: staticServe.root,
@@ -117,11 +220,42 @@ export class HonoAdapter extends AsenaAdapter {
                 staticServeOptions.onFound = staticServe.onFound.handler;
             }
             else {
-                staticServeOptions.onFound = (path, c) => {
-                    staticServe.onFound.handler(path, new HonoContextWrapper(c));
+                staticServeOptions.onFound = async (path, c) => {
+                    // Add cache headers and custom headers
+                    if (staticServe.extra?.cacheControl) {
+                        c.header('Cache-Control', staticServe.extra.cacheControl);
+                    }
+                    else {
+                        // Default cache control for static files
+                        c.header('Cache-Control', 'public, max-age=31536000');
+                    }
+                    // Add custom headers if provided
+                    if (staticServe.extra?.headers) {
+                        Object.entries(staticServe.extra.headers).forEach(([key, value]) => {
+                            c.header(key, value);
+                        });
+                    }
+                    // Call user callback
+                    await staticServe.onFound.handler(path, new HonoContextWrapper(c));
                 };
             }
         }
+        else if (staticServe.extra?.cacheControl || staticServe.extra?.headers) {
+            // Add default onFound handler if cache or custom headers are specified
+            staticServeOptions.onFound = (_path, c) => {
+                if (staticServe.extra?.cacheControl) {
+                    c.header('Cache-Control', staticServe.extra.cacheControl);
+                }
+                else {
+                    c.header('Cache-Control', 'public, max-age=31536000');
+                }
+                if (staticServe.extra?.headers) {
+                    Object.entries(staticServe.extra.headers).forEach(([key, value]) => {
+                        c.header(key, value);
+                    });
+                }
+            };
+        }
         if (staticServe.onNotFound) {
             if (staticServe.onNotFound.override) {
                 // @ts-ignore
@@ -139,33 +273,465 @@ export class HonoAdapter extends AsenaAdapter {
         }
         return staticServeOptions;
     }
+    /**
+     * Prepares validation middleware with enhanced error handling
+     * @param baseValidator - The validator to prepare
+     * @returns Array of Hono middleware handlers for validation
+     */
     async prepareValidator(baseValidator) {
         if (!baseValidator) {
             return [];
         }
         const validators = [];
         for (const key of VALIDATOR_METHODS) {
-            // if the key is not a validator method, skip
-            if (typeof baseValidator[key]?.handle !== 'function') {
+            const validatorHandler = baseValidator[key];
+            // Skip if not a valid validator
+            if (!validatorHandler || typeof validatorHandler.handle !== 'function') {
                 continue;
             }
-            const validator = baseValidator[key];
-            const validationSchema = await validator.handle();
-            let schema;
-            let hook;
-            if ('schema' in validationSchema) {
-                schema = validationSchema['schema'];
-                hook = validationSchema['hook'];
+            try {
+                const validationSchema = await validatorHandler.handle();
+                // Validate that we got a valid schema
+                if (!validationSchema) {
+                    this.logger.warn(`Validator for '${key}' returned null/undefined, skipping`);
+                    continue;
+                }
+                let schema;
+                let hook;
+                if (typeof validationSchema === 'object' && 'schema' in validationSchema) {
+                    schema = validationSchema.schema;
+                    hook = validationSchema.hook;
+                    // Validate schema is actually a Zod schema
+                    if (!schema || typeof schema.parse !== 'function') {
+                        throw new Error(`Invalid Zod schema provided for '${key}' validator`);
+                    }
+                }
+                else {
+                    schema = validationSchema;
+                    if (!schema || typeof schema.parse !== 'function') {
+                        throw new Error(`Invalid Zod schema provided for '${key}' validator`);
+                    }
+                }
+                // Create validator with proper error handling
+                const validator = zValidator(key, schema, hook ||
+                    ((result, c) => {
+                        // Default hook with better error formatting
+                        if (!result.success) {
+                            return c.json({
+                                error: 'Validation failed',
+                                details: result.error.flatten(),
+                                target: key,
+                            }, 400);
+                        }
+                    }));
+                validators.push(validator);
             }
-            else {
-                schema = validationSchema;
+            catch (error) {
+                this.logger.error(`Failed to prepare validator for '${key}':`, error);
+                throw new Error(`Validator preparation failed for '${key}': ${error instanceof Error ? error.message : String(error)}`);
             }
-            validators.push(zValidator(key, schema, hook));
         }
         return validators;
     }
-    normalizePath(path) {
-        return `${path.endsWith('/') ? path : `${path}/`}*`;
+    /**
+     * Gets global middlewares that should be applied to a specific path
+     *
+     * Filters global middlewares based on their include/exclude patterns.
+     * Pattern matching happens once during route registration (zero runtime overhead).
+     *
+     * @param path - The route path to check against middleware patterns
+     * @returns Array of middlewares that should be applied to this path
+     *
+     * @example
+     * ```typescript
+     * // If global middlewares are:
+     * // - authMiddleware with { include: ['/api/*'], exclude: ['/api/health'] }
+     * // - rateLimitMiddleware with no config
+     *
+     * getGlobalMiddlewaresForPath('/api/users')    // => [authMiddleware, rateLimitMiddleware]
+     * getGlobalMiddlewaresForPath('/api/health')   // => [rateLimitMiddleware]
+     * getGlobalMiddlewaresForPath('/public/file')  // => [rateLimitMiddleware]
+     * ```
+     */
+    getGlobalMiddlewaresForPath(path) {
+        return this.globalMiddlewares
+            .filter(({ config }) => shouldApplyMiddleware(path, config))
+            .map(({ middleware }) => middleware);
+    }
+    /**
+     * Extracts base path from a route path
+     * Examples:
+     * - "/api/users/:id" -> "/api/users"
+     * - "/users" -> "/users"
+     * - "/" -> "/"
+     */
+    extractBasePath(path) {
+        // Remove trailing slash
+        let normalized = path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
+        // Find the last segment without parameters
+        const segments = normalized.split('/');
+        const baseSegments = [];
+        for (const segment of segments) {
+            if (segment.startsWith(':') || segment.includes('*')) {
+                break;
+            }
+            baseSegments.push(segment);
+        }
+        return baseSegments.join('/') || '/';
+    }
+    /**
+     * Groups routes by their base path
+     * Returns a map of base path -> routes with that base path
+     */
+    groupRoutesByBasePath(routes) {
+        const groups = new Map();
+        for (const route of routes) {
+            const basePath = this.extractBasePath(route.path);
+            if (!groups.has(basePath)) {
+                groups.set(basePath, []);
+            }
+            groups.get(basePath).push(route);
+        }
+        return groups;
+    }
+    /**
+     * Finds common middlewares across all routes in a group
+     * Returns middlewares that appear in ALL routes
+     */
+    extractCommonMiddlewares(routes) {
+        if (routes.length === 0)
+            return [];
+        if (routes.length === 1)
+            return [];
+        // Get middleware from first route
+        const firstRouteMiddlewares = routes[0].middlewares || [];
+        // Find middlewares that exist in all routes
+        return firstRouteMiddlewares.filter((middleware) => {
+            return routes.every((route) => {
+                return (route.middlewares || []).some((mw) => {
+                    // Compare by constructor name (class identity)
+                    return mw.constructor.name === middleware.constructor.name;
+                });
+            });
+        });
+    }
+    /**
+     * Registers routes to Hono app with optimization
+     * Groups routes by base path and applies common middlewares at group level
+     * Also registers WebSocket routes
+     */
+    async optimizeAndRegisterRoutes() {
+        // Register HTTP routes
+        if (this.routeQueue.length > 0) {
+            // Group routes by base path
+            const routeGroups = this.groupRoutesByBasePath(this.routeQueue);
+            for (const [basePath, routes] of routeGroups) {
+                // Find common middlewares for this group
+                const commonMiddlewares = this.extractCommonMiddlewares(routes);
+                if (routes.length > 1 && commonMiddlewares.length > 0) {
+                    // Multiple routes with common middlewares - use grouping
+                    await this.registerRouteGroup(basePath, commonMiddlewares, routes);
+                }
+                else {
+                    // Single route or no common middlewares - register individually
+                    for (const route of routes) {
+                        await this.registerRouteDirect(route);
+                    }
+                }
+            }
+        }
+        // Register WebSocket routes
+        if (this.wsRouteQueue.length > 0) {
+            for (const wsRoute of this.wsRouteQueue) {
+                await this.registerWebsocketRouteDirect(wsRoute);
+            }
+        }
+        // Log controller summary
+        this.logControllerSummary();
+    }
+    /**
+     * Logs a summary of registered controllers
+     */
+    logControllerSummary() {
+        const httpGroups = this.groupRoutesByController();
+        const wsGroups = this.groupWebSocketRoutesByController();
+        // Log HTTP controllers
+        for (const [controllerName, group] of httpGroups) {
+            const routeCount = group.routes.length;
+            const routeText = routeCount === 1 ? 'route' : 'routes';
+            this.logger.info(`${green('✓')} Successfully registered ${yellow('CONTROLLER')} ${blue(controllerName)} ${yellow(`(${routeCount} ${routeText})`)}`);
+        }
+        // Log WebSocket controllers (only those that don't have HTTP routes)
+        for (const [controllerName, group] of wsGroups) {
+            if (!httpGroups.has(controllerName)) {
+                const routeCount = group.routes.length;
+                const routeText = routeCount === 1 ? 'route' : 'routes';
+                this.logger.info(`${green('✓')} Successfully registered ${yellow('WEBSOCKET')} ${blue(controllerName)} ${yellow(`(${routeCount} ${routeText})`)}`);
+            }
+        }
+    }
+    /**
+     * Registers a WebSocket route directly
+     * Converts HTTP GET route to WebSocket upgrade endpoint
+     */
+    async registerWebsocketRouteDirect(wsRoute) {
+        // Get filtered global middlewares for this WebSocket route
+        const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(wsRoute.path);
+        const preparedGlobalMiddlewares = this.prepareMiddlewares(applicableGlobalMiddlewares);
+        const preparedMiddlewares = this.prepareMiddlewares(wsRoute.middlewares || []);
+        // Combine: global middlewares -> route middlewares
+        const allMiddlewares = [...preparedGlobalMiddlewares, ...preparedMiddlewares];
+        this.app.get(`/${wsRoute.path}`, ...allMiddlewares, async (c, next) => {
+            const websocketData = c.get('_websocketData') || {};
+            const id = bun.randomUUIDv7();
+            const data = { values: websocketData, id, path: wsRoute.path };
+            const upgradeResult = this.server.upgrade(c.req.raw, { data });
+            if (upgradeResult) {
+                return new Response(null);
+            }
+            await next(); // Failed
+        });
+    }
+    /**
+     * Registers a group of routes with common middlewares at base path level
+     */
+    async registerRouteGroup(basePath, commonMiddlewares, routes) {
+        // Create grouped Hono instance
+        const group = new Hono();
+        // Get filtered global middlewares for this base path
+        const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(basePath);
+        const preparedGlobalMiddlewares = this.prepareMiddlewares(applicableGlobalMiddlewares);
+        // Apply global middlewares first (before common middlewares)
+        if (preparedGlobalMiddlewares.length > 0) {
+            group.use('*', ...preparedGlobalMiddlewares);
+        }
+        // Apply common middlewares to the entire group
+        const preparedCommonMiddlewares = this.prepareMiddlewares(commonMiddlewares);
+        if (preparedCommonMiddlewares.length > 0) {
+            group.use('*', ...preparedCommonMiddlewares);
+        }
+        // Method map for group
+        const groupMethodMap = {
+            [HttpMethod.GET]: (path, ...handlers) => group.get(path, ...handlers),
+            [HttpMethod.POST]: (path, ...handlers) => group.post(path, ...handlers),
+            [HttpMethod.PUT]: (path, ...handlers) => group.put(path, ...handlers),
+            [HttpMethod.DELETE]: (path, ...handlers) => group.delete(path, ...handlers),
+            [HttpMethod.PATCH]: (path, ...handlers) => group.patch(path, ...handlers),
+            [HttpMethod.OPTIONS]: (path, ...handlers) => group.options(path, ...handlers),
+            [HttpMethod.CONNECT]: (path, ...handlers) => group.on(HttpMethod.CONNECT.toUpperCase(), path, ...handlers),
+            [HttpMethod.HEAD]: (path, ...handlers) => group.on(HttpMethod.HEAD.toUpperCase(), path, ...handlers),
+            [HttpMethod.TRACE]: (path, ...handlers) => group.on(HttpMethod.TRACE.toUpperCase(), path, ...handlers),
+        };
+        // Register each route in the group
+        for (const route of routes) {
+            // Remove common middlewares from route middlewares
+            const uniqueMiddlewares = (route.middlewares || []).filter((mw) => !commonMiddlewares.some((common) => common.constructor.name === mw.constructor.name));
+            const preparedMiddlewares = this.prepareMiddlewares(uniqueMiddlewares);
+            const validators = route.validator ? await this.prepareValidator(route.validator) : [];
+            const allMiddlewares = [...validators, ...preparedMiddlewares];
+            const methodHandler = groupMethodMap[route.method];
+            if (!methodHandler) {
+                throw new Error(`Invalid HTTP method: ${route.method}`);
+            }
+            // Calculate relative path
+            let relativePath = route.path;
+            if (route.path.startsWith(basePath) && basePath !== '/') {
+                relativePath = route.path.slice(basePath.length);
+            }
+            if (!relativePath.startsWith('/')) {
+                relativePath = '/' + relativePath;
+            }
+            // Register to group
+            if (route.staticServe) {
+                methodHandler(relativePath, ...allMiddlewares, serveStatic(this.prepareStaticServeOptions(route.staticServe)));
+            }
+            else {
+                const handler = this.prepareHandler(route.handler);
+                methodHandler(relativePath, ...allMiddlewares, handler);
+            }
+        }
+        // Mount group to main app
+        this.app.route(basePath, group);
+    }
+    /**
+     * Registers a single route directly without grouping
+     */
+    async registerRouteDirect(route) {
+        // Get filtered global middlewares for this route
+        const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(route.path);
+        const preparedGlobalMiddlewares = this.prepareMiddlewares(applicableGlobalMiddlewares);
+        const preparedMiddlewares = this.prepareMiddlewares(route.middlewares || []);
+        const validators = route.validator ? await this.prepareValidator(route.validator) : [];
+        // Combine: validators -> global middlewares -> route middlewares
+        const allMiddlewares = [...validators, ...preparedGlobalMiddlewares, ...preparedMiddlewares];
+        const methodHandler = this.methodMap[route.method];
+        if (!methodHandler) {
+            throw new Error(`Invalid HTTP method: ${route.method}`);
+        }
+        if (route.staticServe) {
+            methodHandler(route.path, ...allMiddlewares, serveStatic(this.prepareStaticServeOptions(route.staticServe)));
+        }
+        else {
+            const handler = this.prepareHandler(route.handler);
+            methodHandler(route.path, ...allMiddlewares, handler);
+        }
+    }
+    /**
+     * Groups HTTP routes by controller name
+     *
+     * Creates a map of controller names to their routes for organized logging.
+     * Each group contains the controller's base path and all its routes.
+     *
+     * @returns Map of controller names to route groups
+     *
+     * @example
+     * ```typescript
+     * groupRoutesByController()
+     * // => Map {
+     * //   'UserController' => {
+     * //     basePath: '/users',
+     * //     routes: [{ method: 'GET', path: '/users' }, { method: 'POST', path: '/users' }]
+     * //   }
+     * // }
+     * ```
+     */
+    groupRoutesByController() {
+        const groups = new Map();
+        for (const route of this.routeQueue) {
+            const controllerName = route.controllerName || 'Unknown';
+            const controllerBasePath = route.controllerBasePath || '/';
+            if (!groups.has(controllerName)) {
+                groups.set(controllerName, {
+                    basePath: controllerBasePath,
+                    routes: [],
+                });
+            }
+            groups.get(controllerName).routes.push({
+                method: route.method.toUpperCase(),
+                path: route.path,
+            });
+        }
+        return groups;
+    }
+    /**
+     * Groups WebSocket routes by controller name
+     *
+     * Creates a map of controller names to their WebSocket routes for organized logging.
+     *
+     * @returns Map of controller names to WebSocket route groups
+     *
+     * @example
+     * ```typescript
+     * groupWebSocketRoutesByController()
+     * // => Map {
+     * //   'ChatController' => {
+     * //     basePath: '/chat',
+     * //     routes: [{ path: '/chat' }]
+     * //   }
+     * // }
+     * ```
+     */
+    groupWebSocketRoutesByController() {
+        const groups = new Map();
+        for (const wsRoute of this.wsRouteQueue) {
+            const controllerName = wsRoute.controllerName || 'Unknown';
+            const controllerBasePath = wsRoute.path; // WebSocket uses path as base path
+            if (!groups.has(controllerName)) {
+                groups.set(controllerName, {
+                    basePath: controllerBasePath,
+                    routes: [],
+                });
+            }
+            groups.get(controllerName).routes.push({
+                path: wsRoute.path,
+            });
+        }
+        return groups;
+    }
+    /**
+     * Builds controller-based log output
+     *
+     * Creates a formatted string showing all routes grouped by controller,
+     * with HTTP and WebSocket routes clearly organized.
+     *
+     * @returns Formatted log string
+     *
+     * @example
+     * Output format:
+     * ```
+     * Registered routes:
+     *
+     *   UserController (/users):
+     *     GET /users
+     *     GET /users/:id
+     *     POST /users
+     *
+     *   ChatController (/chat):
+     *     WS /chat
+     * ```
+     */
+    buildControllerBasedLog() {
+        const httpGroups = this.groupRoutesByController();
+        const wsGroups = this.groupWebSocketRoutesByController();
+        // Merge WebSocket groups into HTTP groups
+        for (const [controllerName, wsGroup] of wsGroups) {
+            if (httpGroups.has(controllerName)) {
+                // Add WebSocket routes to existing controller group
+                const httpGroup = httpGroups.get(controllerName);
+                for (const wsRoute of wsGroup.routes) {
+                    httpGroup.routes.push({
+                        method: 'WS',
+                        path: wsRoute.path,
+                    });
+                }
+            }
+            else {
+                // Create new group for WebSocket-only controller
+                httpGroups.set(controllerName, {
+                    basePath: wsGroup.basePath,
+                    routes: wsGroup.routes.map((r) => ({
+                        method: 'WS',
+                        path: r.path,
+                    })),
+                });
+            }
+        }
+        // Build log output with colors
+        const lines = [];
+        // Sort controllers alphabetically for consistent output
+        const sortedControllers = Array.from(httpGroups.entries()).sort(([a], [b]) => a.localeCompare(b));
+        for (const [controllerName, group] of sortedControllers) {
+            lines.push(`  ${blue(controllerName)} ${yellow(`(${group.basePath})`)}`);
+            // Sort routes: GET first, then POST, PUT, PATCH, DELETE, WS
+            const methodOrder = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'WS'];
+            const sortedRoutes = group.routes.sort((a, b) => {
+                const orderA = methodOrder.indexOf(a.method);
+                const orderB = methodOrder.indexOf(b.method);
+                return orderA - orderB;
+            });
+            for (const route of sortedRoutes) {
+                // Colorize method based on type
+                let coloredMethod = route.method;
+                if (route.method === 'GET') {
+                    coloredMethod = green(route.method);
+                }
+                else if (route.method === 'POST') {
+                    coloredMethod = blue(route.method);
+                }
+                else if (route.method === 'PUT') {
+                    coloredMethod = yellow(route.method);
+                }
+                else if (route.method === 'DELETE') {
+                    coloredMethod = red(route.method);
+                }
+                else if (route.method === 'WS') {
+                    coloredMethod = blue(route.method);
+                }
+                lines.push(`    ${coloredMethod} ${route.path}`);
+            }
+            lines.push(''); // Empty line between controllers
+        }
+        return lines.join('\n');
     }
 }
 //# sourceMappingURL=HonoAdapter.js.map