@gravito/core 1.6.0 → 2.0.0

package/dist/Router.d.ts

@@ -0,0 +1,270 @@
+import type { GravitoHandler, GravitoMiddleware, HttpMethod, ProxyOptions } from './http/types';
+import type { PlanetCore } from './PlanetCore';
+import { Route } from './Route';
+/**
+ * Type for Controller Class Constructor
+ * @public
+ */
+export type ControllerClass = new (core: PlanetCore) => any;
+/**
+ * Handler can be a function or [Class, 'methodName']
+ * @public
+ */
+export type RouteHandler = GravitoHandler | [ControllerClass, string];
+/**
+ * Interface for FormRequest classes (from @gravito/impulse).
+ * Used for duck-typing detection without hard dependency.
+ */
+export interface FormRequestLike {
+    schema: unknown;
+    source?: string;
+    /**
+     * Validate the request context.
+     * @param ctx - The request context
+     */
+    validate?(ctx: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    }>;
+}
+/**
+ * Type for FormRequest class constructor
+ * @public
+ */
+export type FormRequestClass = new () => FormRequestLike;
+/**
+ * Symbol to mark FormRequest classes for fast identification.
+ * FormRequest classes from @gravito/impulse should set this symbol.
+ */
+/**
+ * Symbol to mark FormRequest classes for fast identification.
+ * FormRequest classes from @gravito/impulse should set this symbol.
+ * @public
+ */
+export declare const FORM_REQUEST_SYMBOL: unique symbol;
+/**
+ * Options for route definitions
+ * @public
+ */
+export interface RouteOptions {
+    /** Route prefix path */
+    prefix?: string;
+    /** Domain/Hostname constraint */
+    domain?: string;
+    /** Middleware stack for the route */
+    middleware?: GravitoMiddleware[];
+}
+/**
+ * Common routing handler argument definition
+ * @public
+ */
+export type RouteDefinitionArg = FormRequestClass | RouteHandler | GravitoMiddleware | GravitoMiddleware[];
+/**
+ * Interface merging for HTTP routing methods to establish overloads
+ * without duplicate bodies.
+ * @public
+ */
+export interface RoutingMethods {
+    get(path: string, handler: RouteHandler): Route;
+    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    post(path: string, handler: RouteHandler): Route;
+    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    put(path: string, handler: RouteHandler): Route;
+    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    delete(path: string, handler: RouteHandler): Route;
+    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    patch(path: string, handler: RouteHandler): Route;
+    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+}
+/**
+ * RouteGroup
+ * Helper class for chained route configuration (prefix, domain, etc.)
+ */
+/**
+ * RouteGroup
+ * Helper class for chained route configuration (prefix, domain, etc.)
+ * @public
+ */
+export interface RouteGroup extends RoutingMethods {
+}
+export declare class RouteGroup {
+    private router;
+    private options;
+    constructor(router: Router, options: RouteOptions);
+    /**
+     * Add a prefix to the current group
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Add middleware to the current group.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Define routes within this group
+     */
+    group(callback: (router: Router | RouteGroup) => void): void;
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    /**
+     * Register a route that forwards requests to another URL (Gateway Proxy).
+     * @param method - HTTP method or 'all'
+     * @param path - Local route path
+     * @param target - Remote URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(method: HttpMethod | HttpMethod[] | 'all', path: string, target: string, options?: ProxyOptions): void;
+}
+/**
+ * Gravito Router
+ *
+ * Provides a Laravel-like fluent API for defining routes.
+ * Supports:
+ * - Controller-based routing: router.get('/', [HomeController, 'index'])
+ * - Route groups with prefixes: router.prefix('/api').group(...)
+ * - Domain-based routing: router.domain('api.app').group(...)
+ * - Middleware chaining: router.middleware(auth).group(...)
+ * - FormRequest validation: router.post('/users', StoreUserRequest, [UserController, 'store'])
+ * - Inline Middleware: router.get('/users', authMiddleware, [UserController, 'index'])
+ */
+export interface Router extends RoutingMethods {
+}
+export declare class Router {
+    private core;
+    routes: Array<{
+        method: string;
+        path: string;
+        domain?: string;
+    }>;
+    private dispatcher;
+    private namedRoutes;
+    private bindings;
+    /**
+     * Compile all registered routes into a flat array for caching or manifest generation.
+     * Optimized: O(n) complexity using Set for lookups instead of O(n²) with Array.some()
+     */
+    compile(): {
+        method: string;
+        path: string;
+        name?: string;
+        domain?: string | undefined;
+    }[];
+    /**
+     * Register a named route
+     */
+    registerName(name: string, method: string, path: string, options?: RouteOptions): void;
+    /**
+     * Generate a URL from a named route.
+     *
+     * Replaces route parameters (e.g., `:id`) with provided values and appends
+     * query parameters to the URL.
+     *
+     * @param name - The name of the route.
+     * @param params - Key-value pairs for route parameters.
+     * @param query - Key-value pairs for query string parameters.
+     * @returns The generated URL string.
+     * @throws Error if the named route is not found or if a required parameter is missing.
+     *
+     * @example
+     * ```typescript
+     * const url = router.url('users.show', { id: 1 }, { tab: 'profile' });
+     * // Result: "/users/1?tab=profile"
+     * ```
+     */
+    url(name: string, params?: Record<string, string | number>, query?: Record<string, string | number | boolean | null | undefined>): string;
+    /**
+     * Export named routes as a serializable manifest (for caching).
+     */
+    exportNamedRoutes(): Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>;
+    /**
+     * Load named routes from a manifest (for caching).
+     */
+    loadNamedRoutes(manifest: Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>): void;
+    /**
+     * Register a route model binding.
+     *
+     * Automatically resolves a route parameter to an object using the provided
+     * resolver function. The resolved object is then available in the request context.
+     *
+     * @param param - The name of the route parameter to bind.
+     * @param resolver - An async function that resolves the parameter value to an object.
+     *
+     * @example
+     * ```typescript
+     * router.bind('user', async (id) => await User.find(id));
+     * ```
+     */
+    bind(param: string, resolver: (id: string) => Promise<unknown>): void;
+    /**
+     * Register a route model binding for a Model class.
+     */
+    model(param: string, modelClass: unknown): void;
+    constructor(core: PlanetCore);
+    /**
+     * Start a route group with a prefix
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Start a route group with a domain constraint
+     */
+    domain(host: string): RouteGroup;
+    /**
+     * Start a route group with middleware.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Register a route that forwards requests to another URL (Gateway Proxy).
+     * @param method - HTTP method or 'all'
+     * @param path - Local route path
+     * @param target - Remote URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(method: HttpMethod | HttpMethod[] | 'all', path: string, target: string, options?: ProxyOptions): void;
+    /**
+     * Register a resource route (RESTful).
+     *
+     * Automatically creates multiple routes for a resource (index, create, store,
+     * show, edit, update, destroy) mapping to specific controller methods.
+     *
+     * @param name - The resource name (e.g., 'users').
+     * @param controller - The controller class handling the resource.
+     * @param options - Optional constraints (only/except) for resource actions.
+     *
+     * @example
+     * ```typescript
+     * router.resource('photos', PhotoController);
+     * ```
+     */
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    /**
+     * Internal Request Registration
+     */
+    req(method: HttpMethod, path: string, requestOrHandlerOrMiddleware: RouteDefinitionArg, handler?: RouteHandler, options?: RouteOptions): Route;
+}
+/**
+ * Standard RESTful resource action names.
+ * @public
+ */
+export type ResourceAction = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+/**
+ * Options for resource route registration.
+ * @public
+ */
+export interface ResourceOptions {
+    only?: ResourceAction[];
+    except?: ResourceAction[];
+}

package/dist/ServiceProvider.d.ts

@@ -0,0 +1,178 @@
+import type { ConfigManager } from './ConfigManager';
+import type { Container } from './Container';
+import type { PlanetCore } from './PlanetCore';
+/**
+ * ServiceProvider - The foundation for modular service registration.
+ *
+ * Service providers are the central place to configure your application.
+ * They bind services to the container and bootstrap application features.
+ *
+ * Lifecycle:
+ * 1. register() - Called during registration phase (sync or async)
+ * 2. boot() - Called after ALL providers have registered
+ *
+ * @since 1.0.0
+ * @example
+ * ```typescript
+ * class DatabaseServiceProvider extends ServiceProvider {
+ *   register(container: Container) {
+ *     container.singleton('db', () => new DatabaseManager());
+ *   }
+ *
+ *   boot(core: PlanetCore) {
+ *     const db = core.container.make<DatabaseManager>('db');
+ *     db.setDefaultConnection(core.config.get('database.default'));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ServiceProvider {
+    /**
+     * Reference to the application core instance.
+     * Set during provider registration.
+     */
+    protected core?: PlanetCore;
+    /**
+     * Whether this provider should be deferred.
+     * Deferred providers are only registered when one of their
+     * provided services is actually requested from the container.
+     */
+    deferred: boolean;
+    /**
+     * Get the services provided by this provider.
+     * Used for deferred loading - provider is only loaded when
+     * one of these services is requested.
+     *
+     * @returns Array of service keys this provider offers
+     *
+     * @example
+     * ```typescript
+     * provides(): string[] {
+     *   return ['db', 'db.connection'];
+     * }
+     * ```
+     */
+    provides(): string[];
+    /**
+     * Register bindings in the container.
+     *
+     * This method is called during the registration phase.
+     * **Warning**: Do not resolve services from other providers here,
+     * as they may not be registered yet.
+     *
+     * Supports both synchronous and asynchronous registration.
+     *
+     * @param container - The IoC container instance
+     */
+    abstract register(container: Container): void | Promise<void>;
+    /**
+     * Bootstrap any application services.
+     *
+     * This method is called after ALL providers have registered.
+     * You can safely resolve services from the container here.
+     *
+     * @param core - The PlanetCore application instance
+     */
+    boot?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is ready to accept requests.
+     *
+     * This method is called after ALL providers have booted.
+     * Use this for final initialization before the server starts accepting traffic.
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onReady?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is shutting down.
+     *
+     * This method is called during graceful shutdown.
+     * Use this to clean up resources, close connections, etc.
+     *
+     * Providers are called in reverse order (LIFO).
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onShutdown?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Set the core instance reference.
+     * Called internally by the application during registration.
+     *
+     * @internal
+     */
+    setCore(core: PlanetCore): void;
+    /**
+     * Merge configuration from a value into the application config.
+     *
+     * If the configuration key already exists and both the existing value and
+     * the new value are objects, they will be shallow-merged. Otherwise, the
+     * new value will overwrite the existing one.
+     *
+     * @param config - The ConfigManager instance.
+     * @param key - The configuration key to set (supports dot notation).
+     * @param value - The configuration value or object to merge.
+     *
+     * @example
+     * ```typescript
+     * this.mergeConfig(config, 'database', {
+     *   default: 'mysql',
+     *   connections: { ... }
+     * });
+     * ```
+     */
+    protected mergeConfig(config: ConfigManager, key: string, value: unknown): void;
+    /**
+     * Merge configuration from an async loader.
+     * Useful for loading config from .ts files dynamically.
+     *
+     * @param config - The ConfigManager instance
+     * @param key - The configuration key
+     * @param loader - Async function that returns config value
+     *
+     * @example
+     * ```typescript
+     * await this.mergeConfigFrom(config, 'database', async () => {
+     *   return (await import('./config/database')).default;
+     * });
+     * ```
+     */
+    protected mergeConfigFrom(config: ConfigManager, key: string, loader: () => Promise<unknown>): Promise<void>;
+    /**
+     * Paths that should be published by the CLI.
+     * Maps source paths to destination paths.
+     */
+    private static publishables;
+    /**
+     * Register paths to be published by the CLI.
+     *
+     * Used by CLI commands like `gravito vendor:publish` to copy configuration,
+     * views, or assets from the package to the application directory.
+     *
+     * @param paths - A record mapping source paths to destination paths.
+     * @param group - Optional group name for selective publishing (e.g., 'config', 'views').
+     *
+     * @example
+     * ```typescript
+     * this.publishes({
+     *   './config/cache.ts': 'config/cache.ts',
+     *   './views/errors': 'resources/views/errors'
+     * }, 'config');
+     * ```
+     */
+    protected publishes(paths: Record<string, string>, group?: string): void;
+    /**
+     * Get all publishable paths for a group.
+     *
+     * @param group - The group name (defaults to provider class name)
+     * @returns Map of source to destination paths
+     */
+    static getPublishables(group?: string): Map<string, string>;
+    /**
+     * Get all publish groups.
+     *
+     * @returns Array of group names
+     */
+    static getPublishGroups(): string[];
+}

