vafast 0.5.4 → 0.5.6

package/README.md

@@ -8,21 +8,24 @@
 
 > Vafast 不只是框架，更是一种 **结构、清晰、可控** 的开发哲学。
 
-```typescript
-import { Server, createHandler } from 'vafast';
-
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Vafast!') }
-]);
+## 🚀 快速开始
 
-export default { port: 3000, fetch: server.fetch };
+```bash
+npx create-vafast-app
 ```
 
+按照提示输入项目名称，然后运行：
+
 ```bash
-# 启动服务器
-npx tsx index.ts
+cd my-vafast-app
+npm install
+npm run dev
 ```
 
+访问 [http://localhost:3000](http://localhost:3000) 即可看到 "Hello Vafast!"。
+
+> 💡 想要手动配置？查看 [安装](#-安装) 部分。
+
 ## ⚡ 性能
 
 | 框架 | RPS | 相对性能 |
@@ -37,10 +40,47 @@ npx tsx index.ts
 
 ## 📦 安装
 
+### 方式一：使用脚手架（推荐）
+
+使用官方脚手架快速创建项目：
+
+```bash
+npx create-vafast-app
+```
+
+### 方式二：手动安装
+
+在现有项目中安装：
+
 ```bash
 npm install vafast
 ```
 
+然后创建 `index.ts`：
+
+```typescript
+import { Server, defineRoute, defineRoutes, serve } from 'vafast';
+
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Vafast!'
+  })
+]);
+
+const server = new Server(routes);
+serve({ fetch: server.fetch, port: 3000 }, (info) => {
+  console.log(`🚀 Server running at http://localhost:${info.port}`);
+});
+```
+
+运行：
+
+```bash
+npx tsx index.ts
+```
+
 ## 💡 设计哲学
 
 ### 结构即真相 — 无装饰器，无链式魔法
@@ -72,14 +112,25 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const routes: Route[] = [
-  { method: 'GET',  path: '/users',     handler: createHandler(() => 'list users') },
-  { method: 'POST', path: '/users',     handler: createHandler(({ body }) => body) },
-  { method: 'GET',  path: '/users/:id', handler: createHandler(({ params }) => `User ${params.id}`) },
-];
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    handler: () => 'list users'
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    handler: ({ body }) => body
+  }),
+  defineRoute({
+    method: 'GET',
+    path: '/users/:id',
+    handler: ({ params }) => `User ${params.id}`
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -110,22 +161,21 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler, err } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes, err } from 'vafast';
 
-const routes: Route[] = [
-  {
+const routes = defineRoutes([
+  defineRoute({
     method: 'GET',
     path: '/user',
-    handler: createHandler((ctx) => {
-      const name = ctx.query.name;
+    handler: ({ query }) => {
+      const name = query.name;
       if (!name) {
         throw err.badRequest('Missing name');  // ✨ 简洁！
       }
       return `Hello, ${name}`;
-    }),
-  },
-];
+    },
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -155,21 +205,29 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
-import type { Route, Middleware } from 'vafast';
+import { Server, defineRoute, defineRoutes, defineMiddleware } from 'vafast';
 
-const authMiddleware: Middleware = async (req, next) => {
+const authMiddleware = defineMiddleware(async (req, next) => {
   const token = req.headers.get('Authorization');
   if (!token) return new Response('Unauthorized', { status: 401 });
   return next();
-};
+});
 
-const routes: Route[] = [
+const routes = defineRoutes([
   // 无中间件
-  { method: 'GET', path: '/public', handler: createHandler(() => 'public') },
+  defineRoute({
+    method: 'GET',
+    path: '/public',
+    handler: () => 'public'
+  }),
   // 仅 auth
-  { method: 'GET', path: '/api/users', middleware: [authMiddleware], handler: createHandler(() => 'users') },
-];
+  defineRoute({
+    method: 'GET',
+    path: '/api/users',
+    middleware: [authMiddleware],
+    handler: () => 'users'
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -177,6 +235,69 @@ export default { fetch: server.fetch };
 
 **对比：Vafast 的中间件直接声明在路由上，一目了然。**
 
+### 扩展字段 — 声明式元数据，赋能业务逻辑
+
+**其他框架的问题：**
+- 路由定义和元数据分离，难以统一管理
+- 需要额外的配置文件或装饰器来存储 webhook、权限、计费等信息
+- 元数据查询需要遍历路由或维护独立映射表
+
+**Vafast 完整示例：**
+```typescript
+import { Server, defineRoute, defineRoutes, getRouteRegistry, defineMiddleware } from 'vafast';
+
+// 计费中间件（基于路由元数据）
+const billingMiddleware = defineMiddleware(async (req, next) => {
+  const route = getRouteRegistry().get(req.method, new URL(req.url).pathname);
+  
+  // 从路由元数据读取计费配置
+  if (route?.billing) {
+    const { price, currency } = route.billing;
+    // 执行计费逻辑
+    await chargeUser(req, price, currency);
+  }
+  
+  return next();
+});
+
+const routes = defineRoutes([
+  defineRoute({
+    method: 'POST',
+    path: '/ai/generate',
+    name: 'AI 生成',
+    description: '生成 AI 内容',
+    // ✨ 扩展字段：计费配置
+    billing: { price: 0.01, currency: 'USD' },
+    // ✨ 扩展字段：Webhook 事件
+    webhook: { eventKey: 'ai.generate', enabled: true },
+    // ✨ 扩展字段：权限要求
+    permission: 'ai.generate',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      const result = await generateAI(body.prompt);
+      return { result };
+    }
+  }),
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    // 免费 API，无需计费
+    handler: () => ({ users: [] })
+  }),
+]);
+
+const server = new Server(routes);
+
+// 查询所有需要计费的 API
+const paidRoutes = getRouteRegistry().filter('billing');
+// 查询所有 Webhook 事件
+const webhookRoutes = getRouteRegistry().filter('webhook');
+// 按权限筛选
+const aiRoutes = getRouteRegistry().filterBy(r => r.permission?.startsWith('ai.'));
+```
+
+**对比：Vafast 的扩展字段让路由定义成为单一数据源，元数据查询、中间件配置、业务逻辑都基于声明式配置。**
+
 ### 类型注入 — 跨文件不丢失
 
 **Hono 跨文件类型问题：**
@@ -205,33 +326,37 @@ export function setupRoutes(app: Hono) {
 export type AuthContext = { user: { id: string; role: string } };
 
 // -------- file: middleware/auth.ts --------
-import type { Middleware } from 'vafast';
+import { defineMiddleware } from 'vafast';
+import type { AuthContext } from '../types';
 
-export const authMiddleware: Middleware = async (req, next) => {
+// 使用 defineMiddleware 定义带类型的中间件
+export const authMiddleware = defineMiddleware<AuthContext>(async (req, next) => {
   const user = await verifyToken(req.headers.get('Authorization'));
-  (req as any).__locals = { user };
-  return next();
-};
+  return next({ user });  // 通过 next 传递上下文
+});
 
 // -------- file: handlers/profile.ts --------
-import { createHandlerWithExtra } from 'vafast';
-import type { AuthContext } from '../types';
+import { defineRoute } from 'vafast';
+import { authMiddleware } from '../middleware/auth';
 
-// 类型在 Handler 级别定义，任意文件都能用！
-export const getProfile = createHandlerWithExtra<AuthContext>((ctx) => {
-  const user = ctx.user;  // ✅ 类型完整: { id: string; role: string }
-  return { profile: user, isAdmin: user.role === 'admin' };
+// 类型在路由级别定义，任意文件都能用！
+export const getProfileRoute = defineRoute({
+  method: 'GET',
+  path: '/profile',
+  middleware: [authMiddleware],
+  handler: ({ user }) => {
+    // ✅ user 自动有类型: { id: string; role: string }
+    return { profile: user, isAdmin: user.role === 'admin' };
+  }
 });
 
 // -------- file: routes.ts --------
-import { Server } from 'vafast';
-import type { Route } from 'vafast';
-import { authMiddleware } from './middleware/auth';
-import { getProfile } from './handlers/profile';
+import { Server, defineRoutes } from 'vafast';
+import { getProfileRoute } from './handlers/profile';
 
-const routes: Route[] = [
-  { method: 'GET', path: '/profile', middleware: [authMiddleware], handler: getProfile },
-];
+const routes = defineRoutes([
+  getProfileRoute,
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -243,34 +368,49 @@ export default { fetch: server.fetch };
 
 **Bun 环境完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Bun!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Bun!'
+  })
 ]);
 
+const server = new Server(routes);
 export default { port: 3000, fetch: server.fetch };
 ```
 
 **Cloudflare Workers 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Workers!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Workers!'
+  })
 ]);
 
+const server = new Server(routes);
 export default { fetch: server.fetch };
 ```
 
 **Node.js 完整示例：**
 ```typescript
-import { Server, createHandler, serve } from 'vafast';
+import { Server, defineRoute, defineRoutes, serve } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Node!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Node!'
+  })
 ]);
 
+const server = new Server(routes);
 serve({ fetch: server.fetch, port: 3000 }, () => {
   console.log('Server running on http://localhost:3000');
 });
@@ -287,9 +427,13 @@ nest new my-app  # 生成 20+ 文件
 # ❌ Express - 需要配置和样板代码
 npm init && npm install express && mkdir routes controllers...
 
