vafast 0.6.2 → 0.7.1

package/README.md

@@ -474,13 +474,74 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 ## 🎯 核心功能
 
 - ⚡ **JIT 编译验证器** - Schema 验证器编译缓存，避免重复编译
-- 🌲 **Radix Tree 路由** - O(k) 时间复杂度的高效路由匹配
+- 🌲 **Radix Tree 路由** - O(k) 时间复杂度的高效路由匹配（详见[路由规则](#路由匹配规则)）
 - 🎯 **快速请求解析** - 优化的 Query/Cookie 解析，比标准方法快 2x
 - 🔒 **端到端类型安全** - 完整的 TypeScript 类型推断
 - 🧩 **灵活中间件系统** - 可组合的中间件架构
 - 📡 **SSE 流式响应** - 内置 Server-Sent Events 支持，适用于 AI 聊天、进度更新等场景
 - 📦 **零配置** - 开箱即用，无需复杂配置
 
+### 路由匹配规则
+
+Vafast 使用 Radix Tree 实现高效路由匹配，支持以下特性：
+
+**1. 路由类型**
+
+```typescript
+// 静态路由
+'/users'
+'/api/v1/health'
+
+// 动态参数 (:param)
+'/users/:id'
+'/posts/:postId/comments/:commentId'
+
+// 通配符 (* 或 *name)
+'/files/*'           // 匿名通配符，params['*']
+'/static/*filepath'  // 命名通配符，params['filepath']
+```
+
+**2. 优先级规则（与 Hono/Fastify 一致）**
+
+```
+静态路由 > 动态参数 > 通配符
+```
+
+```typescript
+// 注册顺序不影响优先级
+router.register('GET', '/users/:id', dynamicHandler);
+router.register('GET', '/users/admin', staticHandler);  // 后注册
+
+// 匹配结果
+GET /users/admin   → staticHandler  ✅ 静态优先
+GET /users/123     → dynamicHandler
+```
+
+**3. 同一位置支持不同参数名**
+
+不同路由在同一位置可以使用不同的参数名，每个路由独立返回其定义的参数名：
+
+```typescript
+// 同一位置（/sessions/ 后）使用不同参数名
+router.register('PUT', '/sessions/:id', updateHandler);
+router.register('GET', '/sessions/:sessionId/messages', messagesHandler);
+
+// 每个路由返回各自定义的参数名
+PUT /sessions/123           → params = { id: '123' }
+GET /sessions/456/messages  → params = { sessionId: '456' }
+
+// CRUD 场景完全支持
+router.register('GET', '/users/:userId', getHandler);
+router.register('PUT', '/users/:id', updateHandler);
+router.register('DELETE', '/users/:uid', deleteHandler);
+
+GET /users/1    → { userId: '1' }
+PUT /users/2    → { id: '2' }
+DELETE /users/3 → { uid: '3' }
+```
+
+> 💡 参数名冲突时会输出警告（建议保持一致），但不影响功能。
+
 ### 返回值与错误处理
 
 Vafast 提供简洁、对称的响应 API：
@@ -528,33 +589,27 @@ defineRoute({
 
 ### SSE 流式响应
 
-内置 `createSSEHandler` 支持 Server-Sent Events，适用于 AI 聊天、进度更新等场景：
+通过 `sse: true` 显式声明 SSE 端点，适用于 AI 聊天、进度更新等场景：
 
 ```typescript
-import { createSSEHandler, defineRoute, defineRoutes, Type } from 'vafast'
+import { defineRoute, defineRoutes, Type } from 'vafast'
 
-// 创建 SSE handler
-const progressHandler = createSSEHandler(
-  { params: Type.Object({ taskId: Type.String() }) },
-  async function* ({ params }) {
-    yield { event: 'start', data: { taskId: params.taskId } }
-    
-    for (let i = 0; i <= 100; i += 10) {
-      yield { data: { progress: i } }
-      await new Promise(r => setTimeout(r, 100))
-    }
-    
-    yield { event: 'complete', data: { message: 'Done!' } }
-  }
-)
-
-// 在 defineRoute 中使用
 const routes = defineRoutes([
   defineRoute({
     method: 'GET',
     path: '/tasks/:taskId/progress',
+    sse: true,  // 显式声明 SSE 端点
     schema: { params: Type.Object({ taskId: Type.String() }) },
-    handler: progressHandler,
+    handler: async function* ({ params }) {
+      yield { event: 'start', data: { taskId: params.taskId } }
+      
+      for (let i = 0; i <= 100; i += 10) {
+        yield { data: { progress: i } }
+        await new Promise(r => setTimeout(r, 100))
+      }
+      
+      yield { event: 'complete', data: { message: 'Done!' } }
+    },
   }),
 ])
 ```

package/dist/{base-server-D7ny0Kwm.d.mts → base-server-CeJ8LTBk.d.mts}

@@ -1,4 +1,4 @@
-import { r as Middleware } from "./types-D4pCpFZ_.mjs";
+import { r as Middleware } from "./types-aczawQFE.mjs";
 
 //#region src/server/base-server.d.ts
 
@@ -36,4 +36,4 @@ declare abstract class BaseServer {
 }
 //#endregion
 export { BaseServer as t };
-//# sourceMappingURL=base-server-D7ny0Kwm.d.mts.map
+//# sourceMappingURL=base-server-CeJ8LTBk.d.mts.map

package/dist/{base64url-DNUGwekK.d.mts → base64url-CAmasWF0.d.mts}

@@ -3,4 +3,4 @@ declare function base64urlEncode(str: string): string;
 declare function base64urlDecode(str: string): string;
 //#endregion
 export { base64urlEncode as n, base64urlDecode as t };
-//# sourceMappingURL=base64url-DNUGwekK.d.mts.map
+//# sourceMappingURL=base64url-CAmasWF0.d.mts.map

package/dist/{component-route-Bxb-08X7.d.mts → component-route-CGbmQm5P.d.mts}

@@ -1,4 +1,4 @@
-import { r as Middleware } from "./types-D4pCpFZ_.mjs";
+import { r as Middleware } from "./types-aczawQFE.mjs";
 
 //#region src/types/component-route.d.ts
 
@@ -28,4 +28,4 @@ interface FlattenedComponentRoute extends ComponentRoute {
 }
 //#endregion
 export { FlattenedComponentRoute as n, NestedComponentRoute as r, ComponentRoute as t };
-//# sourceMappingURL=component-route-Bxb-08X7.d.mts.map
+//# sourceMappingURL=component-route-CGbmQm5P.d.mts.map

package/dist/{component-server-DQ3nZWFc.d.mts → component-server-CKcXIvMg.d.mts}

@@ -1,6 +1,6 @@
-import { r as NestedComponentRoute, t as ComponentRoute } from "./component-route-Bxb-08X7.mjs";
-import { t as BaseServer } from "./base-server-D7ny0Kwm.mjs";
-import { t as DependencyManager } from "./dependency-manager-DIN9X0Gj.mjs";
+import { r as NestedComponentRoute, t as ComponentRoute } from "./component-route-CGbmQm5P.mjs";
+import { t as BaseServer } from "./base-server-CeJ8LTBk.mjs";
+import { t as DependencyManager } from "./dependency-manager-mqzLAocb.mjs";
 
 //#region src/server/component-server.d.ts
 
@@ -35,4 +35,4 @@ declare class ComponentServer extends BaseServer {
 }
 //#endregion
 export { ComponentServer as t };
-//# sourceMappingURL=component-server-DQ3nZWFc.d.mts.map
+//# sourceMappingURL=component-server-CKcXIvMg.d.mts.map

package/dist/{contract-CuruqP6h.d.mts → contract-C-xQoZ6r.d.mts}

@@ -71,4 +71,4 @@ declare function generateAITools(routes: readonly unknown[]): AITool[];
 declare function getApiSpec(routesOrContext?: readonly unknown[] | Record<string, unknown>): ApiSpec;
 //#endregion
 export { generateAITools as n, getApiSpec as r, ApiSpec as t };
-//# sourceMappingURL=contract-CuruqP6h.d.mts.map
+//# sourceMappingURL=contract-C-xQoZ6r.d.mts.map

package/dist/{contract-Cwmmo-Nn.mjs → contract-vSyKiRwz.mjs}

@@ -16,7 +16,7 @@ function generateSpec(routes) {
 		};
 		if (r.name) spec.name = r.name;
 		if (r.description) spec.description = r.description;
-		if (r.sse === true || r.handler?.__sse?.__brand === "SSE") spec.sse = true;
+		if (r.sse === true) spec.sse = true;
 		if (r.schema) {
 			const schema = r.schema;
 			if (schema.body || schema.query || schema.params || schema.headers || schema.cookies || schema.response) {
@@ -113,4 +113,4 @@ function getRoutesFromRegistry() {
 
 //#endregion
 export { getApiSpec as n, generateAITools as t };
-//# sourceMappingURL=contract-Cwmmo-Nn.mjs.map
+//# sourceMappingURL=contract-vSyKiRwz.mjs.map

package/dist/contract-vSyKiRwz.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-vSyKiRwz.mjs","names":[],"sources":["../src/utils/contract.ts"],"sourcesContent":["/**\n * API Spec 生成器\n *\n * 用于生成 API 规范，支持：\n * - 跨仓库类型同步\n * - AI 工具函数生成\n * - Swagger/OpenAPI 文档生成\n *\n * @example\n * ```typescript\n * import { getApiSpec } from 'vafast'\n *\n * // 方式 1：直接作为 handler（推荐，自动从全局 Registry 获取）\n * const allRoutes = [\n *   ...routes,\n *   { method: 'GET', path: '/api-spec', handler: getApiSpec }\n * ]\n *\n * // 方式 2：显式传参（灵活场景，如只暴露公开 API）\n * { handler: () => getApiSpec(publicRoutes) }\n * ```\n */\n\nimport type { TSchema } from '@sinclair/typebox'\nimport type { RouteSchema } from '../defineRoute'\nimport { getRouteRegistry } from './route-registry'\n\n/** 路由规范信息 */\ninterface RouteSpec {\n  method: string\n  path: string\n  name?: string\n  description?: string\n  /** 是否为 SSE 端点（Server-Sent Events） */\n  sse?: boolean\n  schema?: {\n    body?: TSchema\n    query?: TSchema\n    params?: TSchema\n    headers?: TSchema\n    cookies?: TSchema\n    response?: TSchema\n  }\n}\n\n/** API 规范 */\nexport interface ApiSpec {\n  version: string\n  generatedAt: string\n  routes: RouteSpec[]\n}\n\n/** AI 工具函数格式 */\ninterface AITool {\n  name: string\n  description?: string\n  parameters?: TSchema\n}\n\n/**\n * 从路由数组生成 API 规范\n */\nfunction generateSpec(routes: readonly unknown[]): ApiSpec {\n  const routeSpecs: RouteSpec[] = []\n\n  for (const route of routes) {\n    const r = route as {\n      method?: string\n      path?: string\n      name?: string\n      description?: string\n      schema?: RouteSchema\n      sse?: boolean\n    }\n\n    if (!r.method || !r.path) continue\n\n    // 跳过 spec 接口本身\n    if (r.path === '/api-spec' || r.path === '/__spec__') continue\n\n    const spec: RouteSpec = {\n      method: r.method,\n      path: r.path,\n    }\n\n    // 直接从路由获取 name 和 description\n    if (r.name) spec.name = r.name\n    if (r.description) spec.description = r.description\n\n    // SSE 标记\n    if (r.sse === true) {\n      spec.sse = true\n    }\n\n    // 直接从路由获取 schema\n    if (r.schema) {\n      const schema = r.schema\n      if (schema.body || schema.query || schema.params || schema.headers || schema.cookies || schema.response) {\n        spec.schema = {}\n        if (schema.body) spec.schema.body = schema.body\n        if (schema.query) spec.schema.query = schema.query\n        if (schema.params) spec.schema.params = schema.params\n        if (schema.headers) spec.schema.headers = schema.headers\n        if (schema.cookies) spec.schema.cookies = schema.cookies\n        if (schema.response) spec.schema.response = schema.response\n      }\n    }\n\n    routeSpecs.push(spec)\n  }\n\n  return {\n    version: '1.0.0',\n    generatedAt: new Date().toISOString(),\n    routes: routeSpecs,\n  }\n}\n\n/**\n * 从路由数组生成 AI 工具函数\n *\n * 可直接用于 OpenAI Function Calling / Claude Tools\n *\n * @example\n * ```typescript\n * const tools = generateAITools(routes)\n * // [{ name: 'get_users', description: '获取用户列表', parameters: {...} }]\n * ```\n */\nexport function generateAITools(routes: readonly unknown[]): AITool[] {\n  const tools: AITool[] = []\n\n  for (const route of routes) {\n    const r = route as {\n      method?: string\n      path?: string\n      name?: string\n      description?: string\n      schema?: RouteSchema\n    }\n\n    if (!r.method || !r.path) continue\n    if (r.path === '/api-spec' || r.path === '/__spec__') continue\n\n    // 使用 name 或从 path 生成\n    const name = r.name || pathToToolName(r.method, r.path)\n\n    const tool: AITool = { name }\n    if (r.description) tool.description = r.description\n\n    // GET 用 query，其他用 body\n    if (r.schema) {\n      if (r.method === 'GET' && r.schema.query) {\n        tool.parameters = r.schema.query\n      } else if (r.schema.body) {\n        tool.parameters = r.schema.body\n      }\n    }\n\n    tools.push(tool)\n  }\n\n  return tools\n}\n\n/** 从路径生成工具名 */\nfunction pathToToolName(method: string, path: string): string {\n  const segments = path.split('/').filter(Boolean)\n  const cleanSegments = segments\n    .map(s => s.startsWith(':') ? '' : s)\n    .filter(Boolean)\n\n  const prefix = method.toLowerCase()\n  const suffix = cleanSegments.join('_')\n\n  return suffix ? `${prefix}_${suffix}` : prefix\n}\n\n/**\n * 获取 API 规范\n *\n * 支持多种调用方式：\n * 1. 直接作为 handler：自动从全局 Registry 获取（推荐）\n * 2. 无参调用：同上，用于 CLI/测试\n * 3. 有参调用：显式传递路由数组（灵活场景）\n *\n * @param routesOrContext - 可选，路由数组或 handler context。不传则从全局 Registry 获取\n * @returns ApiSpec 对象\n *\n * @example\n * ```typescript\n * import { getApiSpec } from 'vafast'\n *\n * // 方式 1：直接作为 handler（推荐，最简洁）\n * { method: 'GET', path: '/api-spec', handler: getApiSpec }\n *\n * // 方式 2：显式传参（只暴露公开 API）\n * { handler: () => getApiSpec(publicRoutes) }\n *\n * // 方式 3：本地使用（CLI、测试）\n * const spec = getApiSpec()\n * ```\n */\nexport function getApiSpec(routesOrContext?: readonly unknown[] | Record<string, unknown>): ApiSpec {\n  // 智能检测：是路由数组还是 handler context\n  // 路由数组：Array && 第一个元素有 method 属性\n  const isRoutesArray = Array.isArray(routesOrContext) &&\n    routesOrContext.length > 0 &&\n    typeof (routesOrContext[0] as Record<string, unknown>)?.method === 'string'\n\n  const routeList = isRoutesArray\n    ? routesOrContext\n    : getRoutesFromRegistry()\n\n  return generateSpec(routeList)\n}\n\n/**\n * 从全局 Registry 获取路由列表\n * 包含 schema 信息（Registry 存储完整路由）\n */\nfunction getRoutesFromRegistry(): readonly unknown[] {\n  try {\n    const registry = getRouteRegistry()\n    return registry.getAll()\n  } catch {\n    // Registry 未初始化时返回空数组\n    return []\n  }\n}\n"],"mappings":";;;;;;AA8DA,SAAS,aAAa,QAAqC;CACzD,MAAM,aAA0B,EAAE;AAElC,MAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,IAAI;AASV,MAAI,CAAC,EAAE,UAAU,CAAC,EAAE,KAAM;AAG1B,MAAI,EAAE,SAAS,eAAe,EAAE,SAAS,YAAa;EAEtD,MAAM,OAAkB;GACtB,QAAQ,EAAE;GACV,MAAM,EAAE;GACT;AAGD,MAAI,EAAE,KAAM,MAAK,OAAO,EAAE;AAC1B,MAAI,EAAE,YAAa,MAAK,cAAc,EAAE;AAGxC,MAAI,EAAE,QAAQ,KACZ,MAAK,MAAM;AAIb,MAAI,EAAE,QAAQ;GACZ,MAAM,SAAS,EAAE;AACjB,OAAI,OAAO,QAAQ,OAAO,SAAS,OAAO,UAAU,OAAO,WAAW,OAAO,WAAW,OAAO,UAAU;AACvG,SAAK,SAAS,EAAE;AAChB,QAAI,OAAO,KAAM,MAAK,OAAO,OAAO,OAAO;AAC3C,QAAI,OAAO,MAAO,MAAK,OAAO,QAAQ,OAAO;AAC7C,QAAI,OAAO,OAAQ,MAAK,OAAO,SAAS,OAAO;AAC/C,QAAI,OAAO,QAAS,MAAK,OAAO,UAAU,OAAO;AACjD,QAAI,OAAO,QAAS,MAAK,OAAO,UAAU,OAAO;AACjD,QAAI,OAAO,SAAU,MAAK,OAAO,WAAW,OAAO;;;AAIvD,aAAW,KAAK,KAAK;;AAGvB,QAAO;EACL,SAAS;EACT,8BAAa,IAAI,MAAM,EAAC,aAAa;EACrC,QAAQ;EACT;;;;;;;;;;;;;AAcH,SAAgB,gBAAgB,QAAsC;CACpE,MAAM,QAAkB,EAAE;AAE1B,MAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,IAAI;AAQV,MAAI,CAAC,EAAE,UAAU,CAAC,EAAE,KAAM;AAC1B,MAAI,EAAE,SAAS,eAAe,EAAE,SAAS,YAAa;EAKtD,MAAM,OAAe,EAAE,MAFV,EAAE,QAAQ,eAAe,EAAE,QAAQ,EAAE,KAAK,EAE1B;AAC7B,MAAI,EAAE,YAAa,MAAK,cAAc,EAAE;AAGxC,MAAI,EAAE,QACJ;OAAI,EAAE,WAAW,SAAS,EAAE,OAAO,MACjC,MAAK,aAAa,EAAE,OAAO;YAClB,EAAE,OAAO,KAClB,MAAK,aAAa,EAAE,OAAO;;AAI/B,QAAM,KAAK,KAAK;;AAGlB,QAAO;;;AAIT,SAAS,eAAe,QAAgB,MAAsB;CAE5D,MAAM,gBADW,KAAK,MAAM,IAAI,CAAC,OAAO,QAAQ,CAE7C,KAAI,MAAK,EAAE,WAAW,IAAI,GAAG,KAAK,EAAE,CACpC,OAAO,QAAQ;CAElB,MAAM,SAAS,OAAO,aAAa;CACnC,MAAM,SAAS,cAAc,KAAK,IAAI;AAEtC,QAAO,SAAS,GAAG,OAAO,GAAG,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4B1C,SAAgB,WAAW,iBAAyE;AAWlG,QAAO,aARe,MAAM,QAAQ,gBAAgB,IAClD,gBAAgB,SAAS,KACzB,OAAQ,gBAAgB,IAAgC,WAAW,WAGjE,kBACA,uBAAuB,CAEG;;;;;;AAOhC,SAAS,wBAA4C;AACnD,KAAI;AAEF,SADiB,kBAAkB,CACnB,QAAQ;SAClB;AAEN,SAAO,EAAE"}

package/dist/{defineRoute-DyPa9FHa.d.mts → defineRoute-B9VdaoQA.d.mts}

@@ -2,6 +2,15 @@ import { Static, TSchema } from "@sinclair/typebox";
 
 //#region src/defineRoute.d.ts
 
+/** SSE 事件 */
+interface SSEEventType<T = unknown> {
+  event?: string;
+  data: T;
+  id?: string;
+  retry?: number;
+}
+/** SSE Generator 类型 */
+type SSEGeneratorType<TSchema$1 extends RouteSchema = RouteSchema> = (ctx: HandlerContext<TSchema$1>) => AsyncGenerator<SSEEventType<unknown>, void, unknown>;
 /** 路由 Schema 配置 */
 interface RouteSchema {
   body?: TSchema;
@@ -47,6 +56,12 @@ interface HandlerContext<TSchema$1 extends RouteSchema = RouteSchema> {
 type HandlerContextWithExtra<TSchema$1 extends RouteSchema, TExtra> = HandlerContext<TSchema$1> & TExtra;
 /** HTTP 方法 */
 type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
+/** Handler 上下文类型（带中间件扩展） */
+type HandlerCtx<TSchema$1 extends RouteSchema, TMiddleware extends readonly AnyMiddleware[]> = HandlerContextWithExtra<TSchema$1, MergeMiddlewareContexts<TMiddleware>>;
+/** 普通 Handler 类型 */
+type NormalHandler<TSchema$1 extends RouteSchema, TReturn, TMiddleware extends readonly AnyMiddleware[]> = (ctx: HandlerCtx<TSchema$1, TMiddleware>) => TReturn | Promise<TReturn>;
+/** SSE Generator Handler 类型（直接写 async function*，无需 createSSEHandler 包装） */
+type SSEHandler<TSchema$1 extends RouteSchema, TMiddleware extends readonly AnyMiddleware[]> = (ctx: HandlerCtx<TSchema$1, TMiddleware>) => AsyncGenerator<SSEEventType<unknown>, void, unknown>;
 /** 叶子路由配置（有 method 和 handler） */
 interface LeafRouteConfig<TMethod extends HTTPMethod = HTTPMethod, TPath extends string = string, TSchema$1 extends RouteSchema = RouteSchema, TReturn = unknown, TMiddleware extends readonly AnyMiddleware[] = readonly AnyMiddleware[]> {
   readonly method: TMethod;
@@ -54,7 +69,22 @@ interface LeafRouteConfig<TMethod extends HTTPMethod = HTTPMethod, TPath extends
   readonly name?: string;
   readonly description?: string;
   readonly schema?: TSchema$1;
-  readonly handler: (ctx: HandlerContextWithExtra<TSchema$1, MergeMiddlewareContexts<TMiddleware>>) => TReturn | Promise<TReturn>;
+  /**
+   * 是否为 SSE 端点（显式声明，推荐）
+   *
+   * 设置为 true 时，handler 应返回 AsyncGenerator：
+   * ```typescript
+   * sse: true,
+   * handler: async function* (ctx) { yield { data: ... } }
+   * ```
+   */
+  readonly sse?: boolean;
+  /**
+   * Handler 支持两种写法：
+   * 1. 普通函数: `async (ctx) => { return result }`
+   * 2. SSE Generator（需配合 sse: true）: `async function* (ctx) { yield { data: ... } }`
+   */
+  readonly handler: NormalHandler<TSchema$1, TReturn, TMiddleware> | SSEHandler<TSchema$1, TMiddleware>;
   readonly middleware?: TMiddleware;
   readonly docs?: {
     tags?: string[];
@@ -79,6 +109,8 @@ interface ProcessedRoute {
   name?: string;
   description?: string;
   schema?: RouteSchema;
+  /** 是否为 SSE 端点 */
+  sse?: boolean;
   handler: (req: Request) => Promise<Response>;
   middleware?: readonly AnyMiddleware[];
   docs?: {
@@ -135,9 +167,11 @@ declare function defineRoute<const TSchema$1 extends RouteSchema, TReturn, const
   readonly name?: string;
   readonly description?: string;
   readonly schema?: TSchema$1;
+  /** 是否为 SSE 端点，设置为 true 时 handler 应返回 AsyncGenerator */
+  readonly sse?: boolean;
   /** 显式声明上下文类型（用于父级中间件注入的场景） */
   readonly context?: TContext;
-  readonly handler: (ctx: HandlerContextWithExtra<TSchema$1, TContext & MergeMiddlewareContexts<TMiddleware>>) => TReturn | Promise<TReturn>;
+  readonly handler: (ctx: HandlerContextWithExtra<TSchema$1, TContext & MergeMiddlewareContexts<TMiddleware>>) => TReturn | Promise<TReturn> | AsyncGenerator<SSEEventType<unknown>, void, unknown>;
   readonly middleware?: TMiddleware;
   readonly docs?: {
     tags?: string[];
@@ -199,13 +233,23 @@ declare function defineRoute<const TMiddleware extends readonly AnyMiddleware[],
  * })
  * ```
  */
+/** withContext Handler 上下文类型 */
+type WithContextHandlerCtx<TSchema$1 extends RouteSchema, TContext extends object, TMiddleware extends readonly AnyMiddleware[]> = HandlerContextWithExtra<TSchema$1, TContext & MergeMiddlewareContexts<TMiddleware>>;
+/** withContext 支持的 Handler 类型（普通函数 + SSE Generator） */
+type WithContextHandler<TSchema$1 extends RouteSchema, TContext extends object, TMiddleware extends readonly AnyMiddleware[], TReturn> = ((ctx: WithContextHandlerCtx<TSchema$1, TContext, TMiddleware>) => TReturn | Promise<TReturn>) | ((ctx: WithContextHandlerCtx<TSchema$1, TContext, TMiddleware>) => AsyncGenerator<SSEEventType<unknown>, void, unknown>);
 declare function withContext<TContext extends object, TExtensions extends object = object>(): <const TSchema$1 extends RouteSchema, TReturn, const TMiddleware extends readonly AnyMiddleware[], TMethod extends HTTPMethod = HTTPMethod, TPath extends string = string>(config: {
   readonly method: TMethod;
   readonly path: TPath;
   readonly name?: string;
   readonly description?: string;
   readonly schema?: TSchema$1;
-  readonly handler: (ctx: HandlerContextWithExtra<TSchema$1, TContext & MergeMiddlewareContexts<TMiddleware>>) => TReturn | Promise<TReturn>;
+  /**
+   * 是否为 SSE 端点
+   * 设置为 true 时，handler 应返回 AsyncGenerator
+   */
+  readonly sse?: boolean;
+  /** Handler 支持两种写法：普通函数 或 SSE Generator（需配合 sse: true） */
+  readonly handler: WithContextHandler<TSchema$1, TContext, TMiddleware, TReturn>;
   readonly middleware?: TMiddleware;
   readonly docs?: {
     tags?: string[];
@@ -248,5 +292,5 @@ type InferableRoute<TMethod extends string = string, TPath extends string = stri
   readonly middleware?: ReadonlyArray<AnyMiddleware>;
 };
 //#endregion
-export { ProcessedRoute as a, RoutesWithSource as c, defineRoute as d, defineRoutes as f, NestedRouteConfig as i, TypedMiddleware as l, InferableRoute as n, Route as o, withContext as p, LeafRouteConfig as r, RouteSchema as s, HandlerContext as t, defineMiddleware as u };
-//# sourceMappingURL=defineRoute-DyPa9FHa.d.mts.map
+export { ProcessedRoute as a, RoutesWithSource as c, TypedMiddleware as d, defineMiddleware as f, withContext as h, NestedRouteConfig as i, SSEEventType as l, defineRoutes as m, InferableRoute as n, Route as o, defineRoute as p, LeafRouteConfig as r, RouteSchema as s, HandlerContext as t, SSEGeneratorType as u };
+//# sourceMappingURL=defineRoute-B9VdaoQA.d.mts.map

package/dist/defineRoute.d.mts

@@ -1,2 +1,2 @@
-import { a as ProcessedRoute, c as RoutesWithSource, d as defineRoute, f as defineRoutes, i as NestedRouteConfig, l as TypedMiddleware, n as InferableRoute, o as Route, p as withContext, r as LeafRouteConfig, s as RouteSchema, t as HandlerContext, u as defineMiddleware } from "./defineRoute-DyPa9FHa.mjs";
-export { HandlerContext, InferableRoute, LeafRouteConfig, NestedRouteConfig, ProcessedRoute, Route, RouteSchema, RoutesWithSource, TypedMiddleware, defineMiddleware, defineRoute, defineRoutes, withContext };
+import { a as ProcessedRoute, c as RoutesWithSource, d as TypedMiddleware, f as defineMiddleware, h as withContext, i as NestedRouteConfig, l as SSEEventType, m as defineRoutes, n as InferableRoute, o as Route, p as defineRoute, r as LeafRouteConfig, s as RouteSchema, t as HandlerContext, u as SSEGeneratorType } from "./defineRoute-B9VdaoQA.mjs";
+export { HandlerContext, InferableRoute, LeafRouteConfig, NestedRouteConfig, ProcessedRoute, Route, RouteSchema, RoutesWithSource, SSEEventType, SSEGeneratorType, TypedMiddleware, defineMiddleware, defineRoute, defineRoutes, withContext };

package/dist/defineRoute.mjs

@@ -54,37 +54,114 @@ function autoResponse(result) {
 	}
 	return new Response(null, { status: 204 });
 }
-/** 创建包装后的 handler */
+/**
+* 构建 HandlerContext（公共逻辑，供普通 handler 和 SSE handler 复用）
+*/
+async function buildHandlerContext(req, schema) {
+	const query = parseQuery(req);
+	const headers = parseHeaders(req);
+	const cookies = parseCookies(req);
+	const params = req.params || {};
+	let body = void 0;
+	if (req.method !== "GET" && req.method !== "HEAD") try {
+		body = await parseBody(req);
+	} catch {}
+	const data = {
+		body,
+		query,
+		params,
+		headers,
+		cookies
+	};
+	if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) validateAllSchemas(schema, data);
+	const extraCtx = req.__locals || {};
+	return {
+		req,
+		body,
+		query,
+		params,
+		headers,
+		cookies,
+		...extraCtx
+	};
+}
+/** 创建包装后的 handler（普通路由） */
 function wrapHandler(schema, userHandler) {
 	if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) precompileSchemas(schema);
 	return async (req) => {
 		try {
-			const query = parseQuery(req);
-			const headers = parseHeaders(req);
-			const cookies = parseCookies(req);
-			const params = req.params || {};
-			let body = void 0;
-			if (req.method !== "GET" && req.method !== "HEAD") try {
-				body = await parseBody(req);
-			} catch {}
-			const data = {
-				body,
-				query,
-				params,
-				headers,
-				cookies
-			};
-			if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) validateAllSchemas(schema, data);
-			const extraCtx = req.__locals || {};
-			return autoResponse(await userHandler({
-				req,
-				body,
-				query,
-				params,
-				headers,
-				cookies,
-				...extraCtx
-			}));
+			return autoResponse(await userHandler(await buildHandlerContext(req, schema)));
+		} catch (error) {
+			if (error instanceof VafastError) throw error;
+			if (error instanceof Error && error.message.includes("验证失败")) return json({
+				code: 400,
+				message: error.message
+			}, 400);
+			return json({
+				code: 500,
+				message: error instanceof Error ? error.message : "未知错误"
+			}, 500);
+		}
+	};
+}
+/**
+* 格式化 SSE 事件为字符串（内联，避免循环依赖）
+*/
+function formatSSEEvent(event) {
+	const lines = [];
+	if (event.id !== void 0) lines.push(`id: ${event.id}`);
+	if (event.event !== void 0) lines.push(`event: ${event.event}`);
+	if (event.retry !== void 0) lines.push(`retry: ${event.retry}`);
+	const dataStr = typeof event.data === "string" ? event.data : JSON.stringify(event.data);
+	for (const line of dataStr.split("\n")) lines.push(`data: ${line}`);
+	return lines.join("\n") + "\n\n";
+}
+/**
+* 将 AsyncGenerator 包装为 SSE Handler
+* 
+* 支持用户直接写 `async function* (ctx) { yield ... }` 而无需 createSSEHandler
+*/
+function wrapGeneratorToSSEHandler(generator) {
+	return async (ctx) => {
+		const stream = new ReadableStream({ async start(controller) {
+			const encoder = new TextEncoder();
+			try {
+				for await (const event of generator(ctx)) controller.enqueue(encoder.encode(formatSSEEvent(event)));
+			} catch (error) {
+				const errorEvent = formatSSEEvent({
+					event: "error",
+					data: { error: error instanceof Error ? error.message : "未知错误" }
+				});
+				controller.enqueue(encoder.encode(errorEvent));
+			} finally {
+				controller.close();
+			}
+		} });
+		return new Response(stream, { headers: {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache",
+			"Connection": "keep-alive",
+			"X-Accel-Buffering": "no"
+		} });
+	};
+}
+/**
+* 创建 SSE handler 的请求包装器
+* 
+* SSE handler 与普通 handler 使用相同的上下文构建流程（buildHandlerContext），
+* 确保：
+* - body/query/params 解析一致
+* - schema 验证统一
+* - 中间件注入的上下文（如 userInfo）自动可用
+* - 错误处理统一
+* 
+* 唯一区别：SSE handler 返回的是 SSE Stream Response，而非普通 JSON Response
+*/
+function wrapSSEHandler(schema, sseHandler) {
+	if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) precompileSchemas(schema);
+	return async (req) => {
+		try {
+			return await sseHandler(await buildHandlerContext(req, schema));
 		} catch (error) {
 			if (error instanceof VafastError) throw error;
 			if (error instanceof Error && error.message.includes("验证失败")) return json({
@@ -112,50 +189,6 @@ function isNestedRoute(route) {
 function defineRoute(config) {
 	return config;
 }
-/**
-* 创建带预设上下文类型的路由定义器
-*
-* 用于父级中间件注入上下文的场景，定义一次，多处复用
-*
-* @example
-* ```typescript
-* // 1. 在 middleware/index.ts 中定义
-* export const defineAuthRoute = withContext<{ userInfo: UserInfo }>()
-*
-* // 2. 在路由文件中使用
-* defineAuthRoute({
-*   method: 'GET',
-*   path: '/profile',
-*   handler: ({ userInfo }) => {
-*     // userInfo 自动有类型！
-*     return { id: userInfo.id }
-*   }
-* })
-* ```
-*/
-/**
-* 带扩展类型的路由定义器
-*
-* @typeParam TContext - Handler 上下文类型（如 { userInfo: UserInfo }）
-* @typeParam TExtensions - 路由扩展字段类型（如 { webhook?: boolean }）
-*
-* @example
-* ```typescript
-* // 定义扩展类型
-* interface WebhookExtension {
-*   webhook?: boolean | { eventKey?: string }
-* }
-*
-* // 使用扩展
-* const defineRoute = withContext<MyContext, WebhookExtension>()
-* defineRoute({
-*   method: 'POST',
-*   path: '/create',
-*   webhook: true,  // TypeScript 严格检查
-*   handler: ...
-* })
-* ```
-*/
 function withContext() {
 	return (config) => {
 		return config;
@@ -170,18 +203,18 @@ function flattenRoutes(routes, parentPath = "", parentMiddleware = [], parent) {
 		const fullPath = parentPath + route.path;
 		const mergedMiddleware = [...parentMiddleware, ...route.middleware || []];
 		if (isLeafRoute(route)) {
-			const isSSE = route.handler?.__sse?.__brand === "SSE";
+			const isSSE = route.sse === true;
 			const processed = {
 				method: route.method,
 				path: fullPath,
 				name: route.name,
 				description: route.description,
 				schema: route.schema,
-				handler: isSSE ? route.handler : wrapHandler(route.schema, route.handler),
+				sse: isSSE || void 0,
+				handler: isSSE ? wrapSSEHandler(route.schema, wrapGeneratorToSSEHandler(route.handler)) : wrapHandler(route.schema, route.handler),
 				middleware: mergedMiddleware.length > 0 ? mergedMiddleware : void 0,
 				docs: route.docs
 			};
-			if (isSSE) processed.handler.__sse = { __brand: "SSE" };
 			if (parent) processed.parent = parent;
 			const knownKeys = [
 				"method",