package/dist/adapters/GravitoEngineAdapter.d.ts

@@ -0,0 +1,27 @@
+import { Gravito } from '../engine/Gravito';
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoVariables, HttpMethod } from '../http/types';
+import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
+/**
+ * GravitoEngineAdapter - Optimized adapter using the Standalone Gravito Engine
+ *
+ * This adapter is exclusively for Bun and provides the best performance
+ * by using the specialized Gravito engine with object pooling and AOT routing.
+ */
+export declare class GravitoEngineAdapter<V extends GravitoVariables = GravitoVariables> implements HttpAdapter<V> {
+    readonly name = "gravito-engine";
+    readonly version = "1.0.0";
+    private engine;
+    constructor(config?: AdapterConfig);
+    get native(): Gravito;
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
+    routes(routes: RouteDefinition[]): void;
+    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    onError(handler: GravitoErrorHandler<V>): void;
+    onNotFound(handler: GravitoNotFoundHandler<V>): void;
+    fetch: (request: Request, _server?: unknown) => Response | Promise<Response>;
+    warmup(paths: string[]): Promise<void>;
+    createContext(_request: Request): GravitoContext<V>;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
+}

package/dist/adapters/bun/AdaptiveAdapter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Adaptive HTTP Adapter Selector
+ *
+ * Automatically chooses between BunNativeAdapter (high-performance)
+ * and PhotonAdapter (feature-rich) based on real-time metrics.
+ *
+ * @experimental
+ * @since 2.1.0
+ */
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, HttpMethod } from '../../http/types';
+import type { HttpAdapter, RouteDefinition } from '../types';
+/**
+ * Configuration for adaptive adapter
+ */
+export interface AdaptiveAdapterConfig {
+    /**
+     * Enable adaptive selection
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Measurement window size (default: 1000 requests)
+     * @default 1000
+     */
+    windowSize?: number;
+    /**
+     * Switch threshold (multiple of slower adapter)
+     * @default 1.5 (switch if 50% faster)
+     */
+    switchThreshold?: number;
+    /**
+     * Minimum requests before switching
+     * @default 100
+     */
+    minRequestsBeforeSwitch?: number;
+    /**
+     * Enable verbose logging
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Adaptive HTTP Adapter
+ *
+ * Monitors performance and automatically switches between adapters
+ * to optimize for the current workload.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new AdaptiveAdapter({
+ *   enabled: true,
+ *   switchThreshold: 1.5,
+ *   minRequestsBeforeSwitch: 100
+ * })
+ *
+ * adapter.route('GET', '/api/users', handler)
+ *
+ * // Automatically switches to BunNativeAdapter after 100 requests
+ * // if it's 50% faster than PhotonAdapter
+ * ```
+ */
+export declare class AdaptiveAdapter implements HttpAdapter {
+    readonly name = "adaptive";
+    readonly version = "0.0.1";
+    private primary;
+    private metrics;
+    private requestCount;
+    private config;
+    get native(): unknown;
+    constructor(config?: AdaptiveAdapterConfig);
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler | GravitoMiddleware)[]): void;
+    routes(routes: RouteDefinition[]): void;
+    use(path: string, ...middleware: GravitoMiddleware[]): void;
+    useGlobal(...middleware: GravitoMiddleware[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware[]): void;
+    mount(path: string, subAdapter: HttpAdapter): void;
+    createContext(request: Request): GravitoContext;
+    onError(handler: GravitoErrorHandler): void;
+    onNotFound(handler: GravitoNotFoundHandler): void;
+    fetch(request: Request, _server?: unknown): Promise<Response>;
+    /**
+     * Get current performance metrics
+     */
+    getMetrics(): {
+        adapter: string;
+        requestCount: number;
+        averageTime: number;
+        p50: number;
+        p99: number;
+    };
+    /**
+     * Force adapter switching (for testing/debugging)
+     */
+    switchAdapter(adapter: HttpAdapter): void;
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+}

