vector-framework 1.1.1 → 1.2.0

package/src/core/server.ts

@@ -1,28 +1,107 @@
 import type { Server } from 'bun';
-import { cors } from 'itty-router';
-import type { CorsOptions, DefaultVectorTypes, VectorConfig, VectorTypes } from '../types';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATIC_RESPONSES } from '../constants';
+import { cors } from '../utils/cors';
+import { renderOpenAPIDocsHtml } from '../openapi/docs-ui';
+import { generateOpenAPIDocument } from '../openapi/generator';
+import type { CorsOptions, DefaultVectorTypes, OpenAPIOptions, VectorConfig, VectorTypes } from '../types';
 import type { VectorRouter } from './router';
 
+interface NormalizedOpenAPIConfig {
+  enabled: boolean;
+  path: string;
+  target: string;
+  docs: {
+    enabled: boolean;
+    path: string;
+  };
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+  };
+}
+
+const OPENAPI_TAILWIND_ASSET_PATH = '/_vector/openapi/tailwindcdn.js';
+const OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES = [
+  // Source execution (src/core/server.ts -> src/openapi/assets/tailwindcdn.js)
+  '../openapi/assets/tailwindcdn.js',
+  // Bundled dist entrypoints (dist/index.mjs|dist/cli.js -> src/openapi/assets/tailwindcdn.js)
+  '../src/openapi/assets/tailwindcdn.js',
+  // Unbundled dist/core/server.js execution (dist/core -> src/openapi/assets/tailwindcdn.js)
+  '../../src/openapi/assets/tailwindcdn.js',
+] as const;
+const OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES = [
+  'src/openapi/assets/tailwindcdn.js',
+  'openapi/assets/tailwindcdn.js',
+  'dist/openapi/assets/tailwindcdn.js',
+] as const;
+const OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK = '/* OpenAPI docs runtime asset missing: tailwind disabled */';
+
+function resolveOpenAPITailwindAssetFile(): ReturnType<typeof Bun.file> | null {
+  for (const relativePath of OPENAPI_TAILWIND_ASSET_RELATIVE_CANDIDATES) {
+    try {
+      const fileUrl = new URL(relativePath, import.meta.url);
+      if (existsSync(fileUrl)) {
+        return Bun.file(fileUrl);
+      }
+    } catch {
+      // Ignore resolution failures and try the next candidate.
+    }
+  }
+
+  const cwd = process.cwd();
+  for (const relativePath of OPENAPI_TAILWIND_ASSET_CWD_CANDIDATES) {
+    const absolutePath = join(cwd, relativePath);
+    if (existsSync(absolutePath)) {
+      return Bun.file(absolutePath);
+    }
+  }
+
+  return null;
+}
+
+const OPENAPI_TAILWIND_ASSET_FILE = resolveOpenAPITailwindAssetFile();
+const DOCS_HTML_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
+const DOCS_ASSET_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+
+interface OpenAPIDocsHtmlCacheEntry {
+  html: string;
+  gzip: Uint8Array;
+  etag: string;
+}
+
 export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
   private server: Server | null = null;
   private router: VectorRouter<TTypes>;
   private config: VectorConfig<TTypes>;
