@onebun/core 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/application/application.test.ts

@@ -1000,6 +1000,243 @@ describe('OneBunApplication', () => {
         title: 'Post 123 by User 42',
       });
     });
+
+    test('should handle trailing slashes - route without trailing slash matches request with trailing slash', async () => {
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/users/:page')
+        async getUsers(@Param('page') page: string) {
+          return { users: ['Alice', 'Bob'], page: parseInt(page) };
+        }
+      }
+
+      @Module({
+        controllers: [ApiController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Request WITH trailing slash should match route WITHOUT trailing slash
+      const request = new Request('http://localhost:3000/api/users/1/', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const response = await (mockServer as any).fetchHandler(request);
+
+      // Should return 200, not 404 (route should be found)
+      expect(response).toBeInstanceOf(Response);
+      expect(response.status).toBe(200);
+
+      const body = await response.json();
+      expect(body.result).toEqual({ users: ['Alice', 'Bob'], page: 1 });
+    });
+
+    test('should handle trailing slashes - both with and without slash return same result', async () => {
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/items/:category')
+        async getItems(@Param('category') category: string) {
+          return { items: [1, 2, 3], category };
+        }
+      }
+
+      @Module({
+        controllers: [ApiController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Request WITHOUT trailing slash
+      const requestWithout = new Request('http://localhost:3000/api/items/electronics', {
+        method: 'GET',
+      });
+
+      // Request WITH trailing slash
+      const requestWith = new Request('http://localhost:3000/api/items/electronics/', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const responseWithout = await (mockServer as any).fetchHandler(requestWithout);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const responseWith = await (mockServer as any).fetchHandler(requestWith);
+
+      // Both should be valid Response objects
+      expect(responseWithout).toBeInstanceOf(Response);
+      expect(responseWith).toBeInstanceOf(Response);
+
+      // Both should return 200 (not 404)
+      expect(responseWithout.status).toBe(200);
+      expect(responseWith.status).toBe(200);
+
+      const bodyWithout = await responseWithout.json();
+      const bodyWith = await responseWith.json();
+
+      expect(bodyWithout.result).toEqual(bodyWith.result);
+    });
+
+    test('should handle trailing slashes with route parameters', async () => {
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/users/:id')
+        async getUser(@Param('id') id: string) {
+          return { id: parseInt(id) };
+        }
+      }
+
+      @Module({
+        controllers: [ApiController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Request WITH trailing slash on parameterized route
+      const request = new Request('http://localhost:3000/api/users/123/', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const response = await (mockServer as any).fetchHandler(request);
+      const body = await response.json();
+
+      expect(response.status).toBe(200);
+      expect(body.result).toEqual({ id: 123 });
+    });
+
+    test('should handle root path correctly (no trailing slash removal)', async () => {
+      @Controller('/root')
+      class RootController extends BaseController {
+        @Get('/:id')
+        async getById(@Param('id') id: string) {
+          return { message: 'root', id };
+        }
+      }
+
+      @Module({
+        controllers: [RootController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Test that trailing slash is handled correctly even for short paths
+      const request = new Request('http://localhost:3000/root/42/', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const response = await (mockServer as any).fetchHandler(request);
+
+      expect(response).toBeInstanceOf(Response);
+      expect(response.status).toBe(200);
+
+      const body = await response.json();
+      expect(body.result).toEqual({ message: 'root', id: '42' });
+    });
+
+    test('should handle exact root path with trailing slash', async () => {
+      @Controller('/health')
+      class HealthController extends BaseController {
+        @Get('/:type')
+        async check(@Param('type') type: string) {
+          return { status: 'ok', type };
+        }
+      }
+
+      @Module({
+        controllers: [HealthController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Root path "/" should remain "/" after normalization
+      const requestWithSlash = new Request('http://localhost:3000/health/live/', {
+        method: 'GET',
+      });
+
+      const requestWithoutSlash = new Request('http://localhost:3000/health/live', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const responseWith = await (mockServer as any).fetchHandler(requestWithSlash);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const responseWithout = await (mockServer as any).fetchHandler(requestWithoutSlash);
+
+      // Both should work identically
+      expect(responseWith.status).toBe(200);
+      expect(responseWithout.status).toBe(200);
+
+      const bodyWith = await responseWith.json();
+      const bodyWithout = await responseWithout.json();
+      expect(bodyWith.result).toEqual(bodyWithout.result);
+    });
+
+    test('should normalize metrics route labels - trailing slash requests use same label as non-trailing', async () => {
+      @Controller('/api')
+      class ApiController extends BaseController {
+        @Get('/data')
+        async getData() {
+          return { data: 'test' };
+        }
+      }
+
+      @Module({
+        controllers: [ApiController],
+      })
+      class TestModule {}
+
+      const app = createTestApp(TestModule, {
+        metrics: { path: '/metrics' },
+      });
+
+      // Track recorded metrics
+      const recordedMetrics: Array<{ route: string }> = [];
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const mockMetricsService: any = {
+        getMetrics: mock(() => Promise.resolve('# metrics data')),
+        getContentType: mock(() => 'text/plain'),
+        startSystemMetricsCollection: mock(),
+        recordHttpRequest: mock((data: { route: string }) => {
+          recordedMetrics.push({ route: data.route });
+        }),
+      };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (app as any).metricsService = mockMetricsService;
+
+      await app.start();
+
+      // Make requests with both trailing and non-trailing slash
+      const requestWithout = new Request('http://localhost:3000/api/data', {
+        method: 'GET',
+      });
+      const requestWith = new Request('http://localhost:3000/api/data/', {
+        method: 'GET',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await (mockServer as any).fetchHandler(requestWithout);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await (mockServer as any).fetchHandler(requestWith);
+
+      // Both requests should record metrics with the same route label (without trailing slash)
+      expect(recordedMetrics.length).toBe(2);
+      expect(recordedMetrics[0].route).toBe('/api/data');
+      expect(recordedMetrics[1].route).toBe('/api/data');
+      // Verify they are the same (no duplication due to trailing slash)
+      expect(recordedMetrics[0].route).toBe(recordedMetrics[1].route);
+    });
   });
 
   describe('Tracing integration', () => {

package/src/application/application.ts

@@ -50,6 +50,21 @@ try {
   // Metrics module not available - this is optional
 }
 
+// Conditionally import docs (optional dependency - not added to package.json to avoid circular deps)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let generateOpenApiSpec: any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let generateSwaggerUiHtml: any;
+
+try {
+  // eslint-disable-next-line import/no-extraneous-dependencies
+  const docsModule = require('@onebun/docs');
+  generateOpenApiSpec = docsModule.generateOpenApiSpec;
+  generateSwaggerUiHtml = docsModule.generateSwaggerUiHtml;
+} catch {
+  // Docs module not available - this is optional
+}
+
 // Import tracing modules directly
 
 // Global trace context for current request
@@ -63,6 +78,26 @@ function clearGlobalTraceContext(): void {
   }
 }
 
+/**
+ * Normalize URL path by removing trailing slashes (except for root path).
+ * This ensures consistent route matching and metrics collection.
+ * 
+ * @param path - The URL path to normalize
+ * @returns Normalized path without trailing slash
+ * @example
+ * normalizePath('/users/') // => '/users'
+ * normalizePath('/users')  // => '/users'
+ * normalizePath('/')       // => '/'
+ * normalizePath('/api/v1/') // => '/api/v1'
+ */
+function normalizePath(path: string): string {
+  if (path === '/' || path.length <= 1) {
+    return path;
+  }
+
+  return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
 /**
  * OneBun Application
  */
@@ -85,6 +120,9 @@ export class OneBunApplication {
   private wsHandler: WsHandler | null = null;
   private queueService: QueueService | null = null;
   private queueAdapter: QueueAdapter | null = null;
+  // Docs (OpenAPI/Swagger) - generated on start()
+  private openApiSpec: Record<string, unknown> | null = null;
+  private swaggerHtml: string | null = null;
 
   /**
    * Create application instance
@@ -287,6 +325,9 @@ export class OneBunApplication {
       // Initialize Queue system if configured or handlers exist
       await this.initializeQueue(controllers);
 
+      // Initialize Docs (OpenAPI/Swagger) if enabled and available
+      await this.initializeDocs(controllers);
+
       // Create a map of routes with metadata
       const routes = new Map<
         string,
@@ -384,6 +425,10 @@ export class OneBunApplication {
       // Get metrics path
       const metricsPath = this.options.metrics?.path || '/metrics';
 
+      // Get docs paths
+      const docsPath = this.options.docs?.path || '/docs';
+      const openApiPath = this.options.docs?.jsonPath || '/openapi.json';
+
       // Create server with proper context binding
       const app = this;
       const hasWebSocketGateways = this.wsHandler?.hasGateways() ?? false;
@@ -408,7 +453,10 @@ export class OneBunApplication {
         websocket: wsHandlers,
         async fetch(req, server) {
           const url = new URL(req.url);
-          const path = url.pathname;
+          const rawPath = url.pathname;
+          // Normalize path to ensure consistent routing and metrics
+          // (removes trailing slash except for root path)
+          const path = normalizePath(rawPath);
           const method = req.method;
           const startTime = Date.now();
 
@@ -498,6 +546,29 @@ export class OneBunApplication {
             }
           }
 
+          // Handle docs endpoints (OpenAPI/Swagger)
+          if (app.options.docs?.enabled !== false && app.openApiSpec) {
+            // Serve Swagger UI HTML
+            if (path === docsPath && method === 'GET' && app.swaggerHtml) {
+              return new Response(app.swaggerHtml, {
+                headers: {
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'Content-Type': 'text/html; charset=utf-8',
+                },
+              });
+            }
+
+            // Serve OpenAPI JSON spec
+            if (path === openApiPath && method === 'GET') {
+              return new Response(JSON.stringify(app.openApiSpec, null, 2), {
+                headers: {
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'Content-Type': 'application/json',
+                },
+              });
+            }
+          }
+
           // Handle metrics endpoint
           if (path === metricsPath && method === 'GET' && app.metricsService) {
             try {
@@ -1122,6 +1193,80 @@ export class OneBunApplication {
     return this.queueService;
   }
 
+  /**
+   * Initialize the documentation system (OpenAPI/Swagger)
+   */
+  private async initializeDocs(controllers: Function[]): Promise<void> {
+    const docsOptions = this.options.docs;
+
+    // Skip if docs are explicitly disabled or @onebun/docs is not available
+    if (docsOptions?.enabled === false) {
+      this.logger.debug('Documentation explicitly disabled');
+
+      return;
+    }
+
+    if (!generateOpenApiSpec || !generateSwaggerUiHtml) {
+      if (docsOptions?.enabled === true) {
+        this.logger.warn(
+          'Documentation enabled but @onebun/docs module not available. Install with: bun add @onebun/docs',
+        );
+      } else {
+        this.logger.debug('@onebun/docs module not available, documentation disabled');
+      }
+
+      return;
+    }
+
+    try {
+      // Generate OpenAPI spec from controllers
+      this.openApiSpec = generateOpenApiSpec(controllers, {
+        title: docsOptions?.title || this.options.name || 'OneBun API',
+        version: docsOptions?.version || '1.0.0',
+        description: docsOptions?.description,
+      });
+
+      // Add additional OpenAPI info if provided
+      if (this.openApiSpec && docsOptions?.contact) {
+        (this.openApiSpec.info as Record<string, unknown>).contact = docsOptions.contact;
+      }
+      if (this.openApiSpec && docsOptions?.license) {
+        (this.openApiSpec.info as Record<string, unknown>).license = docsOptions.license;
+      }
+      if (this.openApiSpec && docsOptions?.externalDocs) {
+        this.openApiSpec.externalDocs = docsOptions.externalDocs;
+      }
+      if (this.openApiSpec && docsOptions?.servers && docsOptions.servers.length > 0) {
+        this.openApiSpec.servers = docsOptions.servers;
+      }
+
+      // Generate Swagger UI HTML
+      const openApiPath = docsOptions?.jsonPath || '/openapi.json';
+      this.swaggerHtml = generateSwaggerUiHtml(openApiPath);
+
+      const docsPath = docsOptions?.path || '/docs';
+      this.logger.info(
+        `Documentation available at http://${this.options.host}:${this.options.port}${docsPath}`,
+      );
+      this.logger.info(
+        `OpenAPI spec available at http://${this.options.host}:${this.options.port}${openApiPath}`,
+      );
+    } catch (error) {
+      this.logger.error(
+        'Failed to initialize documentation:',
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
+  /**
+   * Get the OpenAPI specification
+   * @returns The OpenAPI spec or null if not generated
+   */
+  getOpenApiSpec(): Record<string, unknown> | null {
+    return this.openApiSpec;
+  }
+
   /**
    * Register signal handlers for graceful shutdown
    * Call this after start() to enable automatic shutdown on SIGTERM/SIGINT

package/src/index.ts

@@ -33,6 +33,8 @@ export {
   type WsStorageType,
   type WsStorageOptions,
   type WebSocketApplicationOptions,
+  // Docs types
+  type DocsApplicationOptions,
 } from './types';
 
 // Decorators and Metadata (exports Controller decorator, Module decorator, etc.)

package/src/types.ts

@@ -277,6 +277,11 @@ export interface ApplicationOptions {
    */
   queue?: QueueApplicationOptions;
 
+  /**
+   * Documentation configuration (OpenAPI/Swagger)
+   */
+  docs?: DocsApplicationOptions;
+
   /**
    * Enable graceful shutdown on SIGTERM/SIGINT
    * When enabled, the application will cleanly shutdown on process signals,
@@ -347,6 +352,80 @@ export interface WebSocketApplicationOptions {
   maxPayload?: number;
 }
 
+/**
+ * Documentation configuration for OneBunApplication
+ * Enables automatic OpenAPI spec generation and Swagger UI
+ */
+export interface DocsApplicationOptions {
+  /**
+   * Enable/disable documentation endpoints
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * Path for Swagger UI
+   * @defaultValue '/docs'
+   */
+  path?: string;
+
+  /**
+   * Path for OpenAPI JSON specification
+   * @defaultValue '/openapi.json'
+   */
+  jsonPath?: string;
+
+  /**
+   * API title for OpenAPI spec
+   * @defaultValue Application name or 'OneBun API'
+   */
+  title?: string;
+
+  /**
+   * API version for OpenAPI spec
+   * @defaultValue '1.0.0'
+   */
+  version?: string;
+
+  /**
+   * API description for OpenAPI spec
+   */
+  description?: string;
+
+  /**
+   * Contact information
+   */
+  contact?: {
+    name?: string;
+    email?: string;
+    url?: string;
+  };
+
+  /**
+   * License information
+   */
+  license?: {
+    name: string;
+    url?: string;
+  };
+
+  /**
+   * External documentation link
+   */
+  externalDocs?: {
+    description?: string;
+    url: string;
+  };
+
+  /**
+   * Server URLs for OpenAPI spec
+   */
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+}
+
 /**
  * HTTP method types
  */