@asenajs/ergenecore 1.0.0

package/dist/lib/Ergenecore.d.ts

@@ -0,0 +1,598 @@
+import type { WebsocketRouteParams } from '@asenajs/asena/adapter';
+import { AsenaAdapter, type AsenaServeOptions, type BaseMiddleware, type ErrorHandler, 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';
+import { type Context } from './ErgenecoreContextWrapper';
+import type { Server } from 'bun';
+import type { ValidationSchema, ValidationSchemaWithHook } from './types';
+/**
+ * CoreAdapter - Native Bun adapter for Asenajs
+ *
+ * High-performance HTTP adapter using Bun's native APIs exclusively:
+ * - SIMD-accelerated routing
+ * - Native Request/Response
+ * - Zero framework overhead
+ * - Built-in parameter extraction
+ */
+export declare class Ergenecore extends AsenaAdapter<Context, ValidationSchemaWithHook | ValidationSchema> {
+    /**
+     * Adapter name
+     */
+    name: string;
+    /**
+     * Server port (inherited from AsenaAdapter but needs override for initialization)
+     */
+    protected port: number;
+    /**
+     * Server hostname
+     */
+    private _hostname;
+    /**
+     * Bun server instance
+     */
+    private server;
+    /**
+     * Route queue for deferred registration
+     * Routes are queued during initialization and built when server starts
+     */
+    private routeQueue;
+    /**
+     * WebSocket route queue for deferred registration
+     * WebSocket routes are queued during initialization and built when server starts
+     */
+    private wsRouteQueue;
+    /**
+     * Flag to track if routes have been built
+     */
+    private routesBuilt;
+    /**
+     * Error handler function
+     */
+    private errorHandler?;
+    /**
+     * Global middlewares with route configuration
+     * Structure: Array<{ middleware, config }>
+     * Config is optional - if not provided, middleware applies to all routes
+     */
+    private globalMiddlewares;
+    private options;
+    /**
+     * Creates a new CoreAdapter instance
+     *
+     * @param logger - Server logger instance
+     * @param websocketAdapter - WebSocket adapter instance (optional)
+     */
+    constructor(logger: ServerLogger, websocketAdapter?: ErgenecoreWebsocketAdapter);
+    /**
+     * Registers a WebSocket route (deferred registration)
+     *
+     * Routes are queued and will be built into Bun's native router format
+     * when the server starts. Supports middleware chain execution before
+     * WebSocket upgrade.
+     *
+     * @param params - WebSocket route parameters (path, middlewares, websocketService)
+     *
+     * @example
+     * ```typescript
+     * adapter.registerWebsocketRoute({
+     *   path: '/chat',
+     *   middlewares: [authMiddleware],
+     *   websocketService: chatService
+     * });
+     * ```
+     */
+    registerWebsocketRoute(params: WebsocketRouteParams<Context>): void;
+    /**
+     * Sets the server port
+     *
+     * @param port - Port number
+     */
+    setPort(port: number): void;
+    /**
+     * Registers a global middleware with optional pattern matching
+     *
+     * @param middleware - Middleware instance
+     * @param config - Optional route configuration for pattern matching
+     *
+     * @example
+     * ```typescript
+     * // Old API (still supported) - applies to all routes
+     * adapter.use(loggerMiddleware);
+     *
+     * // New API with pattern matching - applies only to matching routes
+     * adapter.use(authMiddleware, {
+     *   include: ['/api/*', '/admin/*'],
+     *   exclude: ['/api/health']
+     * });
+     * ```
+     */
+    use(middleware: BaseMiddleware<Context>, config?: GlobalMiddlewareConfig['routes']): void;
+    /**
+     * Registers a route (deferred registration)
+     *
+     * Routes are queued and will be built into Bun's native router format
+     * when the server starts.
+     *
+     * @param params - Route parameters
+     *
+     * @example
+     * ```typescript
+     * adapter.registerRoute({
+     *   method: HttpMethod.GET,
+     *   path: '/users/:id',
+     *   middlewares: [],
+     *   handler: async (ctx) => ctx.send({ id: ctx.getParam('id') })
+     * });
+     * ```
+     */
+    registerRoute(params: RouteParams<Context, ValidationSchemaWithHook>): void;
+    /**
+     * Starts the Bun server
+     *
+     * Builds routes from queue (HTTP + WebSocket) and starts Bun.serve() with native router.
+     *
+     * Process:
+     * 1. Build HTTP routes from route queue
+     * 2. Build WebSocket routes from WebSocket route queue
+     * 3. Check for path collisions (HTTP GET vs WebSocket GET)
+     * 4. Merge HTTP and WebSocket routes
+     * 5. Prepare WebSocket adapter
+     * 6. Start Bun server with merged routes
+     *
+     * @param port - Optional port to override default
+     * @returns Bun server instance
+     */
+    start(port?: number): Server<any>;
+    /**
+     * Stops the server
+     *
+     * @param closeActiveConnections - Whether to close active connections
+     */
+    stop(closeActiveConnections?: boolean): Promise<void>;
+    /**
+     * Sets the error handler
+     *
+     * @param errorHandler - Error handler function
+     */
+    onError(errorHandler: ErrorHandler<Context>): void;
+    /**
+     * Sets serve options
+     *
+     * @param options - Serve options function
+     */
+    serveOptions(options: () => Promise<AsenaServeOptions> | AsenaServeOptions): Promise<void>;
+    /**
+     * Builds Bun native router object from queued routes
+     *
+     * Optimizations applied:
+     * 1. Base path extraction - Groups routes by static base path
+     * 2. Common middleware detection - Identifies shared middlewares per group
+     * 3. Middleware deduplication - Reduces redundant middleware execution
+     *
+     * Converts Asena route format to Bun's native router format:
+     * ```typescript
+     * {
+     *   "/users": {
+     *     GET: (req) => Response,
+     *     POST: (req) => Response
+     *   },
+     *   "/users/:id": {
+     *     GET: (req) => Response
+     *   }
+     * }
+     * ```
+     *
+     * @returns Bun router object
+     */
+    private buildBunRoutes;
+    /**
+     * Builds WebSocket routes from queued WebSocket route registrations
+     *
+     * Converts Asena WebSocket route format to Bun's native router format
+     * with middleware chain support. Each WebSocket route creates a GET
+     * handler that executes middlewares before attempting WebSocket upgrade.
+     *
+     * @returns Bun router object for WebSocket routes
+     *
+     * @example
+     * ```typescript
+     * // Returns:
+     * {
+     *   "/chat": {
+     *     GET: (req) => Response | undefined // upgrade handler with middlewares
+     *   }
+     * }
+     * ```
+     */
+    private buildWebSocketRoutes;
+    /**
+     * Executes middleware chain with recursive next() pattern
+     *
+     * Middlewares can control execution flow by:
+     * - Calling await next() to proceed to next middleware
+     * - Returning false to stop pipeline (403 response)
+     * - Returning Response to send custom response and stop pipeline
+     * - Throwing HttpException to send custom HTTP error response
+     * - Throwing error to trigger error handler
+     *
+     * @param context - Request context
+     * @param middlewares - Array of middlewares to execute
+     * @param index - Current middleware index (internal)
+     * @returns Promise<boolean | Response> - true to continue, false to stop with 403, Response to send custom response
+     *
+     * @example
+     * ```typescript
+     * const result = await this.executeMiddlewares(context, globalMiddlewares);
+     * if (result === false) {
+     *   return new Response('Forbidden', { status: 403 });
+     * }
+     * if (result instanceof Response) {
+     *   return result;
+     * }
+     * ```
+     */
+    private executeMiddlewares;
+    /**
+     * Creates a WebSocket upgrade handler with middleware chain support
+     *
+     * The handler executes in the following order:
+     * 1. Create context wrapper
+     * 2. Execute global middlewares (pattern-filtered, if any return false, reject with 403)
+     * 3. Execute route-specific middlewares (if any return false, reject with 403)
+     * 4. Attempt WebSocket upgrade via server.upgrade()
+     * 5. Return undefined if upgrade successful, error response otherwise
+     *
+     * @param wsRoute - WebSocket route parameters
+     * @returns Bun-compatible WebSocket upgrade handler
+     *
+     * @example
+     * ```typescript
+     * const handler = createWebSocketUpgradeHandler({
+     *   path: '/chat',
+     *   middlewares: [authMiddleware],
+     *   websocketService: chatService
+     * });
+     * // handler(req) => Response | undefined
+     * ```
+     */
+    private createWebSocketUpgradeHandler;
+    /**
+     * Checks for path collisions between HTTP and WebSocket routes
+     *
+     * Validates that no HTTP GET route conflicts with a WebSocket route
+     * on the same path, as both use GET method for their handlers.
+     *
+     * @param httpRoutes - HTTP routes object from buildBunRoutes()
+     * @param wsRoutes - WebSocket routes object from buildWebSocketRoutes()
+     * @throws Error if collision detected
+     *
+     * @example
+     * ```typescript
+     * checkPathCollisions(
+     *   { "/api/data": { GET: handler1 } },
+     *   { "/api/data": { GET: wsHandler } }
+     * );
+     * // Throws: Route collision detected at path "/api/data": Both HTTP and WebSocket routes define GET method
+     * ```
+     */
+    private checkPathCollisions;
+    /**
+     * Merges HTTP and WebSocket routes into a single router object
+     *
+     * Combines routes from buildBunRoutes() and buildWebSocketRoutes(),
+     * ensuring that methods on the same path are properly merged.
+     *
+     * @param httpRoutes - HTTP routes object
+     * @param wsRoutes - WebSocket routes object
+     * @returns Merged routes object
+     *
+     * @example
+     * ```typescript
+     * mergeRoutes(
+     *   { "/api": { POST: handler1, PUT: handler2 } },
+     *   { "/api": { GET: wsHandler } }
+     * );
+     * // Returns: { "/api": { POST: handler1, PUT: handler2, GET: wsHandler } }
+     * ```
+     */
+    private mergeRoutes;
+    /**
+     * Creates a fast path handler for simple routes
+     *
+     * This handler is optimized for routes without:
+     * - Middlewares (global or route-level)
+     * - Validators
+     * - Static file serving
+     *
+     * Benefits:
+     * - Minimal object allocation
+     * - No conditional checks
+     * - Direct handler execution
+     * - Reduced try-catch overhead
+     *
+     * @param route - Route parameters
+     * @returns Bun-compatible fast path handler
+     */
+    private createFastPathHandler;
+    /**
+     * Creates a route handler function for Bun's router
+     *
+     * Wraps the Asena handler with:
+     * - CoreContextWrapper for context abstraction
+     * - Parameter injection from Bun's native parser
+     * - Global and route middlewares (pattern-filtered)
+     * - Error handling
+     *
+     * @param route - Route parameters
+     * @param _commonMiddlewares - Common middlewares for this route group (for future optimization)
+     * @returns Bun-compatible route handler
+     */
+    private createRouteHandler;
+    /**
+     * Type guard to check if validation schema has hook format
+     *
+     * Discriminates between ValidationSchemaWithHook and plain ValidationSchema.
+     * Uses runtime check for 'schema' property to determine type.
+     *
+     * @param schema - Validation schema to check
+     * @returns true if schema is ValidationSchemaWithHook format
+     *
+     * @example
+     * ```typescript
+     * if (isValidationSchemaWithHook(schema)) {
+     *   // schema.schema and schema.hook are available
+     * } else {
+     *   // schema is a plain Zod schema
+     * }
+     * ```
+     */
+    private isValidationSchemaWithHook;
+    /**
+     * Validates request data using Zod schemas
+     *
+     * Checks each validation target (body, query, param, header) and runs
+     * the Zod schema validation. If validation fails and a hook is provided,
+     * the hook is called to generate a custom error response.
+     *
+     * Supports two validation formats:
+     * 1. Plain Zod schema: z.object({...})
+     * 2. Schema with hook: { schema: z.object({...}), hook?: (...) => {...} }
+     *
+     * @param context - Request context
+     * @param validator - Validator instance with schema definitions
+     * @returns Response if validation fails, null if passes
+     */
+    private validateRequest;
+    /**
+     * Extracts data from request based on validation target
+     *
+     * @param context - Request context
+     * @param target - Validation target (body, query, param, header)
+     * @returns Data to be validated
+     */
+    private extractValidationData;
+    /**
+     * Serves static files using Bun.file() API
+     *
+     * This method handles static file serving with the following features:
+     * - Path rewriting via rewriteRequestPath
+     * - Root directory resolution
+     * - File existence checking
+     * - onFound/onNotFound hooks
+     * - Automatic MIME type detection (via Bun.file())
+     *
+     * @param req - Native Bun Request object
+     * @param context - ErgenecoreContextWrapper instance
+     * @param staticServe - Static serve configuration from route
+     * @returns Response object if file found/not found, null if hooks override
+     *
+     * @example
+     * ```typescript
+     * const response = await this.serveStaticFile(req, context, {
+     *   root: '/public',
+     *   rewriteRequestPath: (path) => path.replace('/static', ''),
+     *   onFound: { handler: async () => {}, override: false },
+     *   onNotFound: { handler: async () => {}, override: false }
+     * });
+     * ```
+     */
+    private serveStaticFile;
+    /**
+     * Builds response headers for static file serving
+     *
+     * Constructs headers with:
+     * - Content-Type (custom MIME or Bun default)
+     * - Cache-Control (if specified)
+     * - Custom headers (if specified)
+     *
+     * @param filePath - Resolved absolute file path
+     * @param extras - StaticServeExtras configuration
+     * @returns Headers object for Response
+     *
+     * @example
+     * ```typescript
+     * const headers = this.buildStaticFileHeaders('/app/public/style.css', {
+     *   cacheControl: 'public, max-age=86400',
+     *   headers: { 'X-Custom': 'value' },
+     *   mimes: { '.css': 'text/css; charset=utf-8' }
+     * });
+     * // Returns: { 'Content-Type': 'text/css; charset=utf-8', 'Cache-Control': '...', 'X-Custom': 'value' }
+     * ```
+     */
+    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);
+    /**
+     * 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;
+    /**
+     * Filters global middlewares for a specific route path
+     *
+     * Uses pattern matching to determine which middlewares should apply to this path.
+     * Pattern matching happens ONCE during route building (deferred registration),
+     * not on every request, ensuring zero runtime overhead.
+     *
+     * @param path - Route path (e.g., '/api/users', '/users/:id')
+     * @returns Array of middlewares that should apply to this path
+     *
+     * @example
+     * ```typescript
+     * // Given:
+     * // - LoggerMiddleware (no config → applies to all routes)
+     * // - AuthMiddleware (include: ['/api/*'])
+     * // - RateLimitMiddleware (exclude: ['/health'])
+     *
+     * getGlobalMiddlewaresForPath('/api/users')
+     * // => [LoggerMiddleware, AuthMiddleware, RateLimitMiddleware]
+     *
+     * getGlobalMiddlewaresForPath('/health')
+     * // => [LoggerMiddleware, AuthMiddleware] (RateLimit excluded)
+     *
+     * getGlobalMiddlewaresForPath('/public/page')
+     * // => [LoggerMiddleware, RateLimitMiddleware] (Auth not included)
+     * ```
+     */
+    private getGlobalMiddlewaresForPath;
+    /**
+     * Logs a summary of registered controllers
+     *
+     * Displays colored success messages for each controller with route counts.
+     * HTTP controllers show total HTTP routes, WebSocket-only controllers are
+     * displayed separately.
+     *
+     * @example
+     * Output format:
+     * ```
+     * ✓ Successfully registered CONTROLLER UserController (2 routes)
+     * ✓ Successfully registered WEBSOCKET ChatController (1 route)
+     * ```
+     */
+    private logControllerSummary;
+    /**
+     * Builds controller-based log output with colors
+     *
+     * Creates a formatted string showing all routes grouped by controller,
+     * with HTTP controllers listed first, then WebSocket namespaces separately.
+     *
+     * Color scheme:
+     * - Controller name: blue
+     * - Base path: yellow
+     * - GET method: green
+     * - POST method: blue
+     * - PUT method: yellow
+     * - DELETE method: red
+     * - WS method: blue
+     *
+     * @returns Formatted log string with color codes
+     *
+     * @example
+     * Output format:
+     * ```
+     *   UserController (/users):
+     *     GET /users
+     *     GET /users/:id
+     *     POST /users
+     *
+     *   ChatNamespace (chat):
+     *     WS /chat
+     * ```
+     */
+    private buildControllerBasedLog;
+}