-  private corsHandler: any;
-  private corsHeaders: Record<string, string> | null = null;
+  private openapiConfig: NormalizedOpenAPIConfig;
+  private openapiDocCache: Record<string, unknown> | null = null;
+  private openapiDocsHtmlCache: OpenAPIDocsHtmlCacheEntry | null = null;
+  private openapiWarningsLogged = false;
+  private openapiTailwindMissingLogged = false;
+  private corsHandler: {
+    preflight: (request: Request) => Response;
+    corsify: (response: Response, request: Request) => Response;
+  } | null = null;
+  private corsHeadersEntries: [string, string][] | null = null;
 
   constructor(router: VectorRouter<TTypes>, config: VectorConfig<TTypes>) {
     this.router = router;
     this.config = config;
+    this.openapiConfig = this.normalizeOpenAPIConfig(config.openapi, config.development);
 
     if (config.cors) {
       const opts = this.normalizeCorsOptions(config.cors);
       const { preflight, corsify } = cors(opts);
       this.corsHandler = { preflight, corsify };
 
-      // Pre-build static CORS headers when origin is a fixed string.
-      // Avoids cloning the Response on every request via corsify().
-      if (typeof opts.origin === 'string') {
-        this.corsHeaders = {
+      // Pre-build static CORS headers when origin does not require per-request reflection.
+      const canUseStaticCorsHeaders = typeof opts.origin === 'string' && (opts.origin !== '*' || !opts.credentials);
+
+      if (canUseStaticCorsHeaders) {
+        const corsHeaders: Record<string, string> = {
           'access-control-allow-origin': opts.origin,
           'access-control-allow-methods': opts.allowMethods,
           'access-control-allow-headers': opts.allowHeaders,
@@ -30,10 +109,214 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
           'access-control-max-age': String(opts.maxAge),
         };
         if (opts.credentials) {
-          this.corsHeaders['access-control-allow-credentials'] = 'true';
+          corsHeaders['access-control-allow-credentials'] = 'true';
+        }
+        this.corsHeadersEntries = Object.entries(corsHeaders);
+      }
+
+      // Pass CORS behavior to router so matched routes also receive CORS headers.
+      this.router.setCorsHeaders(this.corsHeadersEntries);
+      this.router.setCorsHandler(this.corsHeadersEntries ? null : this.corsHandler.corsify);
+    }
+  }
+
+  private normalizeOpenAPIConfig(
+    openapi: OpenAPIOptions | boolean | undefined,
+    development: boolean | undefined
+  ): NormalizedOpenAPIConfig {
+    const isDev = development !== false && process.env.NODE_ENV !== 'production';
+    const defaultEnabled = isDev;
+
+    if (openapi === false) {
+      return {
+        enabled: false,
+        path: '/openapi.json',
+        target: 'openapi-3.0',
+        docs: { enabled: false, path: '/docs' },
+      };
+    }
+
+    if (openapi === true) {
+      return {
+        enabled: true,
+        path: '/openapi.json',
+        target: 'openapi-3.0',
+        docs: { enabled: false, path: '/docs' },
+      };
+    }
+
+    const openapiObject = openapi || {};
+    const docsValue = openapiObject.docs;
+    const docs =
+      typeof docsValue === 'boolean'
+        ? { enabled: docsValue, path: '/docs' }
+        : {
+            enabled: docsValue?.enabled === true,
+            path: docsValue?.path || '/docs',
+          };
+
+    return {
+      enabled: openapiObject.enabled ?? defaultEnabled,
+      path: openapiObject.path || '/openapi.json',
+      target: openapiObject.target || 'openapi-3.0',
+      docs,
+      info: openapiObject.info,
+    };
+  }
+
+  private isDocsReservedPath(path: string): boolean {
+    return (
+      path === this.openapiConfig.path || (this.openapiConfig.docs.enabled && path === this.openapiConfig.docs.path)
+    );
+  }
+
+  private getOpenAPIDocument(): Record<string, unknown> {
+    if (this.openapiDocCache) {
+      return this.openapiDocCache;
+    }
+
+    const routes = this.router.getRouteDefinitions().filter((route) => !this.isDocsReservedPath(route.path));
+
+    const result = generateOpenAPIDocument(routes as any, {
+      target: this.openapiConfig.target,
+      info: this.openapiConfig.info,
+    });
+
+    if (!this.openapiWarningsLogged && result.warnings.length > 0) {
+      for (const warning of result.warnings) {
+        console.warn(warning);
+      }
+      this.openapiWarningsLogged = true;
+    }
+
+    this.openapiDocCache = result.document;
+    return this.openapiDocCache;
+  }
+
+  private getOpenAPIDocsHtmlCacheEntry(): OpenAPIDocsHtmlCacheEntry {
+    if (this.openapiDocsHtmlCache) {
+      return this.openapiDocsHtmlCache;
+    }
+
+    const html = renderOpenAPIDocsHtml(this.getOpenAPIDocument(), this.openapiConfig.path, OPENAPI_TAILWIND_ASSET_PATH);
+    const gzip = Bun.gzipSync(html);
+    const etag = `"${Bun.hash(html).toString(16)}"`;
+
+    this.openapiDocsHtmlCache = { html, gzip, etag };
+    return this.openapiDocsHtmlCache;
+  }
+
+  private requestAcceptsGzip(request: Request): boolean {
+    const acceptEncoding = request.headers.get('accept-encoding');
+    return Boolean(acceptEncoding && /\bgzip\b/i.test(acceptEncoding));
+  }
+
+  private validateReservedOpenAPIPaths(): void {
+    if (!this.openapiConfig.enabled) {
+      return;
+    }
+
+    const reserved = new Set<string>([this.openapiConfig.path]);
+    if (this.openapiConfig.docs.enabled) {
+      reserved.add(this.openapiConfig.docs.path);
+      reserved.add(OPENAPI_TAILWIND_ASSET_PATH);
+    }
+
+    const methodConflicts = this.router
+      .getRouteDefinitions()
+      .filter((route) => reserved.has(route.path))
+      .map((route) => `${route.method} ${route.path}`);
+
+    const staticConflicts = Object.entries(this.router.getRouteTable())
+      .filter(([path, value]) => reserved.has(path) && value instanceof Response)
+      .map(([path]) => `STATIC ${path}`);
+
+    const conflicts = [...methodConflicts, ...staticConflicts];
+
+    if (conflicts.length > 0) {
+      throw new Error(
+        `OpenAPI reserved path conflict: ${conflicts.join(
+          ', '
+        )}. Change your route path(s) or reconfigure openapi.path/docs.path.`
+      );
+    }
+  }
+
+  private tryHandleOpenAPIRequest(request: Request): Response | null {
+    if (!this.openapiConfig.enabled || request.method !== 'GET') {
+      return null;
+    }
+
+    const pathname = new URL(request.url).pathname;
+    if (pathname === this.openapiConfig.path) {
+      return Response.json(this.getOpenAPIDocument());
+    }
+
+    if (this.openapiConfig.docs.enabled && pathname === this.openapiConfig.docs.path) {
+      const { html, gzip, etag } = this.getOpenAPIDocsHtmlCacheEntry();
+      if (request.headers.get('if-none-match') === etag) {
+        return new Response(null, {
+          status: 304,
+          headers: {
+            etag,
+            'cache-control': DOCS_HTML_CACHE_CONTROL,
+            vary: 'accept-encoding',
+          },
+        });
+      }
+
+      if (this.requestAcceptsGzip(request)) {
+        return new Response(gzip, {
+          status: 200,
+          headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'content-encoding': 'gzip',
+            etag,
+            'cache-control': DOCS_HTML_CACHE_CONTROL,
+            vary: 'accept-encoding',
+          },
+        });
+      }
+
+      return new Response(html, {
+        status: 200,
+        headers: {
+          'content-type': 'text/html; charset=utf-8',
+          etag,
+          'cache-control': DOCS_HTML_CACHE_CONTROL,
+          vary: 'accept-encoding',
+        },
+      });
+    }
+
+    if (this.openapiConfig.docs.enabled && pathname === OPENAPI_TAILWIND_ASSET_PATH) {
+      if (!OPENAPI_TAILWIND_ASSET_FILE) {
+        if (!this.openapiTailwindMissingLogged) {
+          this.openapiTailwindMissingLogged = true;
+          console.warn(
+            '[OpenAPI] Missing docs runtime asset "tailwindcdn.js". Serving inline fallback script instead.'
+          );
         }
+
+        return new Response(OPENAPI_TAILWIND_ASSET_INLINE_FALLBACK, {
+          status: 200,
+          headers: {
+            'content-type': 'application/javascript; charset=utf-8',
+            'cache-control': DOCS_ASSET_CACHE_CONTROL,
+          },
+        });
       }
+
+      return new Response(OPENAPI_TAILWIND_ASSET_FILE, {
+        status: 200,
+        headers: {
+          'content-type': 'application/javascript; charset=utf-8',
+          'cache-control': DOCS_ASSET_CACHE_CONTROL,
+        },
+      });
     }
+
+    return null;
   }
 
   private normalizeCorsOptions(options: CorsOptions): any {
@@ -53,33 +336,45 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
     };
   }
 