package/dist/adapters/bun/BunContext.d.ts

@@ -0,0 +1,54 @@
+import { RequestScopeManager } from '../../Container/RequestScopeManager';
+import type { ContentfulStatusCode, GravitoContext, GravitoVariables, ProxyOptions, StatusCode } from '../../http/types';
+import { BunRequest } from './BunRequest';
+/**
+ * Bun-optimized implementation of GravitoContext.
+ * @internal
+ */
+export declare class BunContext<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
+    readonly env: Record<string, unknown>;
+    req: BunRequest;
+    private _variables;
+    private _requestScope;
+    /**
+     * URL generator helper
+     */
+    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
+    private _status;
+    private _headers;
+    private _executionCtx?;
+    res: Response | undefined;
+    readonly native: unknown;
+    constructor(request: Request, env?: Record<string, unknown>, executionCtx?: ExecutionContext);
+    /**
+     * Create a proxied instance to enable object destructuring of context variables
+     * This allows: async list({ userService }: Context)
+     */
+    static create<V extends GravitoVariables = GravitoVariables>(request: Request, env?: Record<string, unknown>, executionCtx?: ExecutionContext): GravitoContext<V>;
+    json<T>(data: T, status?: ContentfulStatusCode): Response;
+    text(text: string, status?: ContentfulStatusCode): Response;
+    html(html: string, status?: ContentfulStatusCode): Response;
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    body(data: BodyInit | null, status?: StatusCode): Response;
+    stream(stream: ReadableStream, status?: ContentfulStatusCode): Response;
+    notFound(message?: string): Response;
+    forbidden(message?: string): Response;
+    unauthorized(message?: string): Response;
+    badRequest(message?: string): Response;
+    forward(target: string, options?: ProxyOptions): Promise<Response>;
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    header(name: string): string | undefined;
+    /**
+     * Reset context state for reuse in pooling scenarios
+     * @internal
+     */
+    reset(request: Request): void;
+    status(code: StatusCode): void;
+    get<K extends keyof V>(key: K): V[K];
+    set<K extends keyof V>(key: K, value: V[K]): void;
+    get executionCtx(): ExecutionContext | undefined;
+    requestScope(): RequestScopeManager;
+    scoped<T>(key: string | symbol, factory: () => T): T;
+}

