vafast 0.3.11 → 0.4.0

package/README.md

@@ -507,6 +507,67 @@ server.compile(); // 预编译所有路由的处理链
 
 **性能效果：1000 次请求仅需 ~4ms，平均每次 0.004ms**
 
+### 路由注册表 (RouteRegistry)
+
+Vafast 提供 `RouteRegistry` 用于路由元信息的收集和查询，适用于 API 文档生成、Webhook 事件注册、权限检查等场景：
+
+```typescript
+import { Server, createRouteRegistry } from 'vafast';
+import type { Route } from 'vafast';
+
+// 定义带扩展字段的路由
+const routes: Route[] = [
+  {
+    method: 'POST',
+    path: '/auth/signIn',
+    handler: signInHandler,
+    name: '用户登录',                    // 扩展字段
+    description: '用户通过邮箱密码登录',   // 扩展字段
+    webhook: { eventKey: 'auth.signIn' }, // 自定义扩展
+  },
+  {
+    method: 'GET',
+    path: '/users',
+    handler: getUsersHandler,
+    permission: 'users.read',            // 自定义扩展
+  },
+];
+
+const server = new Server(routes);
+
+// 创建路由注册表
+const registry = createRouteRegistry(server.getRoutesWithMeta());
+
+// 查询路由
+const route = registry.get('POST', '/auth/signIn');
+console.log(route?.name);  // '用户登录'
+
+// 按分类获取
+const authRoutes = registry.getByCategory('auth');
+
+// 筛选有特定字段的路由
+const webhookRoutes = registry.filter('webhook');
+const permissionRoutes = registry.filter('permission');
+
+// 获取所有分类
+const categories = registry.getCategories();  // ['auth', 'users']
+```
+
+**完整 API：**
+
+| 方法 | 说明 |
+|------|------|
+| `getAll()` | 获取所有路由元信息 |
+| `get(method, path)` | 按 method+path 查询 |
+| `has(method, path)` | 检查路由是否存在 |
+| `getByCategory(category)` | 按分类获取路由 |
+| `getCategories()` | 获取所有分类 |
+| `filter(field)` | 筛选有特定字段的路由 |
+| `filterBy(predicate)` | 自定义条件筛选 |
+| `forEach(callback)` | 遍历所有路由 |
+| `map(callback)` | 映射所有路由 |
+| `size` | 路由数量 |
+
 ## 🔧 运行时支持
 
 ### Bun

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { DependencyManager } from './utils/dependency-manager.js';
 export { SchemaConfig, ValidationError, ValidationResult, createValidator, getValidatorCacheStats, precompileSchemas, validateAllSchemas, validateFast, validateSchema, validateSchemaOrThrow } from './utils/validators/validators.js';
 export { Patterns, hasFormat, registerFormat, registerFormats } from './utils/formats.js';
 export { SSEEvent, SSEHandler, SSEMarker, createSSEHandler } from './utils/sse.js';
+export { RouteMeta, RouteRegistry, createRouteRegistry } from './utils/route-registry.js';
 export { flattenNestedRoutes, normalizePath } from './router.js';
 export { requireAuth } from './middleware/authMiddleware.js';
 export { rateLimit } from './middleware/rateLimit.js';

package/dist/index.js