+  private applyCors(response: Response, request?: Request): Response {
+    if (this.corsHeadersEntries) {
+      for (const [k, v] of this.corsHeadersEntries) {
+        response.headers.set(k, v);
+      }
+      return response;
+    }
+
+    if (this.corsHandler && request) {
+      return this.corsHandler.corsify(response, request);
+    }
+
+    return response;
+  }
+
   async start(): Promise<Server> {
-    const port = this.config.port || 3000;
+    const port = this.config.port ?? 3000;
     const hostname = this.config.hostname || 'localhost';
 
-    const fetch = async (request: Request): Promise<Response> => {
+    this.validateReservedOpenAPIPaths();
+
+    const fallbackFetch = async (request: Request): Promise<Response> => {
       try {
-        // Handle CORS preflight
+        // Handle CORS preflight for any path
         if (this.corsHandler && request.method === 'OPTIONS') {
           return this.corsHandler.preflight(request);
         }
 
-        // Try to handle the request with our router
-        let response = await this.router.handle(request);
-
-        // Apply CORS headers if configured
-        if (this.corsHeaders) {
-          for (const [k, v] of Object.entries(this.corsHeaders)) {
-            response.headers.set(k, v);
-          }
-        } else if (this.corsHandler) {
-          response = this.corsHandler.corsify(response, request);
+        // Handle built-in docs endpoints for requests that fell through the Bun route table.
+        const openapiResponse = this.tryHandleOpenAPIRequest(request);
+        if (openapiResponse) {
+          return this.applyCors(openapiResponse, request);
         }
 
-        return response;
+        // No route matched — return 404
+        return this.applyCors(STATIC_RESPONSES.NOT_FOUND.clone() as unknown as Response, request);
       } catch (error) {
         console.error('Server error:', error);
-        return new Response('Internal Server Error', { status: 500 });
+        return this.applyCors(new Response('Internal Server Error', { status: 500 }), request);
       }
     };
 
@@ -88,24 +383,21 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
         port,
         hostname,
         reusePort: this.config.reusePort !== false,
-        fetch,
+        routes: this.router.getRouteTable(),
+        fetch: fallbackFetch,
         idleTimeout: this.config.idleTimeout || 60,
-        error: (error) => {
+        error: (error, request?: Request) => {
           console.error('[ERROR] Server error:', error);
-          return new Response('Internal Server Error', { status: 500 });
+          return this.applyCors(new Response('Internal Server Error', { status: 500 }), request);
         },
       });
 
-      // Validate that the server actually started
       if (!this.server || !this.server.port) {
         throw new Error(`Failed to start server on ${hostname}:${port} - server object is invalid`);
       }
 
-      // Server logs are handled by CLI
-
       return this.server;
     } catch (error: any) {
-      // Enhance error message with context for common issues
       if (error.code === 'EADDRINUSE' || error.message?.includes('address already in use')) {
         error.message = `Port ${port} is already in use`;
         error.port = port;
@@ -125,6 +417,9 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
     if (this.server) {
       this.server.stop();
       this.server = null;
+      this.openapiDocCache = null;
+      this.openapiDocsHtmlCache = null;
+      this.openapiWarningsLogged = false;
       console.log('Server stopped');
     }
   }
@@ -134,7 +429,7 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
   }
 
   getPort(): number {
-    return this.server?.port || this.config.port || 3000;
+    return this.server?.port ?? this.config.port ?? 3000;
   }
 
   getHostname(): string {

package/src/core/vector.ts

@@ -1,5 +1,4 @@
 import type { Server } from 'bun';
-import type { RouteEntry } from 'itty-router';
 import { AuthManager } from '../auth/protected';
 import { CacheManager } from '../cache/manager';
 import { RouteGenerator } from '../dev/route-generator';
@@ -9,15 +8,24 @@ import { toFileUrl } from '../utils/path';
 import type {
   CacheHandler,
   DefaultVectorTypes,
+  InferRouteInputFromSchemaDefinition,
+  LegacyRouteEntry,
   ProtectedHandler,
   RouteHandler,
   RouteOptions,
+  RouteSchemaDefinition,
   VectorConfig,
   VectorTypes,
 } from '../types';
 import { VectorRouter } from './router';
 import { VectorServer } from './server';
 
+interface LoadedRouteDefinition<TTypes extends VectorTypes = DefaultVectorTypes> {
+  entry: { method: string; path: string };
+  options: RouteOptions<TTypes>;
+  handler: RouteHandler<TTypes>;
+}
+
 // Internal-only class - not exposed to users
 export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
   private static instance: Vector<any>;
@@ -36,11 +44,7 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
     this.middlewareManager = new MiddlewareManager<TTypes>();
     this.authManager = new AuthManager<TTypes>();
     this.cacheManager = new CacheManager<TTypes>();
-    this.router = new VectorRouter<TTypes>(
-      this.middlewareManager,
-      this.authManager,
-      this.cacheManager
-    );
+    this.router = new VectorRouter<TTypes>(this.middlewareManager, this.authManager, this.cacheManager);
   }
 
   // Internal use only - not exposed to users
@@ -72,13 +76,20 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
   }
 
   // Internal method to add route