-# ✅ Vafast - 一个文件搞定
-echo "import { Server } from 'vafast';
-const server = new Server([{ method: 'GET', path: '/', handler: () => 'Hi' }]);
+# ✅ Vafast - 使用脚手架一键创建
+npx create-vafast-app
+
+# ✅ 或手动创建 - 一个文件搞定
+echo "import { Server, defineRoute, defineRoutes } from 'vafast';
+const routes = defineRoutes([defineRoute({ method: 'GET', path: '/', handler: () => 'Hi' })]);
+const server = new Server(routes);
 export default { fetch: server.fetch };" > index.ts && bun index.ts
 ```
 
@@ -304,6 +448,9 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 | **类型推断** | 优秀 | 良好 | **优秀 (TypeBox)** |
 | **跨文件类型** | ⚠️ 链断裂丢失 | ❌ 实例绑定丢失 | **✅ Handler 级独立** |
 | **类型定义位置** | 链式调用上下文 | App 实例泛型 | **Handler 泛型参数** |
+| **扩展字段** | ❌ 不支持 | ❌ 不支持 | **✅ 任意扩展字段** |
+| **元数据查询** | ❌ 需遍历 | ❌ 需遍历 | **✅ RouteRegistry API** |
+| **业务集成** | ⚠️ 需额外配置 | ⚠️ 需额外配置 | **✅ 声明式集成** |
 | **性能 (RPS)** | ~118K | ~56K | **~101K** |
 | **学习曲线** | 中等 | 简单 | **简单** |
 | **API 风格** | 函数式链 | Express-like | **配置式** |
@@ -317,8 +464,11 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 | **需要路由一览表** | **✅ Vafast** |
 | **需要精确中间件控制** | **✅ Vafast** |
 | **需要结构化错误** | **✅ Vafast** |
+| **需要扩展字段（webhook、计费、权限）** | **✅ Vafast** |
+| **需要元数据查询和筛选** | **✅ Vafast (RouteRegistry)** |
 | **大型项目多文件拆分** | **✅ Vafast (类型不丢失)** |
 | **团队协作类型安全** | **✅ Vafast** |
+| **API 网关/微服务场景** | **✅ Vafast (声明式配置)** |
 | 从 Express 迁移 | Hono (API 相似) |
 
 ## 🎯 核心功能
@@ -335,25 +485,31 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 Vafast 提供简洁、对称的响应 API：
 
 ```typescript
-import { createHandler, json, err } from 'vafast';
-
-// ==================== 成功响应 ====================
-return user                    // 200 + JSON（自动转换）
-return json(user, 201)         // 201 Created
-return json(user, 200, {       // 自定义头部
-  'X-Request-Id': 'abc123'
+import { defineRoute, json, err } from 'vafast';
+
+defineRoute({
+  method: 'POST',
+  path: '/users',
+  handler: ({ body }) => {
+    // ==================== 成功响应 ====================
+    return body                    // 200 + JSON（自动转换）
+    return json(body, 201)         // 201 Created
+    return json(body, 200, {       // 自定义头部
+      'X-Request-Id': 'abc123'
+    })
+    return 'Hello'                 // 200 + text/plain
+    return new Response(...)       // 完全控制
+
+    // ==================== 错误响应 ====================
+    throw err.badRequest('参数错误')     // 400
+    throw err.unauthorized('请先登录')   // 401
+    throw err.forbidden('无权限')        // 403
+    throw err.notFound('用户不存在')     // 404
+    throw err.conflict('用户名已存在')   // 409
+    throw err.internal('服务器错误')     // 500
+    throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
+  }
 })
-return 'Hello'                 // 200 + text/plain
-return new Response(...)       // 完全控制
-
-// ==================== 错误响应 ====================
-throw err.badRequest('参数错误')     // 400
-throw err.unauthorized('请先登录')   // 401
-throw err.forbidden('无权限')        // 403
-throw err.notFound('用户不存在')     // 404
-throw err.conflict('用户名已存在')   // 409
-throw err.internal('服务器错误')     // 500
-throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
 ```
 
 **API 速查表：**
@@ -372,20 +528,20 @@ throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
 ### 类型安全的路由
 
 ```typescript
-import { Server, defineRoutes, createHandler, Type } from 'vafast';
+import { Server, defineRoute, defineRoutes, Type } from 'vafast';
 
 const routes = defineRoutes([
-  {
+  defineRoute({
     method: 'POST',
     path: '/users',
-    handler: createHandler(
-      { body: Type.Object({ name: Type.String(), email: Type.String() }) },
-      ({ body }) => {
-        // body.name 和 body.email 自动类型推断
-        return { success: true, user: body };
-      }
-    )
-  }
+    schema: {
+      body: Type.Object({ name: Type.String(), email: Type.String() })
+    },
+    handler: ({ body }) => {
+      // body.name 和 body.email 自动类型推断
+      return { success: true, user: body };
+    }
+  })
 ]);
 
 const server = new Server(routes);
@@ -395,32 +551,34 @@ export default { port: 3000, fetch: server.fetch };
 ### 路径参数
 
 ```typescript
-{
+defineRoute({
   method: 'GET',
   path: '/users/:id',
-  handler: createHandler(
-    { params: Type.Object({ id: Type.String() }) },
-    ({ params }) => ({ userId: params.id })
-  )
-}
+  schema: {
+    params: Type.Object({ id: Type.String() })
+  },
+  handler: ({ params }) => ({ userId: params.id })
+})
 ```
 
 ### 中间件
 
 ```typescript
-const authMiddleware = async (req, next) => {
+import { defineMiddleware } from 'vafast';
+
+const authMiddleware = defineMiddleware(async (req, next) => {
   const token = req.headers.get('Authorization');
   if (!token) return new Response('Unauthorized', { status: 401 });
-  return next(req);
-};
+  return next();
+});
 
 const routes = defineRoutes([
-  {
+  defineRoute({
     method: 'GET',
     path: '/protected',
     middleware: [authMiddleware],
-    handler: createHandler(() => ({ secret: 'data' }))
-  }
+    handler: () => ({ secret: 'data' })
+  })
 ]);
 ```
 
@@ -428,22 +586,42 @@ const routes = defineRoutes([
 
 ```typescript
 const routes = defineRoutes([
-  {
+  defineRoute({
     path: '/api',
     middleware: [apiMiddleware],
     children: [
-      { method: 'GET', path: '/users', handler: getUsers },
-      { method: 'POST', path: '/users', handler: createUser },
-      {
+      defineRoute({
+        method: 'GET',
+        path: '/users',
+        handler: getUsers
+      }),
+      defineRoute({
+        method: 'POST',
+        path: '/users',
+        handler: createUser
+      }),
+      defineRoute({
         path: '/users/:id',
         children: [
-          { method: 'GET', path: '/', handler: getUser },
-          { method: 'PUT', path: '/', handler: updateUser },
-          { method: 'DELETE', path: '/', handler: deleteUser },
+          defineRoute({
+            method: 'GET',
+            path: '/',
+            handler: getUser
+          }),
+          defineRoute({
+            method: 'PUT',
+            path: '/',
+            handler: updateUser
+          }),
+          defineRoute({
+            method: 'DELETE',
+            path: '/',
+            handler: deleteUser
+          }),
         ]
-      }
+      })
     ]
-  }
+  })
 ]);
 ```
 
@@ -509,7 +687,7 @@ precompileSchemas([UserSchema, PostSchema, CommentSchema]);
 Vafast 内置 30+ 常用 format 验证器，**导入框架时自动注册**，对标 Zod 的内置验证：
 
 ```typescript
-import { Type, createHandler } from 'vafast';
+import { defineRoute, defineRoutes, Type } from 'vafast';
 
 // 直接使用内置 format，无需手动注册
 const UserSchema = Type.Object({
@@ -520,9 +698,16 @@ const UserSchema = Type.Object({
   createdAt: Type.String({ format: 'date-time' }),
 });
 
-const handler = createHandler({ body: UserSchema }, ({ body }) => {
-  return { success: true, user: body };
-});
+const routes = defineRoutes([
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    schema: { body: UserSchema },
+    handler: ({ body }) => {
+      return { success: true, user: body };
+    }
+  })
+]);
 ```
 
 **支持的 Format 列表：**
@@ -551,52 +736,113 @@ registerFormat('order-id', (v) => /^ORD-\d{8}$/.test(v));
 const isEmail = Patterns.EMAIL.test('test@example.com');
 ```
 
-### 路由注册表 (RouteRegistry)
+### 路由注册表 (RouteRegistry) — 声明式元数据，赋能业务逻辑
 
-Vafast 提供 `RouteRegistry` 用于路由元信息的收集和查询，适用于 API 文档生成、Webhook 事件注册、权限检查等场景：
+Vafast 的声明式路由支持**任意扩展字段**，让路由定义成为业务逻辑的单一数据源。适用于 API 文档生成、Webhook 事件注册、权限检查、**按 API 计费**等场景：
 
 ```typescript
-import { Server, createRouteRegistry } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes, getRouteRegistry, defineMiddleware } from 'vafast';
+
+// 计费中间件：基于路由元数据自动计费
+const billingMiddleware = defineMiddleware(async (req, next) => {
+  const registry = getRouteRegistry();
+  const url = new URL(req.url);
+  const route = registry.get(req.method, url.pathname);
+  
+  if (route?.billing) {
+    const { price, currency, unit } = route.billing;
+    const userId = getUserId(req);
+    
+    // 执行计费逻辑
+    await chargeUser(userId, {
+      api: `${req.method} ${url.pathname}`,
+      price,
+      currency,
+      unit, // 'request' | 'token' | 'minute'
+    });
+  }
+  
+  return next();
+});
 
 // 定义带扩展字段的路由
-const routes: Route[] = [
-  {
+const routes = defineRoutes([
+  defineRoute({
     method: 'POST',
     path: '/auth/signIn',
+    name: '用户登录',
+    description: '用户通过邮箱密码登录',
     handler: signInHandler,
-    name: '用户登录',                    // 扩展字段
-    description: '用户通过邮箱密码登录',   // 扩展字段
-    webhook: { eventKey: 'auth.signIn' }, // 自定义扩展
-  },
-  {
+    // ✨ 扩展字段：Webhook 事件
+    webhook: { eventKey: 'auth.signIn', enabled: true },
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/ai/generate',
+    name: 'AI 生成',
+    description: '生成 AI 内容',
+    // ✨ 扩展字段：按请求计费
+    billing: { price: 0.01, currency: 'USD', unit: 'request' },
+    // ✨ 扩展字段：权限要求
+    permission: 'ai.generate',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      return await generateAI(body.prompt);
+    }
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/ai/chat',
+    name: 'AI 对话',
+    // ✨ 扩展字段：按 token 计费
+    billing: { price: 0.0001, currency: 'USD', unit: 'token' },
+    permission: 'ai.chat',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      return await chatAI(body.message);
+    }
+  }),
+  defineRoute({
     method: 'GET',
     path: '/users',
     handler: getUsersHandler,
-    permission: 'users.read',            // 自定义扩展
-  },
-];
+    permission: 'users.read',
+    // 免费 API，无需计费配置
+  }),
+]);
 
 const server = new Server(routes);
 
-// 创建路由注册表
-const registry = createRouteRegistry(server.getRoutesWithMeta());
+// Server 创建时自动设置全局注册表，直接使用即可
+const registry = getRouteRegistry();
 
-// 查询路由
-const route = registry.get('POST', '/auth/signIn');
-console.log(route?.name);  // '用户登录'
+// 查询路由元信息
+const route = registry.get('POST', '/ai/generate');
+console.log(route?.name);        // 'AI 生成'
+console.log(route?.billing);     // { price: 0.01, currency: 'USD', unit: 'request' }
+console.log(route?.permission);  // 'ai.generate'
+
+// 筛选有特定字段的路由
+const webhookRoutes = registry.filter('webhook');      // 所有 Webhook 事件
+const paidRoutes = registry.filter('billing');         // 所有付费 API
+const aiRoutes = registry.filterBy(r => r.permission?.startsWith('ai.')); // AI 相关 API
 
 // 按分类获取
 const authRoutes = registry.getByCategory('auth');
-
-// 筛选有特定字段的路由
-const webhookRoutes = registry.filter('webhook');
-const permissionRoutes = registry.filter('permission');
+const aiCategoryRoutes = registry.getByCategory('ai');
 
 // 获取所有分类
-const categories = registry.getCategories();  // ['auth', 'users']
+const categories = registry.getCategories();  // ['auth', 'ai', 'users']
 ```
 
+**扩展字段的优势：**
+
+1. **单一数据源**：路由定义包含所有元数据，无需额外配置文件
+2. **类型安全**：扩展字段在 TypeScript 中完全类型化
+3. **运行时查询**：通过 `RouteRegistry` API 动态查询和筛选
+4. **业务集成**：中间件可直接读取路由元数据，实现计费、权限、审计等功能
+5. **API 网关友好**：声明式配置完美适配网关场景
+
 **Registry 实例方法：**
 
 | 方法 | 说明 |
@@ -612,52 +858,61 @@ const categories = registry.getCategories();  // ['auth', 'users']
 | `map(callback)` | 映射所有路由 |
 | `size` | 路由数量 |
 
-**全局便捷函数：**
+**全局便捷函数（Server 创建后自动可用）：**
 
 ```typescript
 import {
-  getRoute,
-  getAllRoutes,
-  filterRoutes,
-  getRoutesByMethod,
+  getRouteRegistry,  // 获取全局注册表实例
+  getRoute,          // 快速查询单个路由
+  getAllRoutes,      // 获取所有路由
+  filterRoutes,      // 按字段筛选
+  getRoutesByMethod, // 按 HTTP 方法获取
 } from 'vafast'
 
-// 获取单个路由
-const route = getRoute('POST', '/users')
+// 方式一：使用全局注册表实例
+const registry = getRouteRegistry()
+const route = registry.get('POST', '/users')
 
-// 获取所有路由
+// 方式二：使用便捷函数（推荐，更简洁）
+const route = getRoute('POST', '/users')
 const allRoutes = getAllRoutes()
-
-// 按字段筛选
 const webhookRoutes = filterRoutes('webhook')
-
-// 按 HTTP 方法获取
 const getRoutes = getRoutesByMethod('GET')
 const postRoutes = getRoutesByMethod('POST')
 
-// 按路径前缀筛选（自己 filter）
+// 按路径前缀筛选
 const authRoutes = getAllRoutes().filter(r => r.path.startsWith('/auth'))
 ```
 
+> 💡 **提示**：Server 创建时会自动设置全局 RouteRegistry，无需手动创建。在任意文件中导入 `getRouteRegistry()` 即可访问。
+
 ### API Spec 生成
 
 Vafast 提供 `getApiSpec` 用于生成 API 规范，支持跨仓库类型同步和 AI 工具函数生成：
 
 ```typescript
-import { Server, defineRoutes, getApiSpec } from 'vafast';
+import { Server, defineRoute, defineRoutes, getApiSpec } from 'vafast';
 
 const routes = defineRoutes([
-  { method: 'GET', path: '/users', handler: getUsers },
-  { method: 'POST', path: '/users', handler: createUser },
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    handler: getUsers
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    handler: createUser
+  }),
+  // 添加 API Spec 接口
+  defineRoute({
+    method: 'GET',
+    path: '/api-spec',
+    handler: getApiSpec  // 直接作为 handler
+  }),
 ]);
 
