@asenajs/ergenecore 1.5.0 → 3.0.0

package/README.md

@@ -1,5 +1,8 @@
 # Asena Ergenecore Adapter
 
+[![Version](https://img.shields.io/badge/version-3.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:
@@ -17,7 +20,7 @@ Built on Bun runtime for exceptional performance:
 
 ## Features
 
-- ⚡ **Zero Dependencies** - Pure Bun native APIs (except Zod for validation)
+- ⚡ **Zero Dependencies** - no runtime dependencies at all; Zod is a peer your project owns
 - 🚀 **SIMD-Accelerated** - Native Bun router with SIMD-optimized matching
 - 🔌 **Full Adapter Support** - HTTP, WebSocket, Middleware, Validation
 - 📦 **Zero-Copy File Serving** - Bun.file() for optimal static file performance
@@ -31,20 +34,31 @@ Ergenecore is the **fastest** Asena adapter because it:
 - Uses Bun's **native HTTP server** (`Bun.serve()`)
 - Leverages **SIMD-accelerated routing** (no framework overhead)
 - Implements **zero-copy** file serving with `Bun.file()`
-- Has **no external dependencies** (except Zod)
+- Has **no runtime dependencies at all** (Zod is a peer your project owns)
 - Is optimized for **Bun runtime** exclusively
 
 ## Requirements
 
 - [Bun](https://bun.sh) v1.3.12 or higher
+- [@asenajs/asena](https://github.com/AsenaJs/Asena) v0.10.0 or higher (peer dependency)
+- [Zod](https://zod.dev) v4.3.6 or higher (peer dependency)
 - TypeScript v5.8.2 or higher
 
 ## Installation
 
 ```bash
-bun add @asenajs/ergenecore
+bun add @asenajs/ergenecore zod
 ```
 
+`zod` is a **peer dependency** - the adapter defines the validation contract, your project owns the
+library and its version.
+
+| Package manager | Command |
+|:--|:--|
+| bun, npm 7+, pnpm 8+ | `bun add zod` — peers auto-install, but declare them anyway so they survive a clean install |
+| yarn 1 | `yarn add zod` — **required**, yarn 1 does not install peers for you |
+
+
 ## Quick Start
 
 ### Basic Server Setup
@@ -609,7 +623,8 @@ import { isValidationError } from '@asenajs/asena/adapter';
 export class ExceptionMapper {
   map(error: Error, context: Context): Response {
     // Request validation failures arrive here like any other error.
-    // Check this before `instanceof HttpException` - ValidationError extends it
+    // Check this before the generic `isHttpException()` branch - a ValidationError is an
+    // HTTP exception too, so the generic branch would otherwise swallow it
     if (isValidationError(error)) {
       return context.send({ error: 'Validation failed', details: error.issues }, 400);
     }
@@ -635,7 +650,7 @@ Contributions are welcome! Please follow these guidelines:
 
 1. Follow the **TDD approach** (write tests first)
 2. Maintain **90%+ test coverage**
-3. Use **Bun native APIs** only (no external dependencies except Zod)
+3. Use **Bun native APIs** only (no runtime dependencies; Zod is a peer)
 4. Follow the **CLAUDE.md** guidelines
 
 ## License

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)
      *
@@ -164,6 +173,11 @@ export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWi
     /**
      * Stops the server
      *
+     * The HTTP socket closes first and the WebSocket layer second - the reverse of the order
+     * start() brought them up, since the transport is initialised *after* Bun.serve(). A close
+     * handler running during the drain may still broadcast, so the transport has to outlive the
+     * sockets that use it.
+     *
      * @param closeActiveConnections - Whether to close active connections
      */
     stop(closeActiveConnections?: boolean): Promise<void>;
@@ -173,6 +187,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 +243,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 +410,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 +505,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);
     /**