@asenajs/ergenecore 1.4.0 → 2.0.0

package/README.md

@@ -1,5 +1,8 @@
 # Asena Ergenecore Adapter
 
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://asena.sh)
+[![Bun Version](https://img.shields.io/badge/Bun-1.3.12%2B-blueviolet)](https://bun.sh)
+
 **Blazing-fast** native Bun adapter for [Asena.js](https://github.com/asenajs/asena) - Built exclusively with Bun's native APIs for maximum performance.
 
 Built on Bun runtime for exceptional performance:
@@ -604,11 +607,14 @@ export class ServerConfig extends ConfigService {
 }
 
 // With custom exception mapper
+import { isValidationError } from '@asenajs/asena/adapter';
+
 export class ExceptionMapper {
   map(error: Error, context: Context): Response {
-    // Custom error mapping logic
-    if (error.name === 'ValidationError') {
-      return context.send({ error: 'Validation failed', details: error.message }, 400);
+    // Request validation failures arrive here like any other error.
+    // Check this before `instanceof HttpException` - ValidationError extends it
+    if (isValidationError(error)) {
+      return context.send({ error: 'Validation failed', details: error.issues }, 400);
     }
 
     return context.send({ error: 'Internal server error' }, 500);

package/dist/lib/Ergenecore.d.ts

@@ -1,5 +1,5 @@
 import type { WebsocketRouteParams } from '@asenajs/asena/adapter';
-import { AsenaAdapter, type AsenaServeOptions, type AsenaStartOptions, type BaseMiddleware, type ErrorHandler, type RouteParams } from '@asenajs/asena/adapter';
+import { AsenaAdapter, type AsenaServeOptions, type AsenaStartOptions, type BaseMiddleware, type ErrorHandler, type NotFoundHandler, type RouteParams } from '@asenajs/asena/adapter';
 import { type ServerLogger } from '@asenajs/asena/logger';
 import type { GlobalMiddlewareConfig } from '@asenajs/asena/server/config';
 import { ErgenecoreWebsocketAdapter } from './ErgenecoreWebsocketAdapter';
@@ -50,6 +50,15 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * Error handler function
      */
     private errorHandler?;
+    /**
+     * Handler for requests that matched no route
+     */
+    private notFoundHandler?;
+    /**
+     * Whether the adapter logs errors before handing them to the application.
+     * Set false when your own handler already logs with a correlation id.
+     */
+    private readonly logErrors;
     /**
      * Global middlewares with route configuration
      * Structure: Array<{ middleware, config }>
@@ -72,7 +81,7 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * @param logger - Server logger instance
      * @param websocketAdapter - WebSocket adapter instance (optional)
      */
-    constructor(logger: ServerLogger, websocketAdapter?: ErgenecoreWebsocketAdapter);
+    constructor(logger: ServerLogger, websocketAdapter?: ErgenecoreWebsocketAdapter, logErrors?: boolean);
     /**
      * Registers a WebSocket route (deferred registration)
      *
@@ -173,6 +182,12 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * @param errorHandler - Error handler function
      */
     onError(errorHandler: ErrorHandler<Context>): void;
+    /**
+     * Registers the handler for requests that match no route.
+     *
+     * Separate from {@link onError}: a missing route is a routing outcome, not a thrown error.
+     */
+    onNotFound(notFoundHandler: NotFoundHandler<Context>): void;
     /**
      * Sets serve options
      *
@@ -223,6 +238,54 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * ```
      */
     private buildWebSocketRoutes;
+    /**
+     * Answers a request nothing served: an unmatched route, or a static file that does not exist.
+     *
+     * Both go through the application's `onNotFound` so an app has one place to shape its 404,
+     * and both fall back to the same JSON envelope the hono adapter uses.
+     *
+     * Deliberately NOT routed to `onError` - that hook is for errors the application threw.
+     */
+    private respondToUnmatched;
+    private resolveUnmatchedResponse;
+    /**
+     * Records a request the framework itself answered with a 404.
+     *
+     * Only reached when the application has no `onNotFound`, or when its hook declined or threw -
+     * an application that answered its own 404 already knows about the request. Without this an
+     * unmatched route was the one outcome that produced no output at any level, which is exactly
+     * the traffic (bots, probes, a typo in a deployed client) an operator needs to see.
+     *
+     * `info`, not `warn`: a scanner walking /wp-admin, /.env and /phpmyadmin must not be able to
+     * fill the warning stream. Not `debug` either - a 404 nobody can see is how a mistyped route
+     * survives to production.
+     */
+    private logUnmatched;
+    /**
+     * Logs an error before the application's handler sees it, at a level that matches the
+     * response the caller will get.
+     *
+     * This adapter used to log only when NO error handler was registered - which is to say,
+     * never in a real application, since every app configures `onError`. A 500 answered
+     * nothing to stdout and the stack was gone. The level split mirrors the hono adapter:
+     * 5xx is ours to fix and gets a stack, 4xx is the caller's and would otherwise let a bot
+     * scanning for /wp-admin flood the error stream.
+     */
+    private logHandledError;
+    /**
+     * Produces the response for a thrown error, in the same order the hono adapter uses.
+     *
+     * The application's handler gets first refusal on *every* error, `HttpException` included.
+     * Previously each catch block answered an `HttpException` straight from `getResponse()` and
+     * only consulted `errorHandler` for everything else, so an app could not reshape its own
+     * 401/403/404 envelopes. Worse, only one of the five catch blocks carried the
+     * `!isValidationError` exemption, so a `ValidationError` thrown on the fast path never
+     * reached `onError` at all - the exact opposite of why ValidationError exists.
+     *
+     * Falls back to the exception's own response (or a 500) when there is no handler, when the
+     * handler returns nothing, or when the handler itself throws.
+     */
+    private respondToError;
     /**
      * Executes middleware chain with recursive next() pattern
      *
@@ -342,7 +405,6 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * - Error handling
      *
      * @param route - Route parameters
-     * @param _commonMiddlewares - Common middlewares for this route group (for future optimization)
      * @returns Bun-compatible route handler
      */
     private createRouteHandler;
@@ -438,66 +500,6 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
      * ```
      */
     private buildStaticFileHeaders;
-    /**
-     * Extracts base path from a route path
-     *
-     * Removes dynamic segments (parameters and wildcards) from the path
-     * to find the static base path for grouping routes.
-     *
-     * @param path - Route path (e.g., "/api/users/:id")
-     * @returns Base path without dynamic segments (e.g., "/api/users")
-     *
-     * @example
-     * ```typescript
-     * extractBasePath('/api/users/:id') // => '/api/users'
-     * extractBasePath('/api/users/:id/posts/:postId') // => '/api/users'
-     * extractBasePath('/static/*') // => '/static'
-     * extractBasePath('/') // => '/'
-     * ```
-     */
-    private extractBasePath;
-    /**
-     * Extracts common middlewares across multiple routes
-     *
-     * Identifies middlewares that are present in ALL routes and can be
-     * moved to group level for optimization.
-     *
-     * @param routes - Array of routes to analyze
-     * @returns Array of common middleware instances
-     *
-     * @example
-     * ```typescript
-     * extractCommonMiddlewares([
-     *   { middlewares: [auth, log, rate] },
-     *   { middlewares: [auth, log] },
-     *   { middlewares: [auth, log] }
-     * ]) // => [auth, log]
-     * ```
-     */
-    private extractCommonMiddlewares;
-    /**
-     * Groups routes by their base path
-     *
-     * Creates a map of base paths to routes for optimization.
-     * Routes with the same base path will share common middlewares.
-     *
-     * @param routes - Array of routes to group
-     * @returns Map of base paths to route arrays
-     *
-     * @example
-     * ```typescript
-     * groupRoutesByBasePath([
-     *   { path: '/api/users' },
-     *   { path: '/api/users/:id' },
-     *   { path: '/api/posts' }
-     * ])
-     * // => Map {
-     * //   '/api/users' => [route1, route2],
-     * //   '/api/posts' => [route3]
-     * // }
-     * ```
-     */
-    private groupRoutesByBasePath;
     get hostname(): any;
     set hostname(value: any);
     /**