vector-framework 1.0.0 → 1.2.0

package/src/core/server.ts

@@ -1,71 +1,380 @@
-import type { Server } from "bun";
-import { cors } from "itty-router";
-import type {
-  CorsOptions,
-  DefaultVectorTypes,
-  VectorConfig,
-  VectorTypes,
-} from "../types";
-import type { VectorRouter } from "./router";
+import type { Server } from 'bun';
+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 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 { preflight, corsify } = cors(
-        this.normalizeCorsOptions(config.cors)
-      );
+      const opts = this.normalizeCorsOptions(config.cors);
+      const { preflight, corsify } = cors(opts);
       this.corsHandler = { preflight, corsify };
+
+      // 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,
+          'access-control-expose-headers': opts.exposeHeaders,
+          'access-control-max-age': String(opts.maxAge),
+        };
+        if (opts.credentials) {
+          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 {
     return {
-      origin: options.origin || "*",
+      origin: options.origin || '*',
       credentials: options.credentials !== false,
       allowHeaders: Array.isArray(options.allowHeaders)
-        ? options.allowHeaders.join(", ")
-        : options.allowHeaders || "Content-Type, Authorization",
+        ? options.allowHeaders.join(', ')
+        : options.allowHeaders || 'Content-Type, Authorization',
       allowMethods: Array.isArray(options.allowMethods)
-        ? options.allowMethods.join(", ")
-        : options.allowMethods || "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+        ? options.allowMethods.join(', ')
+        : options.allowMethods || 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
       exposeHeaders: Array.isArray(options.exposeHeaders)
-        ? options.exposeHeaders.join(", ")
-        : options.exposeHeaders || "Authorization",
+        ? options.exposeHeaders.join(', ')
+        : options.exposeHeaders || 'Authorization',
       maxAge: options.maxAge || 86400,
     };
   }
 
+  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 hostname = this.config.hostname || "localhost";
+    const port = this.config.port ?? 3000;
+    const hostname = this.config.hostname || 'localhost';
+
+    this.validateReservedOpenAPIPaths();
 
-    const fetch = async (request: Request): Promise<Response> => {
+    const fallbackFetch = async (request: Request): Promise<Response> => {
       try {
-        // Handle CORS preflight
-        if (this.corsHandler && request.method === "OPTIONS") {
+        // 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.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 });
+        console.error('Server error:', error);
+        return this.applyCors(new Response('Internal Server Error', { status: 500 }), request);
       }
     };
 
@@ -74,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) => {
-          console.error("[ERROR] Server error:", error);
-          return new Response("Internal Server Error", { status: 500 });
+        error: (error, request?: Request) => {
+          console.error('[ERROR] Server error:', error);
+          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;
@@ -111,7 +417,10 @@ export class VectorServer<TTypes extends VectorTypes = DefaultVectorTypes> {
     if (this.server) {
       this.server.stop();
       this.server = null;
-      console.log("Server stopped");
+      this.openapiDocCache = null;
+      this.openapiDocsHtmlCache = null;
+      this.openapiWarningsLogged = false;
+      console.log('Server stopped');
     }
   }
 
@@ -120,11 +429,11 @@ 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 {
-    return this.server?.hostname || this.config.hostname || "localhost";
+    return this.server?.hostname || this.config.hostname || 'localhost';
   }
 
   getUrl(): string {

package/src/core/vector.ts

@@ -1,22 +1,30 @@
-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";
-import { RouteScanner } from "../dev/route-scanner";
-import { MiddlewareManager } from "../middleware/manager";
-import { toFileUrl } from "../utils/path";
+import type { Server } from 'bun';
+import { AuthManager } from '../auth/protected';
+import { CacheManager } from '../cache/manager';
+import { RouteGenerator } from '../dev/route-generator';
+import { RouteScanner } from '../dev/route-scanner';
+import { MiddlewareManager } from '../middleware/manager';
+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";
+} 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> {
@@ -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,16 +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();
@@ -110,7 +118,7 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
   }
 
   private async discoverRoutes() {
-    const routesDir = this.config.routesDir || "./routes";
+    const routesDir = this.config.routesDir || './routes';
     const excludePatterns = this.config.routeExcludePatterns;
 
     // Always create a new RouteScanner with the current config's routesDir
@@ -134,78 +142,80 @@ export class Vector<TTypes extends VectorTypes = DefaultVectorTypes> {
             const importPath = toFileUrl(route.path);
 
             const module = await import(importPath);
-            const exported =
-              route.name === "default" ? module.default : module[route.name];
+            const exported = route.name === 'default' ? module.default : module[route.name];
 
             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);
-              } else if (typeof exported === "function") {
-                this.router.route(route.options as any, exported);
-                this.logRouteLoaded(route.options);
+                this.router.addRoute(exported);
+                this.logRouteLoaded(exported);
+              } else if (typeof exported === 'function') {
+                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
-            );
+            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"
-      ) {
-        console.error("Failed to discover routes:", error);
+      if ((error as any).code !== 'ENOENT' && (error as any).code !== 'ENOTDIR') {
+        console.error('Failed to discover routes:', error);
       }
     }
   }
 
   async loadRoute(routeModule: any) {
-    if (typeof routeModule === "function") {
+    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") {
+    } 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);
+        if (typeof value === 'function') {
+          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 &&
-      typeof value === "object" &&
-      "entry" in value &&
-      "options" in value &&
-      "handler" in value
+      value !== null &&
+      typeof value === 'object' &&
+      'entry' in value &&
+      'options' 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
   }