-  addRoute(options: RouteOptions<TTypes>, handler: RouteHandler<TTypes>): RouteEntry {
-    return this.router.route(options, handler);
+  addRoute<TSchemaDef extends RouteSchemaDefinition | undefined>(
+    options: Omit<RouteOptions<TTypes>, 'schema'> & { schema?: TSchemaDef },
+    handler: RouteHandler<TTypes, InferRouteInputFromSchemaDefinition<TSchemaDef>>
+  ): void;
+  addRoute(options: RouteOptions<TTypes>, handler: RouteHandler<TTypes>): void {
+    this.router.route(options, handler);
   }
 
   // Internal method to start server - only called by CLI
   async startServer(config?: VectorConfig<TTypes>): Promise<Server> {
     this.config = { ...this.config, ...config };
+    const routeDefaults = { ...this.config.defaults?.route };
+    this.router.setRouteBooleanDefaults(routeDefaults);
+    this.router.setDevelopmentMode(this.config.development);
 
     // Clear previous middleware to avoid accumulation across multiple starts
     this.middlewareManager.clear();
@@ -136,25 +147,21 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
             if (exported) {
               if (this.isRouteDefinition(exported)) {
                 // Use router.route() to ensure middleware is applied
-                const routeDef = exported as any;
-                this.router.route(routeDef.options, routeDef.handler);
-                this.logRouteLoaded(routeDef.options);
+                this.router.route(exported.options, exported.handler);
+                this.logRouteLoaded(exported.options);
               } else if (this.isRouteEntry(exported)) {
                 // Legacy support for direct RouteEntry (won't have middleware)
-                this.router.addRoute(exported as RouteEntry);
-                this.logRouteLoaded(exported as RouteEntry);
+                this.router.addRoute(exported);
+                this.logRouteLoaded(exported);
               } else if (typeof exported === 'function') {
-                this.router.route(route.options as any, exported);
-                this.logRouteLoaded(route.options);
+                this.router.route(route.options as RouteOptions<TTypes>, exported as RouteHandler<TTypes>);
+                this.logRouteLoaded(route.options as RouteOptions<TTypes>);
               }
             }
           } catch (error) {
             console.error(`Failed to load route ${route.name} from ${route.path}:`, error);
           }
         }