-// 添加 API Spec 接口
-const allRoutes = [
-  ...routes,
-  { method: 'GET', path: '/api-spec', handler: getApiSpec }  // 直接作为 handler
-];
-
-const server = new Server(allRoutes);
+const server = new Server(routes);
 ```
 
 **三种使用方式：**

package/dist/{defineRoute-BNqVD0_t.d.mts → defineRoute-FhAN4ivP.d.mts}

@@ -186,10 +186,27 @@ declare function withContext<TContext extends object>(): <const TSchema$1 extend
     responses?: Record<string, unknown>;
   };
 }) => LeafRouteConfig<TMethod, TPath, TSchema$1, TReturn, TMiddleware>;
+/** 带原始类型信息的路由数组 */
+type RoutesWithSource<T extends readonly RouteConfigResult[]> = ProcessedRoute[] & {
+  __source: T;
+};
 /**
  * 定义路由数组，支持嵌套路由
+ *
+ * 使用 `const T` 泛型自动保留字面量类型，无需手动添加 `as const`
+ *
+ * @example
+ * ```typescript
+ * const routes = defineRoutes([
+ *   defineRoute({ method: 'GET', path: '/users', handler: ... }),
+ *   defineRoute({ method: 'POST', path: '/users', handler: ... }),
+ * ])
+ *
+ * // 类型推断自动工作，无需 as const
+ * type Api = InferEden<typeof routes>
+ * ```
  */
-declare function defineRoutes(routes: ReadonlyArray<RouteConfigResult>): ProcessedRoute[];
+declare function defineRoutes<const T extends readonly RouteConfigResult[]>(routes: T): RoutesWithSource<T>;
 /** 可推断的路由类型（供 vafast-api-client 使用） */
 type InferableRoute<TMethod extends string = string, TPath extends string = string, TReturn = unknown, TSchema$1 extends RouteSchema = RouteSchema> = {
   readonly method: TMethod;
@@ -204,5 +221,5 @@ type InferableRoute<TMethod extends string = string, TPath extends string = stri
   readonly middleware?: ReadonlyArray<AnyMiddleware>;
 };
 //#endregion
-export { RouteSchema as a, defineRoute as c, ProcessedRoute as i, defineRoutes as l, InferableRoute as n, TypedMiddleware as o, LeafRouteConfig as r, defineMiddleware as s, HandlerContext as t, withContext as u };
-//# sourceMappingURL=defineRoute-BNqVD0_t.d.mts.map
+export { RouteSchema as a, defineMiddleware as c, withContext as d, ProcessedRoute as i, defineRoute as l, InferableRoute as n, RoutesWithSource as o, LeafRouteConfig as r, TypedMiddleware as s, HandlerContext as t, defineRoutes as u };
+//# sourceMappingURL=defineRoute-FhAN4ivP.d.mts.map

package/dist/defineRoute.d.mts

@@ -1,2 +1,2 @@
-import { a as RouteSchema, c as defineRoute, i as ProcessedRoute, l as defineRoutes, n as InferableRoute, o as TypedMiddleware, r as LeafRouteConfig, s as defineMiddleware, t as HandlerContext, u as withContext } from "./defineRoute-BNqVD0_t.mjs";
-export { HandlerContext, InferableRoute, LeafRouteConfig, ProcessedRoute, RouteSchema, TypedMiddleware, defineMiddleware, defineRoute, defineRoutes, withContext };
+import { a as RouteSchema, c as defineMiddleware, d as withContext, i as ProcessedRoute, l as defineRoute, n as InferableRoute, o as RoutesWithSource, r as LeafRouteConfig, s as TypedMiddleware, t as HandlerContext, u as defineRoutes } from "./defineRoute-FhAN4ivP.mjs";
+export { HandlerContext, InferableRoute, LeafRouteConfig, ProcessedRoute, RouteSchema, RoutesWithSource, TypedMiddleware, defineMiddleware, defineRoute, defineRoutes, withContext };

package/dist/defineRoute.mjs

@@ -164,9 +164,23 @@ function flattenRoutes(routes, parentPath = "", parentMiddleware = []) {
 }
 /**
 * 定义路由数组，支持嵌套路由
+* 
+* 使用 `const T` 泛型自动保留字面量类型，无需手动添加 `as const`
+* 
+* @example
+* ```typescript
+* const routes = defineRoutes([
+*   defineRoute({ method: 'GET', path: '/users', handler: ... }),
+*   defineRoute({ method: 'POST', path: '/users', handler: ... }),
+* ])
+* 
+* // 类型推断自动工作，无需 as const
+* type Api = InferEden<typeof routes>
+* ```
 */
 function defineRoutes(routes) {
-	return flattenRoutes(routes);
+	const processed = flattenRoutes(routes);
+	return Object.assign(processed, { __source: routes });
 }
 
 //#endregion

package/dist/defineRoute.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"defineRoute.mjs","names":[],"sources":["../src/defineRoute.ts"],"sourcesContent":["/**\n * 路由定义 - Schema 在路由级别定义，支持嵌套路由和中间件类型推断\n *\n * @example\n * ```typescript\n * // 定义带类型的中间件（函数式风格，通过 next 传递上下文）\n * const authMiddleware = defineMiddleware<{ user: User }>((req, next) => {\n *   const user = getUser(req)\n *   return next({ user })  // 通过 next 参数传递上下文\n * })\n *\n * // 路由自动推断中间件注入的类型\n * const routes = defineRoutes([\n *   defineRoute({\n *     path: '/api',\n *     middleware: [authMiddleware],\n *     children: [\n *       defineRoute({\n *         method: 'GET',\n *         path: '/profile',\n *         handler: ({ user }) => ({ name: user.name })  // ✅ user 有类型\n *       })\n *     ]\n *   })\n * ])\n * ```\n */\n\nimport type { TSchema, Static } from \"@sinclair/typebox\";\nimport { parseBody, parseQuery, parseHeaders, parseCookies } from \"./utils/parsers\";\nimport { validateAllSchemas, precompileSchemas } from \"./utils/validators/validators\";\nimport { json } from \"./utils/response\";\nimport { VafastError } from \"./middleware\";\n\n// ============= Schema 类型 =============\n\n/** 路由 Schema 配置 */\nexport interface RouteSchema {\n  body?: TSchema;\n  query?: TSchema;\n  params?: TSchema;\n  headers?: TSchema;\n  cookies?: TSchema;\n}\n\n/** 从 Schema 推断类型 */\ntype InferSchemaType<T extends RouteSchema> = {\n  body: T[\"body\"] extends TSchema ? Static<T[\"body\"]> : unknown;\n  query: T[\"query\"] extends TSchema ? Static<T[\"query\"]> : Record<string, string>;\n  params: T[\"params\"] extends TSchema ? Static<T[\"params\"]> : Record<string, string>;\n  headers: T[\"headers\"] extends TSchema ? Static<T[\"headers\"]> : Record<string, string>;\n  cookies: T[\"cookies\"] extends TSchema ? Static<T[\"cookies\"]> : Record<string, string>;\n};\n\n// ============= 中间件类型系统 =============\n\n/** 带类型标记的中间件 */\nexport interface TypedMiddleware<TContext extends object = object> {\n  (req: Request, next: (ctx?: TContext) => Promise<Response>): Response | Promise<Response>;\n  /** 类型标记（仅编译时使用） */\n  __context?: TContext;\n}\n\n/** 普通中间件（无类型注入） */\ntype PlainMiddleware = (req: Request, next: () => Promise<Response>) => Response | Promise<Response>;\n\n/** 任意中间件类型 */\ntype AnyMiddleware = TypedMiddleware<object> | PlainMiddleware;\n\n/** 从中间件提取上下文类型 */\ntype ExtractMiddlewareContext<T> = T extends TypedMiddleware<infer C> ? C : object;\n\n/** 合并中间件数组的上下文类型 */\ntype MergeMiddlewareContexts<T extends readonly unknown[]> =\n  T extends readonly [infer First, ...infer Rest]\n    ? ExtractMiddlewareContext<First> & MergeMiddlewareContexts<Rest>\n    : object;\n\n// ============= Handler 上下文 =============\n\n/** Handler 上下文（包含 schema 推断） */\nexport interface HandlerContext<TSchema extends RouteSchema = RouteSchema> {\n  req: Request;\n  body: InferSchemaType<TSchema>[\"body\"];\n  query: InferSchemaType<TSchema>[\"query\"];\n  params: InferSchemaType<TSchema>[\"params\"];\n  headers: InferSchemaType<TSchema>[\"headers\"];\n  cookies: InferSchemaType<TSchema>[\"cookies\"];\n}\n\n/** Handler 上下文（带中间件注入的额外类型） */\ntype HandlerContextWithExtra<TSchema extends RouteSchema, TExtra> =\n  HandlerContext<TSchema> & TExtra;\n\n// ============= 路由配置类型 =============\n\n/** HTTP 方法 */\ntype HTTPMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\" | \"OPTIONS\" | \"HEAD\";\n\n/** 叶子路由配置（有 method 和 handler） */\nexport interface LeafRouteConfig<\n  TMethod extends HTTPMethod = HTTPMethod,\n  TPath extends string = string,\n  TSchema extends RouteSchema = RouteSchema,\n  TReturn = unknown,\n  TMiddleware extends readonly AnyMiddleware[] = readonly AnyMiddleware[]\n> {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  readonly handler: (\n    ctx: HandlerContextWithExtra<TSchema, MergeMiddlewareContexts<TMiddleware>>\n  ) => TReturn | Promise<TReturn>;\n  readonly middleware?: TMiddleware;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}\n\n/** 嵌套路由配置（有 children，无 method 和 handler） */\ninterface NestedRouteConfig<\n  TPath extends string = string,\n  TMiddleware extends readonly AnyMiddleware[] = readonly AnyMiddleware[]\n> {\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly middleware?: TMiddleware;\n  readonly children: ReadonlyArray<RouteConfigResult>;\n}\n\n/** defineRoute 返回的类型 */\ntype RouteConfigResult =\n  | LeafRouteConfig<HTTPMethod, string, RouteSchema, unknown, readonly AnyMiddleware[]>\n  | NestedRouteConfig<string, readonly AnyMiddleware[]>;\n\n/** 处理后的扁平路由 */\nexport interface ProcessedRoute {\n  method: HTTPMethod;\n  path: string;\n  name?: string;\n  description?: string;\n  schema?: RouteSchema;\n  handler: (req: Request) => Promise<Response>;\n  middleware?: readonly AnyMiddleware[];\n  docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n  /** 允许任意扩展（兼容 Route 类型） */\n  [key: string]: unknown;\n}\n\n// ============= defineMiddleware =============\n\n/**\n * 定义带类型的中间件（函数式风格）\n *\n * 通过 next() 参数传递上下文，更符合函数式编程风格\n *\n * @example\n * ```typescript\n * type AuthContext = { user: { id: string; name: string } }\n *\n * const authMiddleware = defineMiddleware<AuthContext>((req, next) => {\n *   const user = getUserFromToken(req)\n *   return next({ user })  // 通过 next 传递上下文\n * })\n * ```\n */\nexport function defineMiddleware<TContext extends object = object>(\n  handler: (\n    req: Request,\n    next: (ctx?: TContext) => Promise<Response>\n  ) => Promise<Response>\n): TypedMiddleware<TContext> {\n  // 包装成标准中间件签名\n  const middleware = ((req: Request, originalNext: () => Promise<Response>) => {\n    // 包装 next，接收上下文参数并存储到 req.__locals\n    const nextWithContext = (ctx?: TContext): Promise<Response> => {\n      if (ctx) {\n        const target = req as unknown as { __locals?: object };\n        target.__locals = { ...(target.__locals || {}), ...ctx };\n      }\n      return originalNext();\n    };\n    return handler(req, nextWithContext);\n  }) as TypedMiddleware<TContext>;\n\n  return middleware;\n}\n\n// ============= 响应处理 =============\n\n/** 自动转换返回值为 Response */\nfunction autoResponse(result: unknown): Response {\n  if (result instanceof Response) return result;\n  if (result === null || result === undefined) return new Response(null, { status: 204 });\n  if (typeof result === \"string\") {\n    return new Response(result, { headers: { \"Content-Type\": \"text/plain; charset=utf-8\" } });\n  }\n  if (typeof result === \"number\" || typeof result === \"boolean\") {\n    return new Response(String(result), { headers: { \"Content-Type\": \"text/plain; charset=utf-8\" } });\n  }\n  if (typeof result === \"object\") {\n    const obj = result as Record<string, unknown>;\n    if (\"data\" in obj && (\"status\" in obj || \"headers\" in obj)) {\n      const { data, status = 200, headers = {} } = obj;\n      if (data === null || data === undefined) {\n        return new Response(null, { status: status === 200 ? 204 : (status as number), headers: headers as HeadersInit });\n      }\n      return json(data, status as number, headers as Record<string, string>);\n    }\n    return json(result);\n  }\n  return new Response(null, { status: 204 });\n}\n\n/** 创建包装后的 handler */\nfunction wrapHandler<TSchema extends RouteSchema>(\n  schema: TSchema | undefined,\n  userHandler: (ctx: HandlerContext<TSchema>) => unknown | Promise<unknown>\n): (req: Request) => Promise<Response> {\n  if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) {\n    precompileSchemas(schema);\n  }\n\n  return async (req: Request): Promise<Response> => {\n    try {\n      const query = parseQuery(req);\n      const headers = parseHeaders(req);\n      const cookies = parseCookies(req);\n      const params = ((req as unknown as Record<string, unknown>).params as Record<string, string>) || {};\n\n      let body: unknown = undefined;\n      if (req.method !== \"GET\" && req.method !== \"HEAD\") {\n        try {\n          body = await parseBody(req);\n        } catch {\n          // 忽略解析错误\n        }\n      }\n\n      const data = { body, query, params, headers, cookies };\n      if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) {\n        validateAllSchemas(schema, data);\n      }\n\n      // 获取中间件注入的上下文\n      const extraCtx = (req as unknown as { __locals?: unknown }).__locals || {};\n\n      const result = await userHandler({\n        req,\n        body: body as HandlerContext<TSchema>[\"body\"],\n        query: query as HandlerContext<TSchema>[\"query\"],\n        params: params as HandlerContext<TSchema>[\"params\"],\n        headers: headers as HandlerContext<TSchema>[\"headers\"],\n        cookies: cookies as HandlerContext<TSchema>[\"cookies\"],\n        ...extraCtx,\n      } as HandlerContext<TSchema>);\n\n      return autoResponse(result);\n    } catch (error) {\n      // 如果是 VafastError，重新抛出让错误处理中间件处理\n      if (error instanceof VafastError) {\n        throw error;\n      }\n      if (error instanceof Error && error.message.includes(\"验证失败\")) {\n        return json({ success: false, error: \"Validation Error\", message: error.message }, 400);\n      }\n      return json({ success: false, error: \"Internal Error\", message: error instanceof Error ? error.message : \"未知错误\" }, 500);\n    }\n  };\n}\n\n// ============= 判断路由类型 =============\n\n/** 判断是否为叶子路由 */\nfunction isLeafRoute(route: RouteConfigResult): route is LeafRouteConfig {\n  return \"method\" in route && \"handler\" in route;\n}\n\n/** 判断是否为嵌套路由 */\nfunction isNestedRoute(route: RouteConfigResult): route is NestedRouteConfig {\n  return \"children\" in route;\n}\n\n// ============= defineRoute 函数（支持重载） =============\n\n/**\n * 定义叶子路由（有 method 和 handler），支持中间件类型推断和显式上下文类型\n *\n * @example\n * ```typescript\n * // 方式1：通过中间件自动推断上下文\n * defineRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   middleware: [authMiddleware],\n *   handler: ({ user }) => { ... }  // user 来自 authMiddleware\n * })\n *\n * // 方式2：显式声明上下文类型（用于父级中间件注入的场景）\n * defineRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   context: {} as { userInfo: UserInfo },\n *   handler: ({ userInfo }) => { ... }  // userInfo 有类型\n * })\n * ```\n */\nexport function defineRoute<\n  const TSchema extends RouteSchema,\n  TReturn,\n  const TMiddleware extends readonly AnyMiddleware[],\n  TContext extends object = object,\n  TMethod extends HTTPMethod = HTTPMethod,\n  TPath extends string = string\n>(config: {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  /** 显式声明上下文类型（用于父级中间件注入的场景） */\n  readonly context?: TContext;\n  readonly handler: (\n    ctx: HandlerContextWithExtra<TSchema, TContext & MergeMiddlewareContexts<TMiddleware>>\n  ) => TReturn | Promise<TReturn>;\n  readonly middleware?: TMiddleware;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}): LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware>;\n\n/**\n * 定义嵌套路由（有 children），支持中间件类型推断\n */\nexport function defineRoute<\n  const TMiddleware extends readonly AnyMiddleware[],\n  TPath extends string = string\n>(config: {\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly middleware?: TMiddleware;\n  readonly children: ReadonlyArray<RouteConfigResult>;\n}): NestedRouteConfig<TPath, TMiddleware>;\n\n/**\n * defineRoute 实现\n */\nexport function defineRoute(config: {\n  readonly method?: HTTPMethod;\n  readonly path: string;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: RouteSchema;\n  readonly context?: object;\n  readonly handler?: (ctx: HandlerContext<RouteSchema>) => unknown | Promise<unknown>;\n  readonly middleware?: readonly AnyMiddleware[];\n  readonly children?: ReadonlyArray<RouteConfigResult>;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}): RouteConfigResult {\n  return config as RouteConfigResult;\n}\n\n// ============= withContext 工厂函数 =============\n\n/**\n * 创建带预设上下文类型的路由定义器\n *\n * 用于父级中间件注入上下文的场景，定义一次，多处复用\n *\n * @example\n * ```typescript\n * // 1. 在 middleware/index.ts 中定义\n * export const defineAuthRoute = withContext<{ userInfo: UserInfo }>()\n *\n * // 2. 在路由文件中使用\n * defineAuthRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   handler: ({ userInfo }) => {\n *     // userInfo 自动有类型！\n *     return { id: userInfo.id }\n *   }\n * })\n * ```\n */\nexport function withContext<TContext extends object>() {\n  return <\n    const TSchema extends RouteSchema,\n    TReturn,\n    const TMiddleware extends readonly AnyMiddleware[],\n    TMethod extends HTTPMethod = HTTPMethod,\n    TPath extends string = string\n  >(config: {\n    readonly method: TMethod;\n    readonly path: TPath;\n    readonly name?: string;\n    readonly description?: string;\n    readonly schema?: TSchema;\n    readonly handler: (\n      ctx: HandlerContextWithExtra<TSchema, TContext & MergeMiddlewareContexts<TMiddleware>>\n    ) => TReturn | Promise<TReturn>;\n    readonly middleware?: TMiddleware;\n    readonly docs?: {\n      tags?: string[];\n      security?: unknown[];\n      responses?: Record<string, unknown>;\n    };\n  }): LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware> => {\n    return config as LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware>;\n  };\n}\n\n// ============= 扁平化嵌套路由 =============\n\n/**\n * 递归扁平化路由，合并路径和中间件\n */\nfunction flattenRoutes(\n  routes: ReadonlyArray<RouteConfigResult>,\n  parentPath: string = \"\",\n  parentMiddleware: readonly AnyMiddleware[] = []\n): ProcessedRoute[] {\n  const result: ProcessedRoute[] = [];\n\n  for (const route of routes) {\n    const fullPath = parentPath + route.path;\n    const mergedMiddleware = [...parentMiddleware, ...(route.middleware || [])];\n\n    if (isLeafRoute(route)) {\n      result.push({\n        method: route.method,\n        path: fullPath,\n        name: route.name,\n        description: route.description,\n        schema: route.schema,\n        handler: wrapHandler(route.schema, route.handler as (ctx: HandlerContext<RouteSchema>) => unknown),\n        middleware: mergedMiddleware.length > 0 ? mergedMiddleware : undefined,\n        docs: route.docs,\n      });\n    } else if (isNestedRoute(route)) {\n      result.push(...flattenRoutes(route.children, fullPath, mergedMiddleware));\n    }\n  }\n\n  return result;\n}\n\n// ============= defineRoutes 函数 =============\n\n/**\n * 定义路由数组，支持嵌套路由\n */\nexport function defineRoutes(routes: ReadonlyArray<RouteConfigResult>): ProcessedRoute[] {\n  return flattenRoutes(routes);\n}\n\n// ============= 用于 API Client 的类型推断 =============\n\n/** 可推断的路由类型（供 vafast-api-client 使用） */\nexport type InferableRoute<\n  TMethod extends string = string,\n  TPath extends string = string,\n  TReturn = unknown,\n  TSchema extends RouteSchema = RouteSchema\n> = {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  readonly handler: {\n    __returnType: TReturn;\n    __schema: TSchema;\n  };\n  readonly middleware?: ReadonlyArray<AnyMiddleware>;\n};\n"],"mappings":"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"}
+{"version":3,"file":"defineRoute.mjs","names":[],"sources":["../src/defineRoute.ts"],"sourcesContent":["/**\n * 路由定义 - Schema 在路由级别定义，支持嵌套路由和中间件类型推断\n *\n * @example\n * ```typescript\n * // 定义带类型的中间件（函数式风格，通过 next 传递上下文）\n * const authMiddleware = defineMiddleware<{ user: User }>((req, next) => {\n *   const user = getUser(req)\n *   return next({ user })  // 通过 next 参数传递上下文\n * })\n *\n * // 路由自动推断中间件注入的类型\n * const routes = defineRoutes([\n *   defineRoute({\n *     path: '/api',\n *     middleware: [authMiddleware],\n *     children: [\n *       defineRoute({\n *         method: 'GET',\n *         path: '/profile',\n *         handler: ({ user }) => ({ name: user.name })  // ✅ user 有类型\n *       })\n *     ]\n *   })\n * ])\n * ```\n */\n\nimport type { TSchema, Static } from \"@sinclair/typebox\";\nimport { parseBody, parseQuery, parseHeaders, parseCookies } from \"./utils/parsers\";\nimport { validateAllSchemas, precompileSchemas } from \"./utils/validators/validators\";\nimport { json } from \"./utils/response\";\nimport { VafastError } from \"./middleware\";\n\n// ============= Schema 类型 =============\n\n/** 路由 Schema 配置 */\nexport interface RouteSchema {\n  body?: TSchema;\n  query?: TSchema;\n  params?: TSchema;\n  headers?: TSchema;\n  cookies?: TSchema;\n}\n\n/** 从 Schema 推断类型 */\ntype InferSchemaType<T extends RouteSchema> = {\n  body: T[\"body\"] extends TSchema ? Static<T[\"body\"]> : unknown;\n  query: T[\"query\"] extends TSchema ? Static<T[\"query\"]> : Record<string, string>;\n  params: T[\"params\"] extends TSchema ? Static<T[\"params\"]> : Record<string, string>;\n  headers: T[\"headers\"] extends TSchema ? Static<T[\"headers\"]> : Record<string, string>;\n  cookies: T[\"cookies\"] extends TSchema ? Static<T[\"cookies\"]> : Record<string, string>;\n};\n\n// ============= 中间件类型系统 =============\n\n/** 带类型标记的中间件 */\nexport interface TypedMiddleware<TContext extends object = object> {\n  (req: Request, next: (ctx?: TContext) => Promise<Response>): Response | Promise<Response>;\n  /** 类型标记（仅编译时使用） */\n  __context?: TContext;\n}\n\n/** 普通中间件（无类型注入） */\ntype PlainMiddleware = (req: Request, next: () => Promise<Response>) => Response | Promise<Response>;\n\n/** 任意中间件类型 */\ntype AnyMiddleware = TypedMiddleware<object> | PlainMiddleware;\n\n/** 从中间件提取上下文类型 */\ntype ExtractMiddlewareContext<T> = T extends TypedMiddleware<infer C> ? C : object;\n\n/** 合并中间件数组的上下文类型 */\ntype MergeMiddlewareContexts<T extends readonly unknown[]> =\n  T extends readonly [infer First, ...infer Rest]\n    ? ExtractMiddlewareContext<First> & MergeMiddlewareContexts<Rest>\n    : object;\n\n// ============= Handler 上下文 =============\n\n/** Handler 上下文（包含 schema 推断） */\nexport interface HandlerContext<TSchema extends RouteSchema = RouteSchema> {\n  req: Request;\n  body: InferSchemaType<TSchema>[\"body\"];\n  query: InferSchemaType<TSchema>[\"query\"];\n  params: InferSchemaType<TSchema>[\"params\"];\n  headers: InferSchemaType<TSchema>[\"headers\"];\n  cookies: InferSchemaType<TSchema>[\"cookies\"];\n}\n\n/** Handler 上下文（带中间件注入的额外类型） */\ntype HandlerContextWithExtra<TSchema extends RouteSchema, TExtra> =\n  HandlerContext<TSchema> & TExtra;\n\n// ============= 路由配置类型 =============\n\n/** HTTP 方法 */\ntype HTTPMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\" | \"OPTIONS\" | \"HEAD\";\n\n/** 叶子路由配置（有 method 和 handler） */\nexport interface LeafRouteConfig<\n  TMethod extends HTTPMethod = HTTPMethod,\n  TPath extends string = string,\n  TSchema extends RouteSchema = RouteSchema,\n  TReturn = unknown,\n  TMiddleware extends readonly AnyMiddleware[] = readonly AnyMiddleware[]\n> {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  readonly handler: (\n    ctx: HandlerContextWithExtra<TSchema, MergeMiddlewareContexts<TMiddleware>>\n  ) => TReturn | Promise<TReturn>;\n  readonly middleware?: TMiddleware;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}\n\n/** 嵌套路由配置（有 children，无 method 和 handler） */\ninterface NestedRouteConfig<\n  TPath extends string = string,\n  TMiddleware extends readonly AnyMiddleware[] = readonly AnyMiddleware[]\n> {\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly middleware?: TMiddleware;\n  readonly children: ReadonlyArray<RouteConfigResult>;\n}\n\n/** defineRoute 返回的类型 */\ntype RouteConfigResult =\n  | LeafRouteConfig<HTTPMethod, string, RouteSchema, unknown, readonly AnyMiddleware[]>\n  | NestedRouteConfig<string, readonly AnyMiddleware[]>;\n\n/** 处理后的扁平路由 */\nexport interface ProcessedRoute {\n  method: HTTPMethod;\n  path: string;\n  name?: string;\n  description?: string;\n  schema?: RouteSchema;\n  handler: (req: Request) => Promise<Response>;\n  middleware?: readonly AnyMiddleware[];\n  docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n  /** 允许任意扩展（兼容 Route 类型） */\n  [key: string]: unknown;\n}\n\n// ============= defineMiddleware =============\n\n/**\n * 定义带类型的中间件（函数式风格）\n *\n * 通过 next() 参数传递上下文，更符合函数式编程风格\n *\n * @example\n * ```typescript\n * type AuthContext = { user: { id: string; name: string } }\n *\n * const authMiddleware = defineMiddleware<AuthContext>((req, next) => {\n *   const user = getUserFromToken(req)\n *   return next({ user })  // 通过 next 传递上下文\n * })\n * ```\n */\nexport function defineMiddleware<TContext extends object = object>(\n  handler: (\n    req: Request,\n    next: (ctx?: TContext) => Promise<Response>\n  ) => Promise<Response>\n): TypedMiddleware<TContext> {\n  // 包装成标准中间件签名\n  const middleware = ((req: Request, originalNext: () => Promise<Response>) => {\n    // 包装 next，接收上下文参数并存储到 req.__locals\n    const nextWithContext = (ctx?: TContext): Promise<Response> => {\n      if (ctx) {\n        const target = req as unknown as { __locals?: object };\n        target.__locals = { ...(target.__locals || {}), ...ctx };\n      }\n      return originalNext();\n    };\n    return handler(req, nextWithContext);\n  }) as TypedMiddleware<TContext>;\n\n  return middleware;\n}\n\n// ============= 响应处理 =============\n\n/** 自动转换返回值为 Response */\nfunction autoResponse(result: unknown): Response {\n  if (result instanceof Response) return result;\n  if (result === null || result === undefined) return new Response(null, { status: 204 });\n  if (typeof result === \"string\") {\n    return new Response(result, { headers: { \"Content-Type\": \"text/plain; charset=utf-8\" } });\n  }\n  if (typeof result === \"number\" || typeof result === \"boolean\") {\n    return new Response(String(result), { headers: { \"Content-Type\": \"text/plain; charset=utf-8\" } });\n  }\n  if (typeof result === \"object\") {\n    const obj = result as Record<string, unknown>;\n    if (\"data\" in obj && (\"status\" in obj || \"headers\" in obj)) {\n      const { data, status = 200, headers = {} } = obj;\n      if (data === null || data === undefined) {\n        return new Response(null, { status: status === 200 ? 204 : (status as number), headers: headers as HeadersInit });\n      }\n      return json(data, status as number, headers as Record<string, string>);\n    }\n    return json(result);\n  }\n  return new Response(null, { status: 204 });\n}\n\n/** 创建包装后的 handler */\nfunction wrapHandler<TSchema extends RouteSchema>(\n  schema: TSchema | undefined,\n  userHandler: (ctx: HandlerContext<TSchema>) => unknown | Promise<unknown>\n): (req: Request) => Promise<Response> {\n  if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) {\n    precompileSchemas(schema);\n  }\n\n  return async (req: Request): Promise<Response> => {\n    try {\n      const query = parseQuery(req);\n      const headers = parseHeaders(req);\n      const cookies = parseCookies(req);\n      const params = ((req as unknown as Record<string, unknown>).params as Record<string, string>) || {};\n\n      let body: unknown = undefined;\n      if (req.method !== \"GET\" && req.method !== \"HEAD\") {\n        try {\n          body = await parseBody(req);\n        } catch {\n          // 忽略解析错误\n        }\n      }\n\n      const data = { body, query, params, headers, cookies };\n      if (schema && (schema.body || schema.query || schema.params || schema.headers || schema.cookies)) {\n        validateAllSchemas(schema, data);\n      }\n\n      // 获取中间件注入的上下文\n      const extraCtx = (req as unknown as { __locals?: unknown }).__locals || {};\n\n      const result = await userHandler({\n        req,\n        body: body as HandlerContext<TSchema>[\"body\"],\n        query: query as HandlerContext<TSchema>[\"query\"],\n        params: params as HandlerContext<TSchema>[\"params\"],\n        headers: headers as HandlerContext<TSchema>[\"headers\"],\n        cookies: cookies as HandlerContext<TSchema>[\"cookies\"],\n        ...extraCtx,\n      } as HandlerContext<TSchema>);\n\n      return autoResponse(result);\n    } catch (error) {\n      // 如果是 VafastError，重新抛出让错误处理中间件处理\n      if (error instanceof VafastError) {\n        throw error;\n      }\n      if (error instanceof Error && error.message.includes(\"验证失败\")) {\n        return json({ success: false, error: \"Validation Error\", message: error.message }, 400);\n      }\n      return json({ success: false, error: \"Internal Error\", message: error instanceof Error ? error.message : \"未知错误\" }, 500);\n    }\n  };\n}\n\n// ============= 判断路由类型 =============\n\n/** 判断是否为叶子路由 */\nfunction isLeafRoute(route: RouteConfigResult): route is LeafRouteConfig {\n  return \"method\" in route && \"handler\" in route;\n}\n\n/** 判断是否为嵌套路由 */\nfunction isNestedRoute(route: RouteConfigResult): route is NestedRouteConfig {\n  return \"children\" in route;\n}\n\n// ============= defineRoute 函数（支持重载） =============\n\n/**\n * 定义叶子路由（有 method 和 handler），支持中间件类型推断和显式上下文类型\n *\n * @example\n * ```typescript\n * // 方式1：通过中间件自动推断上下文\n * defineRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   middleware: [authMiddleware],\n *   handler: ({ user }) => { ... }  // user 来自 authMiddleware\n * })\n *\n * // 方式2：显式声明上下文类型（用于父级中间件注入的场景）\n * defineRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   context: {} as { userInfo: UserInfo },\n *   handler: ({ userInfo }) => { ... }  // userInfo 有类型\n * })\n * ```\n */\nexport function defineRoute<\n  const TSchema extends RouteSchema,\n  TReturn,\n  const TMiddleware extends readonly AnyMiddleware[],\n  TContext extends object = object,\n  TMethod extends HTTPMethod = HTTPMethod,\n  TPath extends string = string\n>(config: {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  /** 显式声明上下文类型（用于父级中间件注入的场景） */\n  readonly context?: TContext;\n  readonly handler: (\n    ctx: HandlerContextWithExtra<TSchema, TContext & MergeMiddlewareContexts<TMiddleware>>\n  ) => TReturn | Promise<TReturn>;\n  readonly middleware?: TMiddleware;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}): LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware>;\n\n/**\n * 定义嵌套路由（有 children），支持中间件类型推断\n */\nexport function defineRoute<\n  const TMiddleware extends readonly AnyMiddleware[],\n  TPath extends string = string\n>(config: {\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly middleware?: TMiddleware;\n  readonly children: ReadonlyArray<RouteConfigResult>;\n}): NestedRouteConfig<TPath, TMiddleware>;\n\n/**\n * defineRoute 实现\n */\nexport function defineRoute(config: {\n  readonly method?: HTTPMethod;\n  readonly path: string;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: RouteSchema;\n  readonly context?: object;\n  readonly handler?: (ctx: HandlerContext<RouteSchema>) => unknown | Promise<unknown>;\n  readonly middleware?: readonly AnyMiddleware[];\n  readonly children?: ReadonlyArray<RouteConfigResult>;\n  readonly docs?: {\n    tags?: string[];\n    security?: unknown[];\n    responses?: Record<string, unknown>;\n  };\n}): RouteConfigResult {\n  return config as RouteConfigResult;\n}\n\n// ============= withContext 工厂函数 =============\n\n/**\n * 创建带预设上下文类型的路由定义器\n *\n * 用于父级中间件注入上下文的场景，定义一次，多处复用\n *\n * @example\n * ```typescript\n * // 1. 在 middleware/index.ts 中定义\n * export const defineAuthRoute = withContext<{ userInfo: UserInfo }>()\n *\n * // 2. 在路由文件中使用\n * defineAuthRoute({\n *   method: 'GET',\n *   path: '/profile',\n *   handler: ({ userInfo }) => {\n *     // userInfo 自动有类型！\n *     return { id: userInfo.id }\n *   }\n * })\n * ```\n */\nexport function withContext<TContext extends object>() {\n  return <\n    const TSchema extends RouteSchema,\n    TReturn,\n    const TMiddleware extends readonly AnyMiddleware[],\n    TMethod extends HTTPMethod = HTTPMethod,\n    TPath extends string = string\n  >(config: {\n    readonly method: TMethod;\n    readonly path: TPath;\n    readonly name?: string;\n    readonly description?: string;\n    readonly schema?: TSchema;\n    readonly handler: (\n      ctx: HandlerContextWithExtra<TSchema, TContext & MergeMiddlewareContexts<TMiddleware>>\n    ) => TReturn | Promise<TReturn>;\n    readonly middleware?: TMiddleware;\n    readonly docs?: {\n      tags?: string[];\n      security?: unknown[];\n      responses?: Record<string, unknown>;\n    };\n  }): LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware> => {\n    return config as LeafRouteConfig<TMethod, TPath, TSchema, TReturn, TMiddleware>;\n  };\n}\n\n// ============= 扁平化嵌套路由 =============\n\n/**\n * 递归扁平化路由，合并路径和中间件\n */\nfunction flattenRoutes(\n  routes: ReadonlyArray<RouteConfigResult>,\n  parentPath: string = \"\",\n  parentMiddleware: readonly AnyMiddleware[] = []\n): ProcessedRoute[] {\n  const result: ProcessedRoute[] = [];\n\n  for (const route of routes) {\n    const fullPath = parentPath + route.path;\n    const mergedMiddleware = [...parentMiddleware, ...(route.middleware || [])];\n\n    if (isLeafRoute(route)) {\n      result.push({\n        method: route.method,\n        path: fullPath,\n        name: route.name,\n        description: route.description,\n        schema: route.schema,\n        handler: wrapHandler(route.schema, route.handler as (ctx: HandlerContext<RouteSchema>) => unknown),\n        middleware: mergedMiddleware.length > 0 ? mergedMiddleware : undefined,\n        docs: route.docs,\n      });\n    } else if (isNestedRoute(route)) {\n      result.push(...flattenRoutes(route.children, fullPath, mergedMiddleware));\n    }\n  }\n\n  return result;\n}\n\n// ============= defineRoutes 函数 =============\n\n/** 带原始类型信息的路由数组 */\nexport type RoutesWithSource<T extends readonly RouteConfigResult[]> = ProcessedRoute[] & { __source: T };\n\n/**\n * 定义路由数组，支持嵌套路由\n * \n * 使用 `const T` 泛型自动保留字面量类型，无需手动添加 `as const`\n * \n * @example\n * ```typescript\n * const routes = defineRoutes([\n *   defineRoute({ method: 'GET', path: '/users', handler: ... }),\n *   defineRoute({ method: 'POST', path: '/users', handler: ... }),\n * ])\n * \n * // 类型推断自动工作，无需 as const\n * type Api = InferEden<typeof routes>\n * ```\n */\nexport function defineRoutes<const T extends readonly RouteConfigResult[]>(\n  routes: T\n): RoutesWithSource<T> {\n  const processed = flattenRoutes(routes);\n  // 附加原始类型信息（仅用于类型推断，运行时不使用）\n  return Object.assign(processed, { __source: routes }) as RoutesWithSource<T>;\n}\n\n// ============= 用于 API Client 的类型推断 =============\n\n/** 可推断的路由类型（供 vafast-api-client 使用） */\nexport type InferableRoute<\n  TMethod extends string = string,\n  TPath extends string = string,\n  TReturn = unknown,\n  TSchema extends RouteSchema = RouteSchema\n> = {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schema?: TSchema;\n  readonly handler: {\n    __returnType: TReturn;\n    __schema: TSchema;\n  };\n  readonly middleware?: ReadonlyArray<AnyMiddleware>;\n};\n"],"mappings":"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"}

