bxo 0.0.4 → 0.0.5-dev.10

package/index.ts

@@ -3,12 +3,26 @@ import { z } from 'zod';
 // Type utilities for extracting types from Zod schemas
 type InferZodType<T> = T extends z.ZodType<infer U> ? U : never;
 
+// OpenAPI detail information
+interface RouteDetail {
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  operationId?: string;
+  deprecated?: boolean;
+  produces?: string[];
+  consumes?: string[];
+  [key: string]: any; // Allow additional OpenAPI properties
+}
+
 // Configuration interface for route handlers
 interface RouteConfig {
   params?: z.ZodSchema<any>;
   query?: z.ZodSchema<any>;
   body?: z.ZodSchema<any>;
   headers?: z.ZodSchema<any>;
+  response?: z.ZodSchema<any>;
+  detail?: RouteDetail;
 }
 
 // Context type that's fully typed based on the route configuration
@@ -17,6 +31,7 @@ export type Context<TConfig extends RouteConfig = {}> = {
   query: TConfig['query'] extends z.ZodSchema<any> ? InferZodType<TConfig['query']> : Record<string, string | undefined>;
   body: TConfig['body'] extends z.ZodSchema<any> ? InferZodType<TConfig['body']> : unknown;
   headers: TConfig['headers'] extends z.ZodSchema<any> ? InferZodType<TConfig['headers']> : Record<string, string>;
+  path: string;
   request: Request;
   set: {
     status?: number;
@@ -38,72 +53,90 @@ interface Route {
   config?: RouteConfig;
 }
 
+// WebSocket handler interface
+interface WebSocketHandler {
+  onOpen?: (ws: any) => void;
+  onMessage?: (ws: any, message: string | Buffer) => void;
+  onClose?: (ws: any, code?: number, reason?: string) => void;
+  onError?: (ws: any, error: Error) => void;
+}
+
+// WebSocket route definition
+interface WSRoute {
+  path: string;
+  handler: WebSocketHandler;
+}
+
 // Lifecycle hooks
 interface LifecycleHooks {
-  onBeforeStart?: () => Promise<void> | void;
-  onAfterStart?: () => Promise<void> | void;
-  onBeforeStop?: () => Promise<void> | void;
-  onAfterStop?: () => Promise<void> | void;
-  onBeforeRestart?: () => Promise<void> | void;
-  onAfterRestart?: () => Promise<void> | void;
-  onRequest?: (ctx: Context) => Promise<void> | void;
-  onResponse?: (ctx: Context, response: any) => Promise<any> | any;
-  onError?: (ctx: Context, error: Error) => Promise<any> | any;
+  onBeforeStart?: (instance: BXO) => Promise<void> | void;
+  onAfterStart?: (instance: BXO) => Promise<void> | void;
+  onBeforeStop?: (instance: BXO) => Promise<void> | void;
+  onAfterStop?: (instance: BXO) => Promise<void> | void;
+  onBeforeRestart?: (instance: BXO) => Promise<void> | void;
+  onAfterRestart?: (instance: BXO) => Promise<void> | void;
+  onRequest?: (ctx: Context, instance: BXO) => Promise<void> | void;
+  onResponse?: (ctx: Context, response: any, instance: BXO) => Promise<any> | any;
+  onError?: (ctx: Context, error: Error, instance: BXO) => Promise<any> | any;
 }
 
 export default class BXO {
-  private routes: Route[] = [];
+  private _routes: Route[] = [];
+  private _wsRoutes: WSRoute[] = [];
   private plugins: BXO[] = [];
   private hooks: LifecycleHooks = {};
   private server?: any;
   private isRunning: boolean = false;
   private hotReloadEnabled: boolean = false;
   private watchedFiles: Set<string> = new Set();
+  private watchedExclude: Set<string> = new Set();
+  private serverPort?: number;
+  private serverHostname?: string;
 
   constructor() { }
 
   // Lifecycle hook methods
-  onBeforeStart(handler: () => Promise<void> | void): this {
+  onBeforeStart(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onBeforeStart = handler;
     return this;
   }
 
-  onAfterStart(handler: () => Promise<void> | void): this {
+  onAfterStart(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onAfterStart = handler;
     return this;
   }
 
-  onBeforeStop(handler: () => Promise<void> | void): this {
+  onBeforeStop(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onBeforeStop = handler;
     return this;
   }
 
-  onAfterStop(handler: () => Promise<void> | void): this {
+  onAfterStop(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onAfterStop = handler;
     return this;
   }
 
-  onBeforeRestart(handler: () => Promise<void> | void): this {
+  onBeforeRestart(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onBeforeRestart = handler;
     return this;
   }
 
-  onAfterRestart(handler: () => Promise<void> | void): this {
+  onAfterRestart(handler: (instance: BXO) => Promise<void> | void): this {
     this.hooks.onAfterRestart = handler;
     return this;
   }
 
-  onRequest(handler: (ctx: Context) => Promise<void> | void): this {
+  onRequest(handler: (ctx: Context, instance: BXO) => Promise<void> | void): this {
     this.hooks.onRequest = handler;
     return this;
   }
 
-  onResponse(handler: (ctx: Context, response: any) => Promise<any> | any): this {
+  onResponse(handler: (ctx: Context, response: any, instance: BXO) => Promise<any> | any): this {
     this.hooks.onResponse = handler;
     return this;
   }
 
-  onError(handler: (ctx: Context, error: Error) => Promise<any> | any): this {
+  onError(handler: (ctx: Context, error: Error, instance: BXO) => Promise<any> | any): this {
     this.hooks.onError = handler;
     return this;
   }
@@ -129,7 +162,7 @@ export default class BXO {
     handler: Handler<TConfig>,
     config?: TConfig
   ): this {
-    this.routes.push({ method: 'GET', path, handler, config });
+    this._routes.push({ method: 'GET', path, handler, config });
     return this;
   }
 
@@ -147,7 +180,7 @@ export default class BXO {
     handler: Handler<TConfig>,
     config?: TConfig
   ): this {
-    this.routes.push({ method: 'POST', path, handler, config });
+    this._routes.push({ method: 'POST', path, handler, config });
     return this;
   }
 
@@ -165,7 +198,7 @@ export default class BXO {
     handler: Handler<TConfig>,
     config?: TConfig
   ): this {
-    this.routes.push({ method: 'PUT', path, handler, config });
+    this._routes.push({ method: 'PUT', path, handler, config });
     return this;
   }
 
@@ -183,7 +216,7 @@ export default class BXO {
     handler: Handler<TConfig>,
     config?: TConfig
   ): this {
-    this.routes.push({ method: 'DELETE', path, handler, config });
+    this._routes.push({ method: 'DELETE', path, handler, config });
     return this;
   }
 
@@ -201,28 +234,118 @@ export default class BXO {
     handler: Handler<TConfig>,
     config?: TConfig
   ): this {
-    this.routes.push({ method: 'PATCH', path, handler, config });
+    this._routes.push({ method: 'PATCH', path, handler, config });
+    return this;
+  }
+
+  // WebSocket route handler
+  ws(path: string, handler: WebSocketHandler): this {
+    this._wsRoutes.push({ path, handler });
     return this;
   }
 
   // Route matching utility
   private matchRoute(method: string, pathname: string): { route: Route; params: Record<string, string> } | null {
-    for (const route of this.routes) {
+    for (const route of this._routes) {
       if (route.method !== method) continue;
 
       const routeSegments = route.path.split('/').filter(Boolean);
       const pathSegments = pathname.split('/').filter(Boolean);
 
-      if (routeSegments.length !== pathSegments.length) continue;
+      const params: Record<string, string> = {};
+      let isMatch = true;
+
+      // Handle wildcard at the end (catch-all)
+      const hasWildcardAtEnd = routeSegments.length > 0 && routeSegments[routeSegments.length - 1] === '*';
+      
+      if (hasWildcardAtEnd) {
+        // For catch-all wildcard, path must have at least as many segments as route (minus the wildcard)
+        if (pathSegments.length < routeSegments.length - 1) continue;
+      } else {
+        // For exact matching (with possible single-segment wildcards), lengths must match
+        if (routeSegments.length !== pathSegments.length) continue;
+      }
+
+      for (let i = 0; i < routeSegments.length; i++) {
+        const routeSegment = routeSegments[i];
+        const pathSegment = pathSegments[i];
+
+        if (!routeSegment) {
+          isMatch = false;
+          break;
+        }
+
+        // Handle catch-all wildcard at the end
+        if (routeSegment === '*' && i === routeSegments.length - 1) {
+          // Wildcard at end matches remaining path segments
+          const remainingPath = pathSegments.slice(i).join('/');
+          params['*'] = remainingPath;
+          break;
+        }
+
+        if (!pathSegment) {
+          isMatch = false;
+          break;
+        }
+
+        if (routeSegment.startsWith(':')) {
+          const paramName = routeSegment.slice(1);
+          params[paramName] = decodeURIComponent(pathSegment);
+        } else if (routeSegment === '*') {
+          // Single segment wildcard
+          params['*'] = decodeURIComponent(pathSegment);
+        } else if (routeSegment !== pathSegment) {
+          isMatch = false;
+          break;
+        }
+      }
+
+      if (isMatch) {
+        return { route, params };
+      }
+    }
+
+    return null;
+  }
+
+  // WebSocket route matching utility
+  private matchWSRoute(pathname: string): { route: WSRoute; params: Record<string, string> } | null {
+    for (const route of this._wsRoutes) {
+      const routeSegments = route.path.split('/').filter(Boolean);
+      const pathSegments = pathname.split('/').filter(Boolean);
 
       const params: Record<string, string> = {};
       let isMatch = true;
 
+      // Handle wildcard at the end (catch-all)
+      const hasWildcardAtEnd = routeSegments.length > 0 && routeSegments[routeSegments.length - 1] === '*';
+      
+      if (hasWildcardAtEnd) {
+        // For catch-all wildcard, path must have at least as many segments as route (minus the wildcard)
+        if (pathSegments.length < routeSegments.length - 1) continue;
+      } else {
+        // For exact matching (with possible single-segment wildcards), lengths must match
+        if (routeSegments.length !== pathSegments.length) continue;
+      }
+
       for (let i = 0; i < routeSegments.length; i++) {
         const routeSegment = routeSegments[i];
         const pathSegment = pathSegments[i];
 
-        if (!routeSegment || !pathSegment) {
+        if (!routeSegment) {
+          isMatch = false;
+          break;
+        }
+
+        // Handle catch-all wildcard at the end
+        if (routeSegment === '*' && i === routeSegments.length - 1) {
+          // Wildcard at end matches remaining path segments
+          const remainingPath = pathSegments.slice(i).join('/');
+          params['*'] = remainingPath;
+          break;
+        }
+
+        if (!pathSegment) {
           isMatch = false;
           break;
         }
@@ -230,6 +353,9 @@ export default class BXO {
         if (routeSegment.startsWith(':')) {
           const paramName = routeSegment.slice(1);
           params[paramName] = decodeURIComponent(pathSegment);
+        } else if (routeSegment === '*') {
+          // Single segment wildcard
+          params['*'] = decodeURIComponent(pathSegment);
         } else if (routeSegment !== pathSegment) {
           isMatch = false;
           break;
@@ -269,11 +395,30 @@ export default class BXO {
   }
 
   // Main request handler
-  private async handleRequest(request: Request): Promise<Response> {
+  private async handleRequest(request: Request, server?: any): Promise<Response | undefined> {
     const url = new URL(request.url);
     const method = request.method;
     const pathname = url.pathname;
 
+    // Check for WebSocket upgrade
+    if (request.headers.get('upgrade') === 'websocket') {
+      const wsMatchResult = this.matchWSRoute(pathname);
+      if (wsMatchResult && server) {
+        const success = server.upgrade(request, {
+          data: {
+            handler: wsMatchResult.route.handler,
+            params: wsMatchResult.params,
+            pathname
+          }
+        });
+
+        if (success) {
+          return; // undefined response means upgrade was successful
+        }
+      }
+      return new Response('WebSocket upgrade failed', { status: 400 });
+    }
+
     const matchResult = this.matchRoute(method, pathname);
     if (!matchResult) {
       return new Response('Not Found', { status: 404 });
@@ -306,6 +451,7 @@ export default class BXO {
       query: route.config?.query ? this.validateData(route.config.query, query) : query,
       body: route.config?.body ? this.validateData(route.config.body, body) : body,
       headers: route.config?.headers ? this.validateData(route.config.headers, headers) : headers,
+      path: pathname,
       request,
       set: {}
     };
@@ -313,13 +459,13 @@ export default class BXO {
     try {
       // Run global onRequest hook
       if (this.hooks.onRequest) {
-        await this.hooks.onRequest(ctx);
+        await this.hooks.onRequest(ctx, this);
       }
 
       // Run BXO instance onRequest hooks
       for (const bxoInstance of this.plugins) {
         if (bxoInstance.hooks.onRequest) {
-          await bxoInstance.hooks.onRequest(ctx);
+          await bxoInstance.hooks.onRequest(ctx, this);
         }
       }
 
@@ -328,13 +474,27 @@ export default class BXO {
 
       // Run global onResponse hook
       if (this.hooks.onResponse) {
-        response = await this.hooks.onResponse(ctx, response) || response;
+        response = await this.hooks.onResponse(ctx, response, this) || response;
       }
 
       // Run BXO instance onResponse hooks
       for (const bxoInstance of this.plugins) {
         if (bxoInstance.hooks.onResponse) {
-          response = await bxoInstance.hooks.onResponse(ctx, response) || response;
+          response = await bxoInstance.hooks.onResponse(ctx, response, this) || response;
+        }
+      }
+
+      // Validate response against schema if provided
+      if (route.config?.response && !(response instanceof Response)) {
+        try {
+          response = this.validateData(route.config.response, response);
+        } catch (validationError) {
+          // Response validation failed
+          const errorMessage = validationError instanceof Error ? validationError.message : 'Response validation failed';
+          return new Response(JSON.stringify({ error: `Response validation error: ${errorMessage}` }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' }
+          });
         }
       }
 
@@ -343,6 +503,35 @@ export default class BXO {
         return response;
       }
 
+      // Handle File response (like Elysia)
+      if (response instanceof File || (typeof Bun !== 'undefined' && response instanceof Bun.file('').constructor)) {
+        const file = response as File;
+        const responseInit: ResponseInit = {
+          status: ctx.set.status || 200,
+          headers: {
+            'Content-Type': file.type || 'application/octet-stream',
+            'Content-Length': file.size.toString(),
+            ...ctx.set.headers
+          }
+        };
+        return new Response(file, responseInit);
+      }
+
+      // Handle Bun.file() response
+      if (typeof response === 'object' && response && 'stream' in response && 'size' in response) {
+        const bunFile = response as any;
+        const responseInit: ResponseInit = {
+          status: ctx.set.status || 200,
+          headers: {
+            'Content-Type': bunFile.type || 'application/octet-stream',
+            'Content-Length': bunFile.size?.toString() || '',
+            ...ctx.set.headers,
+            ...(bunFile.headers || {}) // Support custom headers from file helper
+          }
+        };
+        return new Response(bunFile, responseInit);
+      }
+
       const responseInit: ResponseInit = {
         status: ctx.set.status || 200,
         headers: ctx.set.headers || {}
@@ -365,12 +554,12 @@ export default class BXO {
       let errorResponse: any;
 
       if (this.hooks.onError) {
-        errorResponse = await this.hooks.onError(ctx, error as Error);
+        errorResponse = await this.hooks.onError(ctx, error as Error, this);
       }
 
       for (const bxoInstance of this.plugins) {
         if (bxoInstance.hooks.onError) {
-          errorResponse = await bxoInstance.hooks.onError(ctx, error as Error) || errorResponse;
+          errorResponse = await bxoInstance.hooks.onError(ctx, error as Error, this) || errorResponse;
         }
       }
 
@@ -394,12 +583,49 @@ export default class BXO {
   }
 
   // Hot reload functionality
-  enableHotReload(watchPaths: string[] = ['./']): this {
+  enableHotReload(watchPaths: string[] = ['./'], excludePatterns: string[] = []): this {
     this.hotReloadEnabled = true;
     watchPaths.forEach(path => this.watchedFiles.add(path));
+    excludePatterns.forEach(pattern => this.watchedExclude.add(pattern));
     return this;
   }
 
+  private shouldExcludeFile(filename: string): boolean {
+    for (const pattern of this.watchedExclude) {
+      // Handle exact match
+      if (pattern === filename) {
+        return true;
+      }
+
+      // Handle directory patterns (e.g., "node_modules/", "dist/")
+      if (pattern.endsWith('/')) {
+        if (filename.startsWith(pattern) || filename.includes(`/${pattern}`)) {
+          return true;
+        }
+      }
+
+      // Handle wildcard patterns (e.g., "*.log", "temp*")
+      if (pattern.includes('*')) {
+        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+        if (regex.test(filename)) {
+          return true;
+        }
+      }
+
+      // Handle file extension patterns (e.g., ".log", ".tmp")
+      if (pattern.startsWith('.') && filename.endsWith(pattern)) {
+        return true;
+      }
+
+      // Handle substring matches for directories
+      if (filename.includes(pattern)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   private async setupFileWatcher(port: number, hostname: string): Promise<void> {
     if (!this.hotReloadEnabled) return;
 
@@ -409,11 +635,19 @@ export default class BXO {
       try {
         fs.watch(watchPath, { recursive: true }, async (eventType: string, filename: string) => {
           if (filename && (filename.endsWith('.ts') || filename.endsWith('.js'))) {
+            // Check if file should be excluded
+            if (this.shouldExcludeFile(filename)) {
+              return;
+            }
+
             console.log(`🔄 File changed: ${filename}, restarting server...`);
             await this.restart(port, hostname);
           }
         });
         console.log(`👀 Watching ${watchPath} for changes...`);
+        if (this.watchedExclude.size > 0) {
+          console.log(`🚫 Excluding patterns: ${Array.from(this.watchedExclude).join(', ')}`);
+        }
       } catch (error) {
         console.warn(`⚠️  Could not watch ${watchPath}:`, error);
       }
@@ -430,22 +664,44 @@ export default class BXO {
     try {
       // Before start hook
       if (this.hooks.onBeforeStart) {
-        await this.hooks.onBeforeStart();
+        await this.hooks.onBeforeStart(this);
       }
 
       this.server = Bun.serve({
         port,
         hostname,
-        fetch: (request) => this.handleRequest(request),
+        fetch: (request, server) => this.handleRequest(request, server),
+        websocket: {
+          message: (ws: any, message: any) => {
+            const handler = ws.data?.handler;
+            if (handler?.onMessage) {
+              handler.onMessage(ws, message);
+            }
+          },
+          open: (ws: any) => {
+            const handler = ws.data?.handler;
+            if (handler?.onOpen) {
+              handler.onOpen(ws);
+            }
+          },
+          close: (ws: any, code?: number, reason?: string) => {
+            const handler = ws.data?.handler;
+            if (handler?.onClose) {
+              handler.onClose(ws, code, reason);
+            }
+          }
+        }
       });
 
       this.isRunning = true;
+      this.serverPort = port;
+      this.serverHostname = hostname;
 
       console.log(`🦊 BXO server running at http://${hostname}:${port}`);
 
       // After start hook
       if (this.hooks.onAfterStart) {
-        await this.hooks.onAfterStart();
+        await this.hooks.onAfterStart(this);
       }
 
       // Setup hot reload
@@ -475,7 +731,7 @@ export default class BXO {
     try {
       // Before stop hook
       if (this.hooks.onBeforeStop) {
-        await this.hooks.onBeforeStop();
+        await this.hooks.onBeforeStop(this);
       }
 
       if (this.server) {
@@ -484,12 +740,14 @@ export default class BXO {
       }
 
       this.isRunning = false;
+      this.serverPort = undefined;
+      this.serverHostname = undefined;
 
       console.log('🛑 BXO server stopped');
 
       // After stop hook
       if (this.hooks.onAfterStop) {
-        await this.hooks.onAfterStop();
+        await this.hooks.onAfterStop(this);
       }
 
     } catch (error) {
@@ -502,7 +760,7 @@ export default class BXO {
     try {
       // Before restart hook
       if (this.hooks.onBeforeRestart) {
-        await this.hooks.onBeforeRestart();
+        await this.hooks.onBeforeRestart(this);
       }
 
       console.log('🔄 Restarting BXO server...');
@@ -516,7 +774,7 @@ export default class BXO {
 
       // After restart hook
       if (this.hooks.onAfterRestart) {
-        await this.hooks.onAfterRestart();
+        await this.hooks.onAfterRestart(this);
       }
 
     } catch (error) {
@@ -535,21 +793,93 @@ export default class BXO {
     return this.isRunning;
   }
 
-  getServerInfo(): { running: boolean; hotReload: boolean; watchedFiles: string[] } {
+  getServerInfo(): { running: boolean; hotReload: boolean; watchedFiles: string[]; excludePatterns: string[] } {
     return {
       running: this.isRunning,
       hotReload: this.hotReloadEnabled,
-      watchedFiles: Array.from(this.watchedFiles)
+      watchedFiles: Array.from(this.watchedFiles),
+      excludePatterns: Array.from(this.watchedExclude)
     };
   }
+
+  // Get server information (alias for getServerInfo)
+  get info() {
+    return {
+      // Server status
+      running: this.isRunning,
+      server: this.server ? 'Bun' : null,
+
+      // Connection details
+      hostname: this.serverHostname,
+      port: this.serverPort,
+      url: this.isRunning && this.serverHostname && this.serverPort
+        ? `http://${this.serverHostname}:${this.serverPort}`
+        : null,
+
+      // Application statistics
+      totalRoutes: this._routes.length,
+      totalWsRoutes: this._wsRoutes.length,
+      totalPlugins: this.plugins.length,
+
+      // Hot reload configuration
+      hotReload: this.hotReloadEnabled,
+      watchedFiles: Array.from(this.watchedFiles),
+      excludePatterns: Array.from(this.watchedExclude),
+
+      // System information
+      runtime: 'Bun',
+      version: typeof Bun !== 'undefined' ? Bun.version : 'unknown',
+      pid: process.pid,
+      uptime: this.isRunning ? process.uptime() : 0
+    };
+  }
+
+  // Get all routes information
+  get routes() {
+    return this._routes.map((route: Route) => ({
+      method: route.method,
+      path: route.path,
+      hasConfig: !!route.config,
+      config: route.config || null
+    }));
+  }
+
+  // Get all WebSocket routes information
+  get wsRoutes() {
+    return this._wsRoutes.map((route: WSRoute) => ({
+      path: route.path,
+      hasHandlers: {
+        onOpen: !!route.handler.onOpen,
+        onMessage: !!route.handler.onMessage,
+        onClose: !!route.handler.onClose,
+        onError: !!route.handler.onError
+      }
+    }));
+  }
+}
+
+const error = (error: Error | string, status: number = 500) => {
+  return new Response(JSON.stringify({ error: error instanceof Error ? error.message : error }), { status });
 }
 
-const error = (error: Error, status: number = 500) => {
-  return new Response(JSON.stringify({ error: error.message }), { status });
+// File helper function (like Elysia)
+const file = (path: string, options?: { type?: string; headers?: Record<string, string> }) => {
+  const bunFile = Bun.file(path);
+  
+  if (options?.type) {
+    // Create a wrapper to override the MIME type
+    return {
+      ...bunFile,
+      type: options.type,
+      headers: options.headers
+    };
+  }
+  
+  return bunFile;
 }
 
 // Export Zod for convenience
-export { z, error };
+export { z, error, file };
 
 // Export types for external use
-export type { RouteConfig };
+export type { RouteConfig, RouteDetail, Handler, WebSocketHandler, WSRoute };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bxo",
   "module": "index.ts",
-  "version": "0.0.4",
+  "version": "0.0.5-dev.10",
   "description": "A simple and lightweight web framework for Bun",
   "type": "module",
   "devDependencies": {