package/dist/adapters/bun/BunNativeAdapter.d.ts

@@ -0,0 +1,66 @@
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, HttpMethod } from '../../http/types';
+import type { HttpAdapter, RouteDefinition } from '../types';
+import type { WebSocketRouteHandlers } from './BunWebSocketHandler';
+/**
+ * Native Bun-optimized HTTP Adapter for Gravito.
+ * Uses Bun's standard Request/Response classes and efficient router.
+ * @public
+ */
+export declare class BunNativeAdapter implements HttpAdapter {
+    readonly name = "bun-native";
+    readonly version = "0.0.1";
+    get native(): unknown;
+    private router;
+    private middlewares;
+    private errorHandler;
+    private notFoundHandler;
+    private contextPool;
+    private readonly maxPoolSize;
+    private middlewareChainCache;
+    private wsHandler;
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler | GravitoMiddleware)[]): void;
+    routes(routes: RouteDefinition[]): void;
+    use(path: string, ...middleware: GravitoMiddleware[]): void;
+    useGlobal(...middleware: GravitoMiddleware[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware[]): void;
+    /**
+     * P1 Fix: Accurate path pattern matching for middleware
+     * Handles wildcards: *, /api/*, /api
+     */
+    private matchesPath;
+    /**
+     * P2 optimization: Pre-compile middleware chain for a path
+     */
+    private getCompiledMiddlewareChain;
+    /**
+     * P0 Fix: Context object pooling to prevent state pollution
+     */
+    private acquireContext;
+    /**
+     * P0 Fix: Release context back to pool
+     */
+    private releaseContext;
+    mount(path: string, subAdapter: HttpAdapter): void;
+    createContext(request: Request): GravitoContext;
+    onError(handler: GravitoErrorHandler): void;
+    onNotFound(handler: GravitoNotFoundHandler): void;
+    /**
+     * 註冊 WebSocket 路由
+     */
+    registerWebSocketRoute(path: string, handlers: WebSocketRouteHandlers): void;
+    /**
+     * 取得 WebSocket handler（供 Bun.serve 使用）
+     */
+    get websocket(): {
+        open?: (ws: unknown) => void | Promise<void>;
+        message?: (ws: unknown, data: string | Buffer | Uint8Array) => void | Promise<void>;
+        close?: (ws: unknown, code: number, reason: string) => void | Promise<void>;
+        drain?: (ws: unknown) => void | Promise<void>;
+    };
+    /**
+     * Predictive Route Warming (JIT Optimization)
+     */
+    warmup(paths: string[]): Promise<void>;
+    fetch(request: Request, _server?: unknown): Promise<Response>;
+    private executeChain;
+}