@asenajs/hono-adapter 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from './lib/HonoWebsocketAdapter';
 export * from './lib/types';
 export * from './lib/defaults';
 export * from './lib/utils/createHonoAdapter';
+export { HTTPException } from 'hono/http-exception';

package/dist/index.js

@@ -3,4 +3,6 @@ export * from './lib/HonoWebsocketAdapter';
 export * from './lib/types';
 export * from './lib/defaults';
 export * from './lib/utils/createHonoAdapter';
+// Re-export Hono's HTTPException for user convenience in middlewares
+export { HTTPException } from 'hono/http-exception';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAE9C,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lib/HonoAdapter.d.ts

@@ -1,26 +1,234 @@
-import { Hono } from "hono";
-import type { Server } from "bun";
-import type { AsenaWebsocketAdapter } from "@asenajs/asena/adapter";
-import { AsenaAdapter, type AsenaServeOptions, type BaseMiddleware, type RouteParams } from "@asenajs/asena/adapter";
-import type { HonoErrorHandler } from "./types";
-import { type ServerLogger } from "@asenajs/asena/logger";
-import type { ValidationSchema } from "./defaults";
-import type { Context as HonoAdapterContext } from "./defaults/Context";
-export declare class HonoAdapter extends AsenaAdapter<Hono, HonoAdapterContext, ValidationSchema, AsenaWebsocketAdapter<Hono, HonoAdapterContext>> {
+import { Hono } from 'hono';
+import type { Server } from 'bun';
+import type { AsenaWebsocketAdapter, WebsocketRouteParams } from '@asenajs/asena/adapter';
+import { AsenaAdapter, type AsenaServeOptions, type BaseMiddleware, type RouteParams } from '@asenajs/asena/adapter';
+import type { GlobalMiddlewareRouteConfig } from '@asenajs/asena/server/config';
+import type { HonoErrorHandler, StaticServeExtras } from './types';
+import { type ServerLogger } from '@asenajs/asena/logger';
+import type { ValidationSchema } from './defaults';
+import type { Context as HonoAdapterContext } from './defaults/Context';
+import type { WebSocketData } from '@asenajs/asena/web-socket';
+export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, ValidationSchema> {
     name: string;
     app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
     private server;
     private options;
+    private routeQueue;
+    /**
+     * WebSocket route queue for deferred registration
+     * WebSocket routes are queued during initialization and registered when server starts
+     */
+    private wsRouteQueue;
+    /**
+     * Global middlewares with optional path filtering configuration
+     * Middlewares are stored with their pattern config and applied during route registration
+     */
+    private globalMiddlewares;
+    private routesRegistered;
     private readonly methodMap;
-    constructor(websocketAdapter: AsenaWebsocketAdapter<Hono, HonoAdapterContext>, logger?: ServerLogger);
-    use(middleware: BaseMiddleware<HonoAdapterContext>, path?: string): void;
-    registerRoute({ method, path, middleware, handler, staticServe, validator, }: RouteParams<HonoAdapterContext, ValidationSchema>): Promise<void>;
-    start(): Promise<Server>;
+    constructor(logger: ServerLogger, websocketAdapter?: AsenaWebsocketAdapter);
+    /**
+     * 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: BaseMiddleware<HonoAdapterContext>, config?: GlobalMiddlewareRouteConfig): void;
+    registerRoute(params: RouteParams<HonoAdapterContext, ValidationSchema, StaticServeExtras>): Promise<void>;
+    /**
+     * 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: WebsocketRouteParams<HonoAdapterContext>): Promise<void> | void;
+    start(): Promise<Server<WebSocketData<any>>>;
+    /**
+     * 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: HonoErrorHandler): void;
     serveOptions(options: () => Promise<AsenaServeOptions> | AsenaServeOptions): Promise<void>;
     setPort(port: number): void;
     private prepareMiddlewares;
     private prepareHandler;
+    /**
+     * Prepares static serve options with enhanced features
+     * @param staticServe - Base static serve parameters
+     * @returns Configured static serve options for Hono
+     */
+    private prepareStaticServeOptions;
+    /**
+     * Prepares validation middleware with enhanced error handling
+     * @param baseValidator - The validator to prepare
+     * @returns Array of Hono middleware handlers for validation
+     */
     private prepareValidator;
-    private normalizePath;
+    /**
+     * 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]
+     * ```
+     */
+    private getGlobalMiddlewaresForPath;
+    /**
+     * Extracts base path from a route path
+     * Examples:
+     * - "/api/users/:id" -> "/api/users"
+     * - "/users" -> "/users"
+     * - "/" -> "/"
+     */
+    private extractBasePath;
+    /**
+     * Groups routes by their base path
+     * Returns a map of base path -> routes with that base path
+     */
+    private groupRoutesByBasePath;
+    /**
+     * Finds common middlewares across all routes in a group
+     * Returns middlewares that appear in ALL routes
+     */
+    private extractCommonMiddlewares;
+    /**
+     * Registers routes to Hono app with optimization
+     * Groups routes by base path and applies common middlewares at group level
+     * Also registers WebSocket routes
+     */
+    private optimizeAndRegisterRoutes;
+    /**
+     * Logs a summary of registered controllers
+     */
+    private logControllerSummary;
+    /**
+     * Registers a WebSocket route directly
+     * Converts HTTP GET route to WebSocket upgrade endpoint
+     */
+    private registerWebsocketRouteDirect;
+    /**
+     * Registers a group of routes with common middlewares at base path level
+     */
+    private registerRouteGroup;
+    /**
+     * Registers a single route directly without grouping
+     */
+    private registerRouteDirect;
+    /**
+     * 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' }]
+     * //   }
+     * // }
+     * ```
+     */
+    private groupRoutesByController;
+    /**
+     * 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' }]
+     * //   }
+     * // }
+     * ```
+     */
+    private groupWebSocketRoutesByController;
+    /**
+     * 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
+     * ```
+     */
+    private buildControllerBasedLog;
 }