package/dist/{index-DCJOWsRE.d.mts → index-XcXGKQqt.d.mts}

@@ -1,6 +1,6 @@
-import { i as ProcessedRoute } from "./defineRoute-BNqVD0_t.mjs";
+import { i as ProcessedRoute } from "./defineRoute-FhAN4ivP.mjs";
 import { r as NestedComponentRoute, t as ComponentRoute } from "./component-route-Di7R40-2.mjs";
-import { t as Server } from "./server-Bicf_7Hx.mjs";
+import { t as Server } from "./server-8X5Hgu7h.mjs";
 import { t as ComponentServer } from "./component-server-fR4UV6Jq.mjs";
 
 //#region src/server/server-factory.d.ts
@@ -45,4 +45,4 @@ declare class ServerFactory {
 }
 //#endregion
 export { ServerFactory as t };
-//# sourceMappingURL=index-DCJOWsRE.d.mts.map
+//# sourceMappingURL=index-XcXGKQqt.d.mts.map

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { a as RouteSchema, c as defineRoute, i as ProcessedRoute, l as defineRoutes, n as InferableRoute, o as TypedMiddleware, r as LeafRouteConfig, s as defineMiddleware, t as HandlerContext, u as withContext } from "./defineRoute-BNqVD0_t.mjs";
+import { a as RouteSchema, c as defineMiddleware, d as withContext, i as ProcessedRoute, l as defineRoute, n as InferableRoute, o as RoutesWithSource, r as LeafRouteConfig, s as TypedMiddleware, t as HandlerContext, u as defineRoutes } from "./defineRoute-FhAN4ivP.mjs";
 import { i as ResponseBody, n as Method, r as Middleware, t as Handler } from "./types-B8Z3cMtZ.mjs";
 import { n as FlattenedComponentRoute, r as NestedComponentRoute, t as ComponentRoute } from "./component-route-Di7R40-2.mjs";
 import { t as BaseServer } from "./base-server-Contwrlf.mjs";
-import { t as Server } from "./server-Bicf_7Hx.mjs";
+import { t as Server } from "./server-8X5Hgu7h.mjs";
 import { t as DependencyManager } from "./dependency-manager-DIN9X0Gj.mjs";
 import { t as ComponentServer } from "./component-server-fR4UV6Jq.mjs";
-import { t as ServerFactory } from "./index-DCJOWsRE.mjs";
+import { t as ServerFactory } from "./index-XcXGKQqt.mjs";
 import { n as composeMiddleware, t as VafastError } from "./middleware-BR-R4p0M.mjs";
 import { a as parseBody, c as parseCookiesFast, d as parseHeaders, f as parseQuery, i as getHeader, p as parseQueryFast, r as getCookie, s as parseCookies } from "./parsers-8hIAx0OV.mjs";
 import { c as text, i as json, n as err, o as redirect, r as html, s as stream, t as empty } from "./response-BNLzz4Tq.mjs";
@@ -14,12 +14,12 @@ import { n as base64urlEncode, t as base64urlDecode } from "./base64url-DNUGwekK
 import { t as HtmlRenderer } from "./html-renderer-DhQxRuyi.mjs";
 import { a as ValidationError, c as getValidatorCacheStats, d as validateFast, f as validateSchema, l as precompileSchemas, o as ValidationResult, p as validateSchemaOrThrow, s as createValidator, t as SchemaConfig, u as validateAllSchemas } from "./validators-BFC6S_fr.mjs";
 import { i as registerFormats, n as hasFormat, r as registerFormat, t as Patterns } from "./formats-DDDSFWP0.mjs";
-import { a as createSSEHandler, i as SSEMarker, r as SSEHandler, t as SSEEvent } from "./sse-DYuFPif9.mjs";
-import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "./route-registry-DZv4vAjT.mjs";
+import { a as createSSEHandler, i as SSEMarker, r as SSEHandler, t as SSEEvent } from "./sse-DyI21Jqk.mjs";
+import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "./route-registry-YIco7opr.mjs";
 import { n as getApiSpec, t as generateAITools } from "./contract-BL3JflJ7.mjs";
 import "./utils/index.mjs";
 import { normalizePath } from "./router.mjs";
 import { i as ServeResult, o as serve, r as ServeOptions, t as FetchHandler } from "./serve-DlzxgOhz.mjs";
 import "./serve.mjs";
 import { FormatRegistry, Type } from "@sinclair/typebox";
-export { BaseServer, ComponentRoute, ComponentServer, DependencyManager, type FetchHandler, FlattenedComponentRoute, FormatRegistry, Handler, HandlerContext, HtmlRenderer, InferableRoute, LeafRouteConfig, Method, Middleware, NestedComponentRoute, Patterns, ProcessedRoute, ResponseBody, RouteMeta, RouteRegistry, RouteSchema, SSEEvent, SSEHandler, SSEMarker, SchemaConfig, type ServeOptions, type ServeResult, Server, ServerFactory, Type, TypedMiddleware, VafastError, ValidationError, ValidationResult, base64urlDecode, base64urlEncode, composeMiddleware, createRouteRegistry, createSSEHandler, createValidator, defineMiddleware, defineRoute, defineRoutes, empty, err, filterRoutes, generateAITools, getAllRoutes, getApiSpec, getCookie, getHeader, getRoute, getRouteRegistry, getRoutesByMethod, getValidatorCacheStats, goAwait, hasFormat, html, json, normalizePath, parseBody, parseCookies, parseCookiesFast, parseHeaders, parseQuery, parseQueryFast, precompileSchemas, redirect, registerFormat, registerFormats, serve, stream, text, validateAllSchemas, validateFast, validateSchema, validateSchemaOrThrow, withContext };
+export { BaseServer, ComponentRoute, ComponentServer, DependencyManager, type FetchHandler, FlattenedComponentRoute, FormatRegistry, Handler, HandlerContext, HtmlRenderer, InferableRoute, LeafRouteConfig, Method, Middleware, NestedComponentRoute, Patterns, ProcessedRoute, ResponseBody, RouteMeta, RouteRegistry, RouteSchema, RoutesWithSource, SSEEvent, SSEHandler, SSEMarker, SchemaConfig, type ServeOptions, type ServeResult, Server, ServerFactory, Type, TypedMiddleware, VafastError, ValidationError, ValidationResult, base64urlDecode, base64urlEncode, composeMiddleware, createRouteRegistry, createSSEHandler, createValidator, defineMiddleware, defineRoute, defineRoutes, empty, err, filterRoutes, generateAITools, getAllRoutes, getApiSpec, getCookie, getHeader, getRoute, getRouteRegistry, getRoutesByMethod, getValidatorCacheStats, goAwait, hasFormat, html, json, normalizePath, parseBody, parseCookies, parseCookiesFast, parseHeaders, parseQuery, parseQueryFast, precompileSchemas, redirect, registerFormat, registerFormats, serve, stream, text, validateAllSchemas, validateFast, validateSchema, validateSchemaOrThrow, withContext };

package/dist/monitoring/index.d.mts

@@ -1,5 +1,5 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import "../server-Bicf_7Hx.mjs";
-import "../index-DCJOWsRE.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import "../server-8X5Hgu7h.mjs";
+import "../index-XcXGKQqt.mjs";
 import { MemoryInfo, MonitoredServer, MonitoringConfig, MonitoringMetrics, MonitoringStatus, PathStats, StatusCodeDistribution, TimeWindowStats, createMonitoredServer, withMonitoring } from "./native-monitor.mjs";
 export { type MemoryInfo, type MonitoredServer, type MonitoringConfig, type MonitoringMetrics, type MonitoringStatus, type PathStats, type StatusCodeDistribution, type TimeWindowStats, createMonitoredServer, withMonitoring };

package/dist/monitoring/native-monitor.d.mts

@@ -1,6 +1,6 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import { t as Server } from "../server-Bicf_7Hx.mjs";
-import "../index-DCJOWsRE.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import { t as Server } from "../server-8X5Hgu7h.mjs";
+import "../index-XcXGKQqt.mjs";
 
 //#region src/monitoring/native-monitor.d.ts
 

package/dist/{route-registry-DZv4vAjT.d.mts → route-registry-YIco7opr.d.mts}

@@ -1,4 +1,4 @@
-import { a as RouteSchema, i as ProcessedRoute } from "./defineRoute-BNqVD0_t.mjs";
+import { a as RouteSchema, i as ProcessedRoute } from "./defineRoute-FhAN4ivP.mjs";
 import { n as Method } from "./types-B8Z3cMtZ.mjs";
 
 //#region src/utils/route-registry.d.ts
@@ -187,4 +187,4 @@ declare function filterRoutes<K extends string>(field: K): (RouteMeta & Record<K
 declare function getRoutesByMethod(method: string): RouteMeta[];
 //#endregion
 export { getAllRoutes as a, getRoutesByMethod as c, filterRoutes as i, setGlobalRegistry as l, RouteRegistry as n, getRoute as o, createRouteRegistry as r, getRouteRegistry as s, RouteMeta as t };
-//# sourceMappingURL=route-registry-DZv4vAjT.d.mts.map
+//# sourceMappingURL=route-registry-YIco7opr.d.mts.map

package/dist/server/index.d.mts

@@ -1,6 +1,6 @@
-import "../defineRoute-BNqVD0_t.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
 import { t as BaseServer } from "../base-server-Contwrlf.mjs";
-import { t as Server } from "../server-Bicf_7Hx.mjs";
+import { t as Server } from "../server-8X5Hgu7h.mjs";
 import { t as ComponentServer } from "../component-server-fR4UV6Jq.mjs";
-import { t as ServerFactory } from "../index-DCJOWsRE.mjs";
+import { t as ServerFactory } from "../index-XcXGKQqt.mjs";
 export { BaseServer, ComponentServer, Server, ServerFactory };

package/dist/server/server-factory.d.mts

@@ -1,4 +1,4 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import "../server-Bicf_7Hx.mjs";
-import { t as ServerFactory } from "../index-DCJOWsRE.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import "../server-8X5Hgu7h.mjs";
+import { t as ServerFactory } from "../index-XcXGKQqt.mjs";
 export { ServerFactory };

package/dist/server/server.d.mts

@@ -1,3 +1,3 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import { t as Server } from "../server-Bicf_7Hx.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import { t as Server } from "../server-8X5Hgu7h.mjs";
 export { Server };

package/dist/{server-Bicf_7Hx.d.mts → server-8X5Hgu7h.d.mts}

@@ -1,4 +1,4 @@
-import { i as ProcessedRoute } from "./defineRoute-BNqVD0_t.mjs";
+import { i as ProcessedRoute } from "./defineRoute-FhAN4ivP.mjs";
 import { n as Method } from "./types-B8Z3cMtZ.mjs";
 import { t as BaseServer } from "./base-server-Contwrlf.mjs";
 
@@ -45,4 +45,4 @@ declare class Server extends BaseServer {
 }
 //#endregion
 export { Server as t };
-//# sourceMappingURL=server-Bicf_7Hx.d.mts.map
+//# sourceMappingURL=server-8X5Hgu7h.d.mts.map

package/dist/{sse-DYuFPif9.d.mts → sse-DyI21Jqk.d.mts}

@@ -1,4 +1,4 @@
-import { a as RouteSchema, t as HandlerContext } from "./defineRoute-BNqVD0_t.mjs";
+import { a as RouteSchema, t as HandlerContext } from "./defineRoute-FhAN4ivP.mjs";
 
 //#region src/utils/sse.d.ts
 
@@ -60,4 +60,4 @@ declare function createSSEHandler<const T extends RouteSchema>(schema: T, genera
 declare function createSSEHandler(generator: SSEGenerator<RouteSchema>): SSEHandler<RouteSchema>;
 //#endregion
 export { createSSEHandler as a, SSEMarker as i, SSEGenerator as n, SSEHandler as r, SSEEvent as t };
-//# sourceMappingURL=sse-DYuFPif9.d.mts.map
+//# sourceMappingURL=sse-DyI21Jqk.d.mts.map

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-import "../defineRoute-BNqVD0_t.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
 import { t as DependencyManager } from "../dependency-manager-DIN9X0Gj.mjs";
 import { a as parseBody, c as parseCookiesFast, d as parseHeaders, f as parseQuery, i as getHeader, p as parseQueryFast, r as getCookie, s as parseCookies } from "../parsers-8hIAx0OV.mjs";
 import { c as text, i as json, n as err, o as redirect, r as html, s as stream, t as empty } from "../response-BNLzz4Tq.mjs";
@@ -7,7 +7,7 @@ import { n as base64urlEncode, t as base64urlDecode } from "../base64url-DNUGwek
 import { t as HtmlRenderer } from "../html-renderer-DhQxRuyi.mjs";
 import { a as ValidationError, c as getValidatorCacheStats, d as validateFast, f as validateSchema, l as precompileSchemas, o as ValidationResult, p as validateSchemaOrThrow, s as createValidator, t as SchemaConfig, u as validateAllSchemas } from "../validators-BFC6S_fr.mjs";
 import { i as registerFormats, n as hasFormat, r as registerFormat, t as Patterns } from "../formats-DDDSFWP0.mjs";
-import { a as createSSEHandler, i as SSEMarker, r as SSEHandler, t as SSEEvent } from "../sse-DYuFPif9.mjs";
-import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "../route-registry-DZv4vAjT.mjs";
+import { a as createSSEHandler, i as SSEMarker, r as SSEHandler, t as SSEEvent } from "../sse-DyI21Jqk.mjs";
+import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "../route-registry-YIco7opr.mjs";
 import { n as getApiSpec, t as generateAITools } from "../contract-BL3JflJ7.mjs";
 export { DependencyManager, HtmlRenderer, Patterns, type RouteMeta, RouteRegistry, type SSEEvent, type SSEHandler, type SSEMarker, type SchemaConfig, type ValidationError, type ValidationResult, base64urlDecode, base64urlEncode, createRouteRegistry, createSSEHandler, createValidator, empty, err, filterRoutes, generateAITools, getAllRoutes, getApiSpec, getCookie, getHeader, getRoute, getRouteRegistry, getRoutesByMethod, getValidatorCacheStats, goAwait, hasFormat, html, json, parseBody, parseCookies, parseCookiesFast, parseHeaders, parseQuery, parseQueryFast, precompileSchemas, redirect, registerFormat, registerFormats, stream, text, validateAllSchemas, validateFast, validateSchema, validateSchemaOrThrow };

package/dist/utils/route-registry.d.mts

@@ -1,3 +1,3 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, l as setGlobalRegistry, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "../route-registry-DZv4vAjT.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import { a as getAllRoutes, c as getRoutesByMethod, i as filterRoutes, l as setGlobalRegistry, n as RouteRegistry, o as getRoute, r as createRouteRegistry, s as getRouteRegistry, t as RouteMeta } from "../route-registry-YIco7opr.mjs";
 export { RouteMeta, RouteRegistry, createRouteRegistry, filterRoutes, getAllRoutes, getRoute, getRouteRegistry, getRoutesByMethod, setGlobalRegistry };

package/dist/utils/sse.d.mts

@@ -1,3 +1,3 @@
-import "../defineRoute-BNqVD0_t.mjs";
-import { a as createSSEHandler, i as SSEMarker, n as SSEGenerator, r as SSEHandler, t as SSEEvent } from "../sse-DYuFPif9.mjs";
+import "../defineRoute-FhAN4ivP.mjs";
+import { a as createSSEHandler, i as SSEMarker, n as SSEGenerator, r as SSEHandler, t as SSEEvent } from "../sse-DyI21Jqk.mjs";
 export { SSEEvent, SSEGenerator, SSEHandler, SSEMarker, createSSEHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vafast",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "极简结构化Web框架，支持 Bun 和 Node.js。Go风格，函数优先。",
   "type": "module",
   "repository": {