@gravito/ripple 4.0.1 → 5.0.0

package/dist/core/src/Router.d.ts

@@ -55,6 +55,33 @@ export interface RouteOptions {
     /** 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.)
@@ -64,6 +91,8 @@ export interface RouteOptions {
  * Helper class for chained route configuration (prefix, domain, etc.)
  * @public
  */
+export interface RouteGroup extends RoutingMethods {
+}
 export declare class RouteGroup {
     private router;
     private options;
@@ -81,21 +110,6 @@ export declare class RouteGroup {
      * Define routes within this group
      */
     group(callback: (router: Router | RouteGroup) => void): void;
-    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;
     resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
     /**
      * Register a route that forwards requests to another URL (Gateway Proxy).
@@ -118,6 +132,8 @@ export declare class RouteGroup {
  * - 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<{
@@ -210,36 +226,6 @@ export declare class Router {
      * Accepts individual handlers or arrays of handlers.
      */
     middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
-    /**
-     * Register a GET route.
-     */
-    get(path: string, handler: RouteHandler): Route;
-    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
-    get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
-    /**
-     * Register a POST route.
-     */
-    post(path: string, handler: RouteHandler): Route;
-    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
-    post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
-    /**
-     * Register a PUT route.
-     */
-    put(path: string, handler: RouteHandler): Route;
-    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
-    put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
-    /**
-     * Register a DELETE route.
-     */
-    delete(path: string, handler: RouteHandler): Route;
-    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
-    delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
-    /**
-     * Register a PATCH route.
-     */
-    patch(path: string, handler: RouteHandler): Route;
-    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
-    patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
     /**
      * Register a route that forwards requests to another URL (Gateway Proxy).
      * @param method - HTTP method or 'all'
@@ -267,7 +253,7 @@ export declare class Router {
     /**
      * Internal Request Registration
      */
-    req(method: HttpMethod, path: string, requestOrHandlerOrMiddleware: FormRequestClass | RouteHandler | GravitoMiddleware | GravitoMiddleware[], handler?: RouteHandler, options?: RouteOptions): Route;
+    req(method: HttpMethod, path: string, requestOrHandlerOrMiddleware: RouteDefinitionArg, handler?: RouteHandler, options?: RouteOptions): Route;
 }
 /**
  * Standard RESTful resource action names.

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

@@ -7,7 +7,7 @@ import { BunRequest } from './BunRequest';
  */
 export declare class BunContext<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
     readonly env: Record<string, unknown>;
-    readonly req: BunRequest;
+    req: BunRequest;
     private _variables;
     private _requestScope;
     /**
@@ -40,6 +40,11 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
         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;

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

@@ -1,5 +1,6 @@
 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.
@@ -13,15 +14,49 @@ export declare class BunNativeAdapter implements HttpAdapter {
     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>;
+    } | undefined;
     /**
      * Predictive Route Warming (JIT Optimization)
      */

package/dist/core/src/adapters/bun/BunWebSocketHandler.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WebSocket 路由管理器
+ *
+ * 負責註冊和分發 WebSocket 事件到相應的路由處理器
+ */
+export interface WebSocketRouteHandlers {
+    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>;
+}
+export declare class BunWebSocketHandler {
+    private routes;
+    /**
+     * 註冊 WebSocket 路由
+     */
+    register(path: string, handlers: WebSocketRouteHandlers): void;
+    /**
+     * 檢查是否有該路由
+     * 支援精確匹配和 wildcard 匹配
+     */
+    hasRoute(path: string): boolean;
+    /**
+     * 檢查是否有任何已註冊的路由
+     */
+    hasAnyRoute(): boolean;
+    /**
+     * 將 handlers 轉換為 Bun.serve websocket config
+     */
+    toHandler(): {
+        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>;
+    };
+    /**
+     * 尋找符合路徑的 handler
+     * 優先精確匹配，再 wildcard 匹配
+     */
+    private findHandler;
+    /**
+     * 路徑匹配邏輯
+     * 支援：
+     * - 精確匹配：/chat
+     * - Wildcard：/api/*, /api*
+     */
+    private matchesPath;
+}

package/dist/core/src/adapters/bun/RadixRouter.d.ts

@@ -6,6 +6,7 @@ import { type RouteHandler, type RouteMatch } from './types';
 export declare class RadixRouter {
     private root;
     private globalConstraints;
+    private routeCache;
     /**
      * Add a generic parameter constraint
      */

package/dist/core/src/adapters/bun/index.d.ts

@@ -0,0 +1,7 @@
+export * from './BunContext';
+export * from './BunNativeAdapter';
+export * from './BunRequest';
+export * from './BunWebSocketHandler';
+export * from './RadixNode';
+export * from './RadixRouter';
+export * from './types';

package/dist/core/src/binary/BinaryUtils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * BinaryUtils - 統一的二進制轉換工具類
+ *
+ * 支援 Bun 原生 API 優化，並提供 Node.js 回退路徑。
+ * 設計為 isomorphic，可在 Bun 和 Node.js 環境中運行。
+ * @public
+ */
+/**
+ * BinaryUtils - 提供統一的二進制轉換、編碼、壓縮工具
+ * 所有方法均為靜態方法，可直接呼叫
+ * @public
+ */
+export declare class BinaryUtils {
+    /**
+     * 將各種資料類型轉換為 Uint8Array
+     * @param data - 輸入資料（Blob、Buffer、string、ArrayBuffer 或 Uint8Array）
+     * @returns Uint8Array
+     * @public
+     */
+    static toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;
+    /**
+     * 將各種資料類型轉換為 ArrayBuffer
+     * @param data - 輸入資料
+     * @returns ArrayBuffer
+     * @public
+     */
+    static toArrayBuffer(data: Blob | Buffer | string | Uint8Array | ArrayBuffer): Promise<ArrayBuffer>;
+    /**
+     * 將 Uint8Array 編碼為 Base64 字串
+     * 在 Bun 環境中使用原生 toBase64()，否則使用 Buffer
+     * @param data - 輸入的 Uint8Array
+     * @returns Base64 字串
+     * @public
+     */
+    static toBase64(data: Uint8Array): string;
+    /**
+     * 將 Base64 字串解碼為 Uint8Array
+     * @param base64 - Base64 字串
+     * @returns Uint8Array
+     * @public
+     */
+    static fromBase64(base64: string): Uint8Array;
+    /**
+     * 將 Uint8Array 編碼為 Base64URL 字串（URL 安全，無填充）
+     * @param data - 輸入的 Uint8Array
+     * @returns Base64URL 字串
+     * @public
+     */
+    static toBase64Url(data: Uint8Array): string;
+    /**
+     * 將 Base64URL 字串解碼為 Uint8Array
+     * @param base64url - Base64URL 字串
+     * @returns Uint8Array
+     * @public
+     */
+    static fromBase64Url(base64url: string): Uint8Array;
+    /**
+     * 將 Uint8Array 編碼為十六進制字串
+     * 在 Bun 環境中使用原生 toHex()，否則使用 Buffer
+     * @param data - 輸入的 Uint8Array
+     * @returns 十六進制字串（小寫）
+     * @public
+     */
+    static toHex(data: Uint8Array): string;
+    /**
+     * 將十六進制字串解碼為 Uint8Array
+     * @param hex - 十六進制字串
+     * @returns Uint8Array
+     * @throws {TypeError} 如果輸入不是有效的十六進制字串
+     * @public
+     */
+    static fromHex(hex: string): Uint8Array;
+    /**
+     * 使用 gzip 壓縮資料
+     * 在 Bun 環境中使用原生 Bun.gzipSync()，在 Node.js 中使用 zlib
+     * @param data - 輸入資料
+     * @param level - 壓縮等級（0-9），預設為 6
+     * @returns 壓縮後的 Uint8Array
+     * @public
+     */
+    static gzip(data: Uint8Array, level?: number): Promise<Uint8Array>;
+    /**
+     * 解壓縮 gzip 資料
+     * 在 Bun 環境中使用原生 Bun.gunzipSync()，在 Node.js 中使用 zlib
+     * @param data - gzip 壓縮的 Uint8Array
+     * @returns 解壓縮後的 Uint8Array
+     * @public
+     */
+    static gunzip(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * 將 ReadableStream<Uint8Array> 讀取為 Uint8Array
+     * 在 Bun 環境中使用原生 Bun.readableStreamToBytes()，否則手動讀取 chunks
+     * @param stream - 輸入的 ReadableStream
+     * @returns Uint8Array
+     * @public
+     */
+    static readableStreamToBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+    /**
+     * 將 ReadableStream<Uint8Array> 讀取為 ArrayBuffer
+     * @param stream - 輸入的 ReadableStream
+     * @returns ArrayBuffer
+     * @public
+     */
+    static readableStreamToArrayBuffer(stream: ReadableStream<Uint8Array>): Promise<ArrayBuffer>;
+}

package/dist/core/src/binary/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Binary utilities module for @gravito/core
+ * @packageDocumentation
+ */
+export { BinaryUtils } from './BinaryUtils';

package/dist/core/src/compat/async-local-storage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Universal AsyncLocalStorage wrapper.
+ * Automatically switches between node:async_hooks and a browser mock.
+ */
+export declare const AsyncLocalStorage: {
+    new <_T>(): any;
+};

package/dist/core/src/compat/crypto.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Universal Crypto wrapper.
+ * Automatically switches between node:crypto and globalThis.crypto.
+ */
+export declare const randomUUID: () => string;
+export declare const randomBytes: (size: number) => any;

package/dist/core/src/engine/AOTRouter.d.ts

@@ -101,6 +101,16 @@ export declare class AOTRouter {
      * @returns Combined middleware array
      */
     private collectMiddleware;
+    /**
+     * Get all static routes optimized for Bun's native router.
+     *
+     * Unlike basic offloading, this version supports routes with middleware
+     * by pre-compiling the middleware chain into a single native handler.
+     *
+     * @param onMatch - Factory to wrap handler and middleware into a Bun-compatible function
+     * @returns Record of path -> Handler (Bun-compatible)
+     */
+    getNativeRoutes(onMatch: (handler: Handler, middleware: Middleware[], path: string) => (req: Request) => Response | Promise<Response>): Record<string, any>;
     /**
      * Check if a path is static (no parameters or wildcards)
      */

package/dist/core/src/engine/FastContext.d.ts

@@ -29,6 +29,7 @@ declare class FastRequestImpl implements FastRequest {
     private _cachedFormData;
     private _formDataParsed;
     private _cachedQueries;
+    private _cachedCookies;
     private _ctx;
     constructor(ctx: FastContext);
     /**
@@ -51,6 +52,7 @@ declare class FastRequestImpl implements FastRequest {
     queries(): Record<string, string | string[]>;
     header(name: string): string | undefined;
     headers(): Record<string, string>;
+    get cookies(): Record<string, string>;
     json<T = unknown>(): Promise<T>;
     text(): Promise<string>;
     formData(): Promise<FormData>;
@@ -87,9 +89,18 @@ export declare class FastContext implements IFastContext {
     json<T>(data: T, status?: number): Response;
     text(text: string, status?: number): Response;
     html(html: string, status?: number): Response;
+    /**
+     * Escape HTML using Bun's SIMD-accelerated native implementation
+     */
+    escape(html: string): string;
     redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
     body(data: BodyInit | null, status?: number): Response;
-    stream(stream: ReadableStream, status?: number): Response;
+    /**
+     * Send high-performance binary response (e.g. CBOR, Protobuf)
+     * Utilizing Bun's native ArrayBufferSink for zero-allocation construction.
+     */
+    binary(data: Uint8Array | ArrayBuffer, status?: number): Response;
+    stream(stream: any, status?: number): Response;
     notFound(message?: string): Response;
     forbidden(message?: string): Response;
     unauthorized(message?: string): Response;
@@ -97,6 +108,13 @@ export declare class FastContext implements IFastContext {
     forward(target: string, _options?: any): Promise<Response>;
     header(name: string): string | undefined;
     header(name: string, value: string): void;
+    /**
+     * Status code setter (no-op)
+     *
+     * Note: Since all response helpers accept a `status` parameter,
+     * this method is not actively used. Status should be set directly
+     * in the response helper call (e.g., `ctx.json({}, 201)`).
+     */
     status(_code: number): void;
     private _store;
     get<T>(key: string): T;

package/dist/core/src/engine/Gravito.d.ts

@@ -33,10 +33,6 @@ export declare class Gravito {
     constructor(options?: EngineOptions);
     /**
      * Register a GET route
-     *
-     * @param path - Route path (e.g., '/users/:id')
-     * @param handlers - Handler and optional middleware
-     * @returns This instance for chaining
      */
     get(path: string, ...handlers: Handler[]): this;
     /**
@@ -52,7 +48,7 @@ export declare class Gravito {
      */
     delete(path: string, ...handlers: Handler[]): this;
     /**
-     * Register a PDF route
+     * Register a PATCH route
      */
     patch(path: string, ...handlers: Handler[]): this;
     /**
@@ -94,15 +90,22 @@ export declare class Gravito {
      */
     warmup(paths: string[]): Promise<void>;
     /**
-     * Handle an incoming request
+     * Generate Native Bun.serve Configuration
+     *
+     * Offloads static routes to Bun's SIMD-accelerated native router.
+     * Supports pre-compiled middleware chains for zero runtime lookup.
      */
-    fetch: (request: Request) => Promise<Response>;
+    serveConfig(baseConfig?: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Optimize TLS Configuration for Bun 1.39+
+     */
+    private optimizeTLS;
     /**
-     * Handle routes with middleware (async path)
+     * Handle an incoming request
      */
-    private handleWithMiddleware;
+    fetch: (request: Request) => Promise<Response>;
     /**
-     * Handle dynamic routes (Radix Tree lookup)
+     * Handle dynamic routes with Radix Tree
      */
     private handleDynamicRoute;
     /**
@@ -125,12 +128,4 @@ export declare class Gravito {
      * Add a route to the router
      */
     private addRoute;
-    /**
-     * Execute middleware chain followed by handler
-     */
-    private executeMiddleware;
-    /**
-     * Handle errors (Async version for dynamic/middleware paths)
-     */
-    private handleError;
 }

package/dist/core/src/engine/MinimalContext.d.ts

@@ -44,6 +44,7 @@ declare class MinimalRequest implements FastRequest {
     json<T = unknown>(): Promise<T>;
     text(): Promise<string>;
     formData(): Promise<FormData>;
+    get cookies(): Record<string, string>;
     get raw(): Request;
 }
 /**
@@ -75,6 +76,7 @@ export declare class MinimalContext implements IFastContext {
     unauthorized(message?: string): Response;
     badRequest(message?: string): Response;
     forward(target: string, _options?: any): Promise<Response>;
+    escape(html: string): string;
     get<T>(_key: string): T;
     set(_key: string, _value: any): void;
     /**

package/dist/core/src/engine/analyzer.d.ts

@@ -1,27 +1,113 @@
 /**
- * Handler Static Analyzer (Elysia-inspired)
+ * @fileoverview Handler 靜態分析器（Elysia-inspired，升級版）
  *
- * Analyzes handler functions to determine what request properties
- * they access, allowing for optimized code paths.
+ * 分析 handler 函式，偵測其存取了哪些請求屬性，
+ * 以選擇最優化的 Context 類型（minimal/fast/full）。
+ *
+ * ## 版本歷史
+ *
+ * ### v2（目前版本）- 使用 Bun.Transpiler
+ * - 精確度：~99%（AST 層級分析）
+ * - 正確處理假陽性：`const header = '...'` 不再誤判
+ * - 支援解構賦值：`const { header } = ctx.req`
+ * - 支援 Minified 代碼（transformSync 先標準化）
+ * - Fallback：若 Transpiler 失敗，退回字串匹配
+ *
+ * ### v1（原版本）- 字串匹配
+ * - 精確度：~85%
+ * - 假陽性：變數名稱包含目標字串會誤判
+ * - 假陰性：解構賦值無法偵測
+ * - Minified 代碼可能失效
+ *
+ * @module @gravito/core/engine/analyzer
+ * @since 3.0.0
  */
 /**
- * Represents the results of a static analysis performed on a handler function.
+ * Handler 靜態分析結果
+ *
+ * 記錄 handler 函式使用了哪些請求屬性，
+ * 用於選擇最優化的 Context 類型。
  *
  * @public
  * @since 3.0.0
  */
 export interface HandlerAnalysis {
+    /** 是否存取了 request headers */
     usesHeaders: boolean;
+    /** 是否存取了 query string 參數 */
     usesQuery: boolean;
+    /** 是否存取了 request body */
     usesBody: boolean;
+    /** 是否存取了 route 路徑參數 */
     usesParams: boolean;
+    /** 是否為非同步函式（含 async/await） */
     isAsync: boolean;
 }
 /**
- * Analyze a handler function to detect what it accesses
+ * 分析 handler 函式，偵測其使用了哪些請求屬性
+ *
+ * 使用 Bun.Transpiler 進行 AST 層級的精確分析（精確度 ~99%）。
+ * 若 Transpiler 不可用，自動 fallback 到字串匹配（精確度 ~85%）。
+ *
+ * ## 精確度提升說明
+ *
+ * **假陽性修復**（原本誤判，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會誤判 usesHeaders = true
+ * // 因為字串 'header' 出現在變數名稱中
+ * function handler(ctx) {
+ *   const header = 'Content-Type'  // ← 變數名稱，不是 API 呼叫
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = false ✅
+ * ```
+ *
+ * **假陰性修復**（原本漏偵測，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會漏偵測解構賦值
+ * function handler(ctx) {
+ *   const { header, query } = ctx.req  // ← 解構賦值
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = true, usesQuery = true ✅
+ * ```
+ *
+ * @param handler - 要分析的 handler 函式
+ * @returns HandlerAnalysis 分析結果
+ *
+ * @example
+ * ```typescript
+ * const handler = async (ctx) => {
+ *   const name = ctx.req.query('name')
+ *   return ctx.json({ name })
+ * }
+ *
+ * const analysis = analyzeHandler(handler)
+ * // analysis.usesQuery === true
+ * // analysis.usesHeaders === false
+ * // analysis.isAsync === true
+ *
+ * const type = getOptimalContextType(analysis)
+ * // type === 'fast'
+ * ```
  */
 export declare function analyzeHandler(handler: Function): HandlerAnalysis;
 /**
- * Determine optimal context type based on analysis
+ * 根據分析結果決定最優化的 Context 類型
+ *
+ * Context 類型由輕到重：
+ * - `minimal`：僅支援路徑參數與靜態回應，零 overhead
+ * - `fast`：支援 headers 與 query，使用物件池
+ * - `full`：支援完整功能含 body 解析（async）
+ *
+ * 選擇邏輯（優先順序）：
+ * 1. 若存取 headers → `fast`（header 設置需要完整支援）
+ * 2. 若不存取任何屬性 → `minimal`
+ * 3. 若僅存取 params → `minimal`（params 在 minimal 中也可用）
+ * 4. 若存取 body → `full`（async body 解析需要完整 context）
+ * 5. 其他 → `fast`
+ *
+ * @param analysis - HandlerAnalysis 分析結果
+ * @returns 最優化的 context 類型
  */
 export declare function getOptimalContextType(analysis: HandlerAnalysis): 'minimal' | 'fast' | 'full';

package/dist/core/src/engine/types.d.ts

@@ -25,6 +25,7 @@ export interface FastContext {
     unauthorized(message?: string): Response;
     badRequest(message?: string): Response;
     forward(target: string, options?: any): Promise<Response>;
+    escape(html: string): string;
     /** Header management */
     header(name: string): string | undefined;
     header(name: string, value: string): void;
@@ -70,6 +71,8 @@ export interface FastRequest {
     header(name: string): string | undefined;
     /** Get all headers */
     headers(): Record<string, string>;
+    /** Get all cookies (Native Bun 1.39+ / Lazy Parsed) */
+    readonly cookies: Record<string, string>;
     /** Parse JSON body */
     json<T = unknown>(): Promise<T>;
     /** Parse text body */