@asenajs/ergenecore 1.1.0 → 1.3.0

package/README.md

@@ -70,8 +70,8 @@ await server.start();
 ### Controller Example
 
 ```typescript
-import { Controller } from '@asenajs/asena/server';
-import { Get, Post, Put, Delete } from '@asenajs/asena/web';
+import { Controller } from '@asenajs/asena/decorators';
+import { Get, Post, Put, Delete } from '@asenajs/asena/decorators/http';
 import type { Context } from '@asenajs/ergenecore/types';
 
 @Controller('/users')
@@ -225,9 +225,9 @@ const session = context.getCookie('session');
 #### Custom Middleware
 
 ```typescript
-import { Middleware } from '@asenajs/asena/server';
-import { Controller } from '@asenajs/asena/server';
-import { Get } from '@asenajs/asena/web';
+import { Middleware } from '@asenajs/asena/decorators';
+import { Controller } from '@asenajs/asena/decorators';
+import { Get } from '@asenajs/asena/decorators/http';
 import { MiddlewareService, type Context } from '@asenajs/ergenecore';
 
 @Middleware()
@@ -262,7 +262,7 @@ export class AdminController {
 Ergenecore comes with a built-in CORS middleware for handling Cross-Origin Resource Sharing:
 
 ```typescript
-import { Middleware } from '@asenajs/asena/server';
+import { Middleware } from '@asenajs/asena/decorators';
 import { CorsMiddleware } from '@asenajs/ergenecore';
 
 // Allow all origins (default)
@@ -303,7 +303,7 @@ export class DynamicCors extends CorsMiddleware {
 }
 
 // Use globally in server config
-import { Config } from '@asenajs/asena/server';
+import { Config } from '@asenajs/asena/decorators';
 import { ConfigService } from '@asenajs/ergenecore';
 
 @Config()
@@ -326,7 +326,7 @@ export class ApiController {
 Ergenecore includes a Token Bucket-based rate limiter for controlling request rates and preventing abuse:
 
 ```typescript
-import { Middleware } from '@asenajs/asena/server';
+import { Middleware } from '@asenajs/asena/decorators';
 import { RateLimiterMiddleware } from '@asenajs/ergenecore';
 
 // General API rate limiter (100 requests per minute)
@@ -381,7 +381,7 @@ export class CustomRateLimiter extends RateLimiterMiddleware {
 }
 
 // Use globally
-import { Config } from '@asenajs/asena/server';
+import { Config } from '@asenajs/asena/decorators';
 import { ConfigService } from '@asenajs/ergenecore';
 
 @Config()
@@ -432,8 +432,8 @@ The middleware automatically sets standard rate limit headers:
 ### Validation with Zod
 
 ```typescript
-import { Controller, Middleware } from '@asenajs/asena/server';
-import { Post } from '@asenajs/asena/web';
+import { Controller, Middleware } from '@asenajs/asena/decorators';
+import { Post } from '@asenajs/asena/decorators/http';
 import { ValidationService, type Context, type ValidationSchema, type ValidationSchemaWithHook } from '@asenajs/ergenecore';
 import { z } from 'zod';
 
@@ -471,8 +471,8 @@ async json(): Promise<ValidationSchema | ValidationSchemaWithHook> {
 ### Combining Middleware and Validation
 
 ```typescript
-import { Controller, Middleware } from '@asenajs/asena/server';
-import { Post } from '@asenajs/asena/web';
+import { Controller, Middleware } from '@asenajs/asena/decorators';
+import { Post } from '@asenajs/asena/decorators/http';
 import {
   MiddlewareService,
   ValidationService,
@@ -556,8 +556,8 @@ export class ChatSocket extends AsenaWebSocketService<void> {
 ### Static File Serving
 
 ```typescript
-import { Controller } from '@asenajs/asena/server';
-import { Get } from '@asenajs/asena/web';
+import { Controller } from '@asenajs/asena/decorators';
+import { Get } from '@asenajs/asena/decorators/http';
 import { StaticServe, StaticServeService } from '@asenajs/asena/static';
 import type { Context } from '@asenajs/ergenecore/types';
 
@@ -587,8 +587,8 @@ export class StaticController {
 ### Error Handling
 
 ```typescript
-import { Config } from '@asenajs/asena/server';
-import { Inject } from '@asenajs/asena/ioc';
+import { Config } from '@asenajs/asena/decorators';
+import { Inject } from '@asenajs/asena/decorators/ioc';
 import { ConfigService, type Context } from '@asenajs/ergenecore';
 
 @Config()

package/dist/lib/Ergenecore.d.ts

@@ -56,6 +56,11 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * Config is optional - if not provided, middleware applies to all routes
      */
     private globalMiddlewares;
+    /**
+     * HTML routes for FrontendController pages
+     * Stored separately and merged into Bun.serve() routes at start time
+     */
+    private htmlRoutes;
     private options;
     /**
      * Creates a new CoreAdapter instance
@@ -82,7 +87,7 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * });
      * ```
      */
-    registerWebsocketRoute(params: WebsocketRouteParams<Context>): void;
+    registerWebsocketRoute(params: WebsocketRouteParams<Context>): Promise<void>;
     /**
      * Sets the server port
      *
@@ -107,6 +112,14 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * });
      * ```
      */
+    /**
+     * Registers an HTML route for FrontendController pages.
+     * HTML routes bypass the middleware chain and are served directly by Bun.serve().
+     *
+     * @param path - Full URL path (e.g., '/ui/home')
+     * @param htmlBundle - The HTML bundle returned by importing an .html file
+     */
+    registerHTMLRoute(path: string, htmlBundle: unknown): void;
     use(middleware: BaseMiddleware<Context>, config?: GlobalMiddlewareConfig['routes']): void;
     /**
      * Registers a route (deferred registration)
@@ -143,7 +156,7 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * @param port - Optional port to override default
      * @returns Bun server instance
      */
-    start(port?: number): Server<any>;
+    start(port?: number): Promise<Server<any>>;
     /**
      * Stops the server
      *

package/dist/lib/Ergenecore.js

@@ -1,11 +1,11 @@
 import { AsenaAdapter, VALIDATOR_METHODS, } from '@asenajs/asena/adapter';
 import { blue, green, red, yellow } from '@asenajs/asena/logger';
-import { shouldApplyMiddleware } from '@asenajs/asena/utils/patternMatcher';
 import { ErgenecoreWebsocketAdapter } from './ErgenecoreWebsocketAdapter';
 import { ErgenecoreContextWrapper } from './ErgenecoreContextWrapper';
 import * as Bun from 'bun';
 import * as path from 'path';
 import { HttpException, MiddlewareResponseError } from './errors';
+import { shouldApplyMiddleware } from '@asenajs/asena/utils';
 /**
  * Static response headers for performance
  *
@@ -63,6 +63,11 @@ export class Ergenecore extends AsenaAdapter {
      * Config is optional - if not provided, middleware applies to all routes
      */
     globalMiddlewares = [];
+    /**
+     * HTML routes for FrontendController pages
+     * Stored separately and merged into Bun.serve() routes at start time
+     */
+    htmlRoutes = new Map();
     options = {};
     /**
      * Creates a new CoreAdapter instance
@@ -92,12 +97,12 @@ export class Ergenecore extends AsenaAdapter {
      * });
      * ```
      */
-    registerWebsocketRoute(params) {
+    async registerWebsocketRoute(params) {
         // Queue WebSocket route for building during start()
         this.wsRouteQueue.push(params);
         // Register WebSocket service with adapter using the route path (not namespace)
         if (this.websocketAdapter && params.websocketService) {
-            this.websocketAdapter.registerWebSocket(params.websocketService);
+            await this.websocketAdapter.registerWebSocket(params.websocketService);
         }
     }
     /**
@@ -126,6 +131,27 @@ export class Ergenecore extends AsenaAdapter {
      * });
      * ```
      */
+    /**
+     * Registers an HTML route for FrontendController pages.
+     * HTML routes bypass the middleware chain and are served directly by Bun.serve().
+     *
+     * @param path - Full URL path (e.g., '/ui/home')
+     * @param htmlBundle - The HTML bundle returned by importing an .html file
+     */
+    registerHTMLRoute(path, htmlBundle) {
+        if (this.htmlRoutes.has(path)) {
+            throw new Error(`Duplicate HTML route: "${path}" is already registered.`);
+        }
+        this.htmlRoutes.set(path, htmlBundle);
+        // Register trailing slash variant for consistent routing
+        // e.g., /ui → also register /ui/ (or vice versa)
+        if (path !== '/' && !path.endsWith('/')) {
+            this.htmlRoutes.set(`${path}/`, htmlBundle);
+        }
+        else if (path !== '/' && path.endsWith('/')) {
+            this.htmlRoutes.set(path.slice(0, -1), htmlBundle);
+        }
+    }
     use(middleware, config) {
         this.globalMiddlewares.push({ middleware, config });
     }
@@ -166,7 +192,7 @@ export class Ergenecore extends AsenaAdapter {
      * @param port - Optional port to override default
      * @returns Bun server instance
      */
-    start(port) {
+    async start(port) {
         // Build routes if not built yet
         const serverHostname = this._hostname;
         if (!this.routesBuilt) {
@@ -178,8 +204,15 @@ export class Ergenecore extends AsenaAdapter {
             this.checkPathCollisions(httpRoutes, wsRoutes);
             // 4. Merge routes
             const finalRoutes = this.mergeRoutes(httpRoutes, wsRoutes);
+            // 4.5. Merge HTML routes (FrontendController pages)
+            for (const [htmlPath, htmlBundle] of this.htmlRoutes) {
+                if (finalRoutes[htmlPath]) {
+                    throw new Error(`HTML route collision at "${htmlPath}": path already registered as an API or WebSocket route.`);
+                }
+                finalRoutes[htmlPath] = htmlBundle;
+            }
             // 5. Prepare WebSocket before starting server
-            this.websocketAdapter.prepareWebSocket(this.options.wsOptions);
+            await this.websocketAdapter.prepareWebSocket(this.options.wsOptions);
             const serverPort = port ?? this.port;
             // 6. Start Bun server with merged routes
             this.server = Bun.serve({
@@ -190,7 +223,7 @@ export class Ergenecore extends AsenaAdapter {
                 websocket: this.websocketAdapter.websocket,
             });
             // Start WebSocket server (initializes AsenaWebSocketServer for each namespace)
-            this.websocketAdapter.startWebsocket(this.server);
+            await this.websocketAdapter.startWebsocket(this.server);
             this.routesBuilt = true;
             // Log controller summary first
             if (this.routeQueue.length > 0 || this.wsRouteQueue.length > 0) {
@@ -275,7 +308,15 @@ export class Ergenecore extends AsenaAdapter {
             }
             // Build Bun router object for each path
             for (const [path, pathRoutes] of routesByPath) {
-                routes[path] = {};
+                // Normalize trailing slash to support both variants
+                // This ensures /users and /users/ both work with query params
+                const normalizedPath = path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
+                const pathWithSlash = normalizedPath === '/' ? '/' : `${normalizedPath}/`;
+                // Initialize both path variants (skip duplicate for root path)
+                routes[normalizedPath] = routes[normalizedPath] || {};
+                if (normalizedPath !== '/') {
+                    routes[pathWithSlash] = routes[pathWithSlash] || {};
+                }
                 for (const route of pathRoutes) {
                     const method = route.method.toUpperCase();
                     // Fast Path Optimization with Pattern Matching
@@ -286,19 +327,48 @@ export class Ergenecore extends AsenaAdapter {
                         (!route.middlewares || route.middlewares.length === 0) &&
                         !route.validator &&
                         !route.staticServe;
-                    if (isSimpleRoute) {
-                        // Use fast path handler for simple routes (minimal overhead)
-                        routes[path][method] = this.createFastPathHandler(route);
+                    // Create handler based on route complexity
+                    const handler = isSimpleRoute
+                        ? this.createFastPathHandler(route)
+                        : this.createRouteHandler(route, commonMiddlewares);
+                    // Register handler to both path variants for trailing slash support
+                    if (method === 'ALL') {
+                        // Bun native: direct handler function matches all HTTP methods
+                        routes[normalizedPath] = handler;
+                        if (normalizedPath !== '/') {
+                            routes[pathWithSlash] = handler;
+                        }
                     }
                     else {
-                        // Use full-featured handler for complex routes
-                        routes[path][method] = this.createRouteHandler(route, commonMiddlewares);
+                        routes[normalizedPath][method] = handler;
+                        if (normalizedPath !== '/') {
+                            routes[pathWithSlash][method] = handler;
+                        }
                     }
                 }
             }
         }
-        // Add 404 handler with static headers
-        routes['/*'] = () => {
+        // Catch-all handler for unmatched routes (including OPTIONS preflight)
+        // Runs global middlewares so CORS and other cross-cutting concerns work for all requests
+        routes['/*'] = async (req) => {
+            const context = new ErgenecoreContextWrapper(req, this.server);
+            const requestPath = new URL(req.url).pathname;
+            // Filter and run applicable global middlewares
+            const applicableMiddlewares = this.globalMiddlewares
+                .filter(({ config }) => shouldApplyMiddleware(requestPath, config))
+                .map(({ middleware }) => middleware);
+            if (applicableMiddlewares.length > 0) {
+                const result = await this.executeMiddlewares(context, applicableMiddlewares);
+                if (result instanceof Response)
+                    return result;
+                if (result === false) {
+                    return new Response('Forbidden', { status: 403 });
+                }
+            }
+            // No middleware handled the request → error handler or 404
+            if (this.errorHandler) {
+                return this.errorHandler(new Error('Not Found'), context);
+            }
             return new Response(JSON.stringify({ error: 'Not Found' }), {
                 status: 404,
                 headers: STATIC_JSON_HEADERS,
@@ -333,7 +403,7 @@ export class Ergenecore extends AsenaAdapter {
             // Initialize path object
             routes[path] = routes[path] || {};
             // Add GET handler for WebSocket upgrade (with middleware chain)
-            routes[path]['GET'] = this.createWebSocketUpgradeHandler(wsRoute);
+            routes[path].GET = this.createWebSocketUpgradeHandler(wsRoute);
         }
         return routes;
     }
@@ -363,15 +433,24 @@ export class Ergenecore extends AsenaAdapter {
      * }
      * ```
      */
-    async executeMiddlewares(context, middlewares, index = 0) {
+    async executeMiddlewares(context, middlewares, index = 0, onComplete) {
         // Base case: all middlewares executed successfully
         if (index >= middlewares.length) {
+            if (onComplete) {
+                const result = await onComplete();
+                if (result instanceof Response)
+                    return result;
+                if (result === false)
+                    return false;
+            }
             return true;
         }
         const middleware = middlewares[index];
+        let nextCalled = false;
         // Create next() function that executes the next middleware in chain
         const next = async () => {
-            const result = await this.executeMiddlewares(context, middlewares, index + 1);
+            nextCalled = true;
+            const result = await this.executeMiddlewares(context, middlewares, index + 1, onComplete);
             // If next middleware returned Response, throw MiddlewareResponseError to propagate it
             if (result instanceof Response) {
                 throw new MiddlewareResponseError(result);
@@ -392,7 +471,11 @@ export class Ergenecore extends AsenaAdapter {
             if (result === false) {
                 return false;
             }
-            // Middleware executed successfully
+            // If middleware returned true/void without calling next(), auto-continue the chain
+            if (!nextCalled) {
+                return await this.executeMiddlewares(context, middlewares, index + 1, onComplete);
+            }
+            // Middleware called next() and completed successfully
             return true;
         }
         catch (error) {
@@ -442,7 +525,7 @@ export class Ergenecore extends AsenaAdapter {
         return async (req) => {
             try {
                 // Create context wrapper
-                const context = new ErgenecoreContextWrapper(req);
+                const context = new ErgenecoreContextWrapper(req, this.server);
                 // Execute filtered global middlewares with real next() chain
                 if (applicableGlobalMiddlewares.length > 0) {
                     const result = await this.executeMiddlewares(context, applicableGlobalMiddlewares);
@@ -522,7 +605,7 @@ export class Ergenecore extends AsenaAdapter {
             // Check if HTTP routes have the same path
             if (httpRoutes[wsPath]) {
                 // Check if HTTP route has GET method (collision with WebSocket GET)
-                if (httpRoutes[wsPath]['GET']) {
+                if (httpRoutes[wsPath].GET) {
                     throw new Error(`Route collision detected at path "${wsPath}": Both HTTP and WebSocket routes define GET method. ` +
                         `WebSocket routes use GET for upgrade handshake, so HTTP GET cannot be registered on the same path.`);
                 }
@@ -583,14 +666,13 @@ export class Ergenecore extends AsenaAdapter {
         // If no error handler is set, use ultra-minimal version with default error handling
         if (!this.errorHandler) {
             return async (req) => {
-                const context = new ErgenecoreContextWrapper(req);
+                const context = new ErgenecoreContextWrapper(req, this.server);
                 try {
                     // Inject Bun's native route params if present
-                    // @ts-ignore - Bun adds params to Request
+                    // @ts-expect-error - Bun adds params to Request
                     if (req.params) {
-                        // @ts-ignore - Bun adds params to Request
+                        // @ts-expect-error - Bun adds params to Request
                         const params = req.params;
-                        // eslint-disable-next-line guard-for-in
                         for (const key in params) {
                             context.setValue(`param:${key}`, params[key]);
                         }
@@ -625,14 +707,13 @@ export class Ergenecore extends AsenaAdapter {
         }
         // With error handler (minimal try-catch)
         return async (req) => {
-            const context = new ErgenecoreContextWrapper(req);
+            const context = new ErgenecoreContextWrapper(req, this.server);
             try {
                 // Inject Bun's native route params if present
-                // @ts-ignore - Bun adds params to Request
+                // @ts-expect-error - Bun adds params to Request
                 if (req.params) {
-                    // @ts-ignore - Bun adds params to Request
+                    // @ts-expect-error - Bun adds params to Request
                     const params = req.params;
-                    // eslint-disable-next-line guard-for-in
                     for (const key in params) {
                         context.setValue(`param:${key}`, params[key]);
                     }
@@ -678,65 +759,59 @@ export class Ergenecore extends AsenaAdapter {
         const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(route.path);
         return async (req) => {
             // Create context wrapper outside try block so it's accessible in catch
-            const context = new ErgenecoreContextWrapper(req);
+            const context = new ErgenecoreContextWrapper(req, this.server);
             // Inject Bun's native route params
-            // @ts-ignore - Bun adds params to Request
+            // @ts-expect-error - Bun adds params to Request
             if (req.params) {
-                // @ts-ignore - Bun adds params to Request
+                // @ts-expect-error - Bun adds params to Request
                 const params = req.params;
-                // eslint-disable-next-line guard-for-in
                 for (const key in params) {
                     context.setValue(`param:${key}`, params[key]);
                 }
             }
             try {
-                // Execute filtered global middlewares with real next() chain
-                if (applicableGlobalMiddlewares.length > 0) {
-                    const result = await this.executeMiddlewares(context, applicableGlobalMiddlewares);
-                    // If middleware returned a custom response, return it
-                    if (result instanceof Response) {
-                        return result;
-                    }
-                    // If middleware returned false, return 403
-                    if (result === false) {
-                        return new Response('Forbidden', { status: 403 });
+                // Combine global + route middlewares into a single chain
+                const allMiddlewares = [
+                    ...applicableGlobalMiddlewares,
+                    ...(route.middlewares || []),
+                ];
+                // Execute middleware chain with handler as onComplete callback
+                // This ensures the handler runs INSIDE the middleware async context
+                const result = await this.executeMiddlewares(context, allMiddlewares, 0, async () => {
+                    // Execute validation
+                    if (route.validator) {
+                        const validationResult = await this.validateRequest(context, route.validator);
+                        if (validationResult)
+                            return validationResult;
                     }
-                }
-                // Execute route middlewares with real next() chain
-                if (route.middlewares && route.middlewares.length > 0) {
-                    const result = await this.executeMiddlewares(context, route.middlewares);
-                    // If middleware returned a custom response, return it
-                    if (result instanceof Response) {
-                        return result;
+                    // Handle static file serving
+                    if (route.staticServe) {
+                        const staticResponse = await this.serveStaticFile(req, context, route.staticServe);
+                        if (staticResponse)
+                            return staticResponse;
                     }
-                    // If middleware returned false, return 403
-                    if (result === false) {
-                        return new Response('Forbidden', { status: 403 });
+                    // Execute route handler
+                    const response = await route.handler(context);
+                    // If handler returns Response, return it directly
+                    if (response instanceof Response) {
+                        return response;
                     }
+                    // Otherwise, wrap in Response
+                    return new Response(JSON.stringify(response), {
+                        status: 200,
+                        headers: { 'Content-Type': 'application/json' },
+                    });
+                });
+                // If middleware chain returned a custom response, return it
+                if (result instanceof Response) {
+                    return result;
                 }
-                // Execute validation
-                if (route.validator) {
-                    const validationResult = await this.validateRequest(context, route.validator);
-                    if (validationResult)
-                        return validationResult;
-                }
-                // Handle static file serving
-                if (route.staticServe) {
-                    const staticResponse = await this.serveStaticFile(req, context, route.staticServe);
-                    if (staticResponse)
-                        return staticResponse;
+                // If middleware chain returned false (stopped), return 403
+                if (result === false) {
+                    return new Response('Forbidden', { status: 403 });
                 }
-                // Execute route handler
-                const response = await route.handler(context);
-                // If handler returns Response, return it directly
-                if (response instanceof Response) {
-                    return response;
-                }
-                // Otherwise, wrap in Response
-                return new Response(JSON.stringify(response), {
-                    status: 200,
-                    headers: { 'Content-Type': 'application/json' },
-                });
+                // Default: result is true (should not happen with onComplete, but just in case)
+                return new Response(null, { status: 204 });
             }
             catch (error) {
                 // If handler or middleware threw HttpException, convert to Response
@@ -746,7 +821,7 @@ export class Ergenecore extends AsenaAdapter {
                 // Handle other errors with custom error handler if available
                 if (this.errorHandler) {
                     // Pass the original context with params already injected
-                    return await this.errorHandler(error, context);
+                    return this.errorHandler(error, context);
                 }
                 // Default error response
                 this.logger.error('Route handler error:', error);
@@ -1057,7 +1132,7 @@ export class Ergenecore extends AsenaAdapter {
      */
     extractBasePath(path) {
         // Remove trailing slash (except for root)
-        let normalized = path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
+        const normalized = path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
         // Split path into segments
         const segments = normalized.split('/');
         const baseSegments = [];
@@ -1355,10 +1430,7 @@ export class Ergenecore extends AsenaAdapter {
         for (const [controllerName, group] of mixedControllers) {
             // Merge WebSocket routes into this controller
             const wsGroup = wsGroups.get(controllerName);
-            const allRoutes = [
-                ...group.routes,
-                ...wsGroup.routes.map((r) => ({ method: 'WS', path: r.path })),
-            ];
+            const allRoutes = [...group.routes, ...wsGroup.routes.map((r) => ({ method: 'WS', path: r.path }))];
             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'];