@asenajs/ergenecore 1.2.0 → 1.3.1

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,15 @@ 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;
+    /**
+     * Queue of FrontendController route metadata for deferred logging at start time
+     */
+    private frontEndRouteQueue;
     private options;
     /**
      * Creates a new CoreAdapter instance
@@ -107,6 +116,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, controllerName: string, controllerBasePath: string): void;
     use(middleware: BaseMiddleware<Context>, config?: GlobalMiddlewareConfig['routes']): void;
     /**
      * Registers a route (deferred registration)
@@ -595,4 +612,8 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * ```
      */
     private buildControllerBasedLog;
+    /**
+     * Groups FrontendController routes by controller name for logging
+     */
+    private groupFrontEndRoutesByController;
 }

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/utlis';
 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,15 @@ 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();
+    /**
+     * Queue of FrontendController route metadata for deferred logging at start time
+     */
+    frontEndRouteQueue = [];
     options = {};
     /**
      * Creates a new CoreAdapter instance
@@ -126,6 +135,28 @@ 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, controllerName, controllerBasePath) {
+        if (this.htmlRoutes.has(path)) {
+            throw new Error(`Duplicate HTML route: "${path}" is already registered.`);
+        }
+        this.htmlRoutes.set(path, htmlBundle);
+        this.frontEndRouteQueue.push({ path, controllerName, controllerBasePath });
+        // 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 });
     }
@@ -178,6 +209,13 @@ 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
             await this.websocketAdapter.prepareWebSocket(this.options.wsOptions);
             const serverPort = port ?? this.port;
@@ -193,7 +231,7 @@ export class Ergenecore extends AsenaAdapter {
             await this.websocketAdapter.startWebsocket(this.server);
             this.routesBuilt = true;
             // Log controller summary first
-            if (this.routeQueue.length > 0 || this.wsRouteQueue.length > 0) {
+            if (this.routeQueue.length > 0 || this.wsRouteQueue.length > 0 || this.frontEndRouteQueue.length > 0) {
                 this.logControllerSummary();
                 // Then log detailed route list
                 this.logger.info(this.buildControllerBasedLog());
@@ -275,7 +313,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 +332,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,
@@ -363,15 +438,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 +476,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 +530,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);
@@ -583,7 +671,8 @@ 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);
+                context.routePattern = route.path;
                 try {
                     // Inject Bun's native route params if present
                     // @ts-expect-error - Bun adds params to Request
@@ -624,7 +713,8 @@ 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);
+            context.routePattern = route.path;
             try {
                 // Inject Bun's native route params if present
                 // @ts-expect-error - Bun adds params to Request
@@ -676,7 +766,8 @@ 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);
+            context.routePattern = route.path;
             // Inject Bun's native route params
             // @ts-expect-error - Bun adds params to Request
             if (req.params) {
@@ -687,53 +778,48 @@ export class Ergenecore extends AsenaAdapter {
                 }
             }
             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;
+                // 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;
                     }
-                    // If middleware returned false, return 403
-                    if (result === false) {
-                        return new Response('Forbidden', { status: 403 });
-                    }
-                }
-                // 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;
-                }
-                // Execute route handler
-                const response = await route.handler(context);
-                // If handler returns Response, return it directly
-                if (response instanceof Response) {
-                    return response;
+                // If middleware chain returned false (stopped), return 403
+                if (result === false) {
+                    return new Response('Forbidden', { status: 403 });
                 }
-                // 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
@@ -1278,6 +1364,13 @@ export class Ergenecore extends AsenaAdapter {
                 this.logger.info(`${green('✓')} Successfully registered ${yellow('WEBSOCKET')} ${blue(controllerName)} ${yellow(`(${routeCount} ${routeText})`)}`);
             }
         }
+        // Log FrontendControllers
+        const frontEndGroups = this.groupFrontEndRoutesByController();
+        for (const [controllerName, group] of frontEndGroups) {
+            const routeCount = group.routes.length;
+            const routeText = routeCount === 1 ? 'route' : 'routes';
+            this.logger.info(`${green('✓')} Successfully registered ${yellow('FRONTEND')} ${blue(controllerName)} ${yellow(`(${routeCount} ${routeText})`)}`);
+        }
     }
     /**
      * Builds controller-based log output with colors
@@ -1394,7 +1487,33 @@ export class Ergenecore extends AsenaAdapter {
             }
             lines.push(''); // Empty line between namespaces
         }
+        // 4. Frontend controllers (HTML routes)
+        const frontEndGroups = this.groupFrontEndRoutesByController();
+        const sortedFrontEnd = Array.from(frontEndGroups.entries()).sort(([a], [b]) => a.localeCompare(b));
+        for (const [controllerName, group] of sortedFrontEnd) {
+            lines.push(`  ${blue(controllerName)} ${yellow(`(${group.basePath})`)}`);
+            for (const route of group.routes) {
+                lines.push(`    ${green('HTML')} ${route.path}`);
+            }
+            lines.push('');
+        }
         return lines.join('\n');
     }
+    /**
+     * Groups FrontendController routes by controller name for logging
+     */
+    groupFrontEndRoutesByController() {
+        const groups = new Map();
+        for (const route of this.frontEndRouteQueue) {
+            if (!groups.has(route.controllerName)) {
+                groups.set(route.controllerName, {
+                    basePath: route.controllerBasePath,
+                    routes: [],
+                });
+            }
+            groups.get(route.controllerName).routes.push({ path: route.path });
+        }
+        return groups;
+    }
 }
 //# sourceMappingURL=Ergenecore.js.map