-
-        // Ensure routes are properly sorted after loading all
-        this.router.sortRoutes();
       }
     } catch (error) {
       if ((error as any).code !== 'ENOENT' && (error as any).code !== 'ENOTDIR') {
@@ -166,36 +173,49 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
   async loadRoute(routeModule: any) {
     if (typeof routeModule === 'function') {
       const routeEntry = routeModule();
-      if (Array.isArray(routeEntry)) {
-        this.router.addRoute(routeEntry as RouteEntry);
+      if (this.isRouteEntry(routeEntry)) {
+        this.router.addRoute(routeEntry);
       }
     } else if (routeModule && typeof routeModule === 'object') {
       for (const [, value] of Object.entries(routeModule)) {
         if (typeof value === 'function') {
-          const routeEntry = (value as any)();
-          if (Array.isArray(routeEntry)) {
-            this.router.addRoute(routeEntry as RouteEntry);
+          const routeEntry = value();
+          if (this.isRouteEntry(routeEntry)) {
+            this.router.addRoute(routeEntry);
           }
         }
       }
     }
   }
 
-  private isRouteEntry(value: any): boolean {
-    return Array.isArray(value) && value.length >= 3;
+  private isRouteEntry(value: unknown): value is LegacyRouteEntry {
+    if (!Array.isArray(value) || value.length < 3) {
+      return false;
+    }
+
+    const [method, matcher, handlers, path] = value;
+    return (
+      typeof method === 'string' &&
+      matcher instanceof RegExp &&
+      Array.isArray(handlers) &&
+      handlers.length > 0 &&
+      handlers.every((handler) => typeof handler === 'function') &&
+      (path === undefined || typeof path === 'string')
+    );
   }
 
-  private isRouteDefinition(value: any): boolean {
+  private isRouteDefinition(value: unknown): value is LoadedRouteDefinition<TTypes> {
     return (
-      value &&
+      value !== null &&
       typeof value === 'object' &&
       'entry' in value &&
       'options' in value &&
-      'handler' in value
+      'handler' in value &&
+      typeof (value as LoadedRouteDefinition<TTypes>).handler === 'function'
     );
   }
 
-  private logRouteLoaded(_: RouteEntry | RouteOptions): void {
+  private logRouteLoaded(_: RouteOptions<TTypes> | LegacyRouteEntry): void {
     // Silent - no logging
   }
 

package/src/dev/route-generator.ts

@@ -36,9 +36,7 @@ export class RouteGenerator {
 
       if (fileRoutes.some((r) => r.name === 'default')) {
         if (namedImports.length > 0) {
-          imports.push(
-            `import ${importName}, { ${namedImports.join(', ')} } from '${relativePath}';`
-          );
+          imports.push(`import ${importName}, { ${namedImports.join(', ')} } from '${relativePath}';`);
         } else {
           imports.push(`import ${importName} from '${relativePath}';`);
         }

package/src/dev/route-scanner.ts

@@ -95,8 +95,7 @@ export class RouteScanner {
 
         try {
           // Convert Windows paths to URLs for import
-          const importPath =
-            process.platform === 'win32' ? `file:///${fullPath.replace(/\\/g, '/')}` : fullPath;
+          const importPath = process.platform === 'win32' ? `file:///${fullPath.replace(/\\/g, '/')}` : fullPath;
 
           const module = await import(importPath);
 
@@ -117,13 +116,7 @@ export class RouteScanner {
             if (name === 'default') continue;
 
             // Check for new RouteDefinition format
-            if (
-              value &&
-              typeof value === 'object' &&
-              'entry' in value &&
-              'options' in value &&
-              'handler' in value
-            ) {
+            if (value && typeof value === 'object' && 'entry' in value && 'options' in value && 'handler' in value) {
               const routeDef = value as any;
               routes.push({
                 name,