@@ -8,8 +8,9 @@ function flattenNestedRoutes(routes) {
       ...route2.middleware || []
     ];
     if ("method" in route2 && "handler" in route2) {
+      const leafRoute = route2;
       flattened.push({
-        ...route2,
+        ...leafRoute,
         fullPath: currentPath,
         middlewareChain: currentMiddleware
       });
@@ -628,6 +629,22 @@ var Server = class extends BaseServer {
   getRoutes() {
     return this.router.getRoutes();
   }
+  /**
+   * 获取完整的路由元信息（不含 handler 和 middleware）
+   *
+   * 用于 API 文档生成、Webhook 事件注册、权限检查等场景
+   *
+   * @example
+   * ```typescript
+   * const routes = server.getRoutesWithMeta()
+   * for (const route of routes) {
+   *   console.log(route.fullPath, route.name, route.description)
+   * }
+   * ```
+   */
+  getRoutesWithMeta() {
+    return this.routes;
+  }
 };
 
 // src/middleware/component-router.ts
@@ -1683,6 +1700,130 @@ function createSSEHandler(schemaOrGenerator, maybeGenerator) {
   return handler;
 }
 
+// src/utils/route-registry.ts
+var RouteRegistry = class {
+  /** 所有路由元信息 */
+  routes = [];
+  /** 路由映射表：METHOD:fullPath -> RouteMeta */
+  routeMap = /* @__PURE__ */ new Map();
+  /** 分类映射表：category -> RouteMeta[] */
+  categoryMap = /* @__PURE__ */ new Map();
+  constructor(routes) {
+    this.buildRegistry(routes);
+  }
+  /**
+   * 构建注册表
+   */
+  buildRegistry(routes) {
+    for (const route2 of routes) {
+      const meta = {
+        method: route2.method,
+        path: route2.path,
+        fullPath: route2.fullPath,
+        name: route2.name,
+        description: route2.description
+      };
+      for (const key of Object.keys(route2)) {
+        if (!["method", "path", "fullPath", "name", "description", "handler", "middleware", "middlewareChain"].includes(key)) {
+          meta[key] = route2[key];
+        }
+      }
+      this.routes.push(meta);
+      this.routeMap.set(`${route2.method}:${route2.fullPath}`, meta);
+      const category = this.extractCategory(route2.fullPath);
+      if (!this.categoryMap.has(category)) {
+        this.categoryMap.set(category, []);
+      }
+      this.categoryMap.get(category).push(meta);
+    }
+  }
+  /**
+   * 提取分类（第一段路径）
+   */
+  extractCategory(path) {
+    const segments = path.split("/").filter(Boolean);
+    return segments[0] || "root";
+  }
+  // ============================================
+  // 查询接口
+  // ============================================
+  /**
+   * 获取所有路由元信息
+   */
+  getAll() {
+    return [...this.routes];
+  }
+  /**
+   * 按 method + path 查询路由
+   */
+  get(method, path) {
+    return this.routeMap.get(`${method}:${path}`);
+  }
+  /**
+   * 检查路由是否存在
+   */
+  has(method, path) {
+    return this.routeMap.has(`${method}:${path}`);
+  }
+  /**
+   * 按分类获取路由
+   */
+  getByCategory(category) {
+    return this.categoryMap.get(category) || [];
+  }
+  /**
+   * 获取所有分类
+   */
+  getCategories() {
+    return Array.from(this.categoryMap.keys()).sort();
+  }
+  /**
+   * 筛选有特定字段的路由
+   *
+   * @example
+   * ```typescript
+   * // 获取所有配置了 webhook 的路由
+   * const webhookRoutes = registry.filter('webhook')
+   * ```
+   */
+  filter(field) {
+    return this.routes.filter((r) => field in r && r[field] !== void 0);
+  }
+  /**
+   * 按条件筛选路由
+   *
+   * @example
+   * ```typescript
+   * // 获取所有 POST 请求
+   * const postRoutes = registry.filterBy(r => r.method === 'POST')
+   * ```
+   */
+  filterBy(predicate) {
+    return this.routes.filter(predicate);
+  }
+  /**
+   * 获取路由数量
+   */
+  get size() {
+    return this.routes.length;
+  }
+  /**
+   * 遍历所有路由
+   */
+  forEach(callback) {
+    this.routes.forEach(callback);
+  }
+  /**
+   * 映射所有路由
+   */
+  map(callback) {
+    return this.routes.map(callback);
+  }
+};
+function createRouteRegistry(routes) {
+  return new RouteRegistry(routes);
+}
+
 // src/middleware/authMiddleware.ts
 var requireAuth = async (req, next) => {
   const token = getCookie2(req, "auth");
@@ -2299,6 +2440,7 @@ export {
   FormatRegistry2 as FormatRegistry,
   HtmlRenderer,
   Patterns,
+  RouteRegistry,
   Server,
   ServerFactory,
   TokenError,
@@ -2315,6 +2457,7 @@ export {
   createPermissionAuth,
   createRequestValidator,
   createRoleAuth,
+  createRouteRegistry,
   createSSEHandler,
   createTokenPair,
   createTypedRoute,