vafast 0.3.11 → 0.4.0

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

@@ -0,0 +1,134 @@
+import { FlattenedRoute, Method } from '../types/types.js';
+
+/**
+ * 路由注册表
+ *
+ * 提供路由元信息的收集和查询能力
+ * 可用于：API 文档生成、Webhook 事件注册、权限检查、审计日志等
+ *
+ * @example
+ * ```typescript
+ * // 创建注册表
+ * const registry = createRouteRegistry(server.getRoutes())
+ *
+ * // 查询路由
+ * const route = registry.get('POST', '/auth/signIn')
+ *
+ * // 筛选有 webhook 配置的路由
+ * const webhookRoutes = registry.filter('webhook')
+ *
+ * // 按分类获取
+ * const authRoutes = registry.getByCategory('auth')
+ * ```
+ */
+
+/**
+ * 路由元信息（不含 handler 和 middleware）
+ */
+interface RouteMeta {
+    method: Method;
+    path: string;
+    fullPath: string;
+    name?: string;
+    description?: string;
+    /** 扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 路由注册表
+ *
+ * 泛型 T 用于定义扩展字段的类型
+ */
+declare class RouteRegistry<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 所有路由元信息 */
+    private routes;
+    /** 路由映射表：METHOD:fullPath -> RouteMeta */
+    private routeMap;
+    /** 分类映射表：category -> RouteMeta[] */
+    private categoryMap;
+    constructor(routes: FlattenedRoute[]);
+    /**
+     * 构建注册表
+     */
+    private buildRegistry;
+    /**
+     * 提取分类（第一段路径）
+     */
+    private extractCategory;
+    /**
+     * 获取所有路由元信息
+     */
+    getAll(): RouteMeta[];
+    /**
+     * 按 method + path 查询路由
+     */
+    get(method: string, path: string): (RouteMeta & T) | undefined;
+    /**
+     * 检查路由是否存在
+     */
+    has(method: string, path: string): boolean;
+    /**
+     * 按分类获取路由
+     */
+    getByCategory(category: string): RouteMeta[];
+    /**
+     * 获取所有分类
+     */
+    getCategories(): string[];
+    /**
+     * 筛选有特定字段的路由
+     *
+     * @example
+     * ```typescript
+     * // 获取所有配置了 webhook 的路由
+     * const webhookRoutes = registry.filter('webhook')
+     * ```
+     */
+    filter<K extends string>(field: K): (RouteMeta & Record<K, unknown>)[];
+    /**
+     * 按条件筛选路由
+     *
+     * @example
+     * ```typescript
+     * // 获取所有 POST 请求
+     * const postRoutes = registry.filterBy(r => r.method === 'POST')
+     * ```
+     */
+    filterBy(predicate: (route: RouteMeta) => boolean): RouteMeta[];
+    /**
+     * 获取路由数量
+     */
+    get size(): number;
+    /**
+     * 遍历所有路由
+     */
+    forEach(callback: (route: RouteMeta, index: number) => void): void;
+    /**
+     * 映射所有路由
+     */
+    map<R>(callback: (route: RouteMeta, index: number) => R): R[];
+}
+/**
+ * 创建路由注册表
+ *
+ * @example
+ * ```typescript
+ * // 定义扩展字段类型
+ * interface MyRouteMeta {
+ *   webhook?: { eventKey: string }
+ *   permission?: string
+ * }
+ *
+ * // 创建带类型的注册表
+ * const registry = createRouteRegistry<MyRouteMeta>(server.getRoutes())
+ *
+ * // 类型安全的查询
+ * const route = registry.get('POST', '/auth/signIn')
+ * if (route?.webhook) {
+ *   console.log(route.webhook.eventKey)
+ * }
+ * ```
+ */
+declare function createRouteRegistry<T extends Record<string, unknown> = Record<string, unknown>>(routes: FlattenedRoute[]): RouteRegistry<T>;
+
+export { type RouteMeta, RouteRegistry, createRouteRegistry };

package/dist/utils/route-registry.js

@@ -0,0 +1,128 @@
+// 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 route of routes) {
+      const meta = {
+        method: route.method,
+        path: route.path,
+        fullPath: route.fullPath,
+        name: route.name,
+        description: route.description
+      };
+      for (const key of Object.keys(route)) {
+        if (!["method", "path", "fullPath", "name", "description", "handler", "middleware", "middlewareChain"].includes(key)) {
+          meta[key] = route[key];
+        }
+      }
+      this.routes.push(meta);
+      this.routeMap.set(`${route.method}:${route.fullPath}`, meta);
+      const category = this.extractCategory(route.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);
+}
+export {
+  RouteRegistry,
+  createRouteRegistry
+};
+//# sourceMappingURL=route-registry.js.map

package/dist/utils/route-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/route-registry.ts"],"sourcesContent":["/**\n * 路由注册表\n *\n * 提供路由元信息的收集和查询能力\n * 可用于：API 文档生成、Webhook 事件注册、权限检查、审计日志等\n *\n * @example\n * ```typescript\n * // 创建注册表\n * const registry = createRouteRegistry(server.getRoutes())\n *\n * // 查询路由\n * const route = registry.get('POST', '/auth/signIn')\n *\n * // 筛选有 webhook 配置的路由\n * const webhookRoutes = registry.filter('webhook')\n *\n * // 按分类获取\n * const authRoutes = registry.getByCategory('auth')\n * ```\n */\n\nimport type { FlattenedRoute, Method } from '../types'\n\n/**\n * 路由元信息（不含 handler 和 middleware）\n */\nexport interface RouteMeta {\n  method: Method\n  path: string\n  fullPath: string\n  name?: string\n  description?: string\n  /** 扩展字段 */\n  [key: string]: unknown\n}\n\n/**\n * 路由注册表\n *\n * 泛型 T 用于定义扩展字段的类型\n */\nexport class RouteRegistry<T extends Record<string, unknown> = Record<string, unknown>> {\n  /** 所有路由元信息 */\n  private routes: RouteMeta[] = []\n\n  /** 路由映射表：METHOD:fullPath -> RouteMeta */\n  private routeMap = new Map<string, RouteMeta>()\n\n  /** 分类映射表：category -> RouteMeta[] */\n  private categoryMap = new Map<string, RouteMeta[]>()\n\n  constructor(routes: FlattenedRoute[]) {\n    this.buildRegistry(routes)\n  }\n\n  /**\n   * 构建注册表\n   */\n  private buildRegistry(routes: FlattenedRoute[]): void {\n    for (const route of routes) {\n      // 提取元信息（排除 handler 和 middleware）\n      const meta: RouteMeta = {\n        method: route.method,\n        path: route.path,\n        fullPath: route.fullPath,\n        name: route.name,\n        description: route.description,\n      }\n\n      // 复制扩展字段\n      for (const key of Object.keys(route)) {\n        if (!['method', 'path', 'fullPath', 'name', 'description', 'handler', 'middleware', 'middlewareChain'].includes(key)) {\n          meta[key] = route[key as keyof FlattenedRoute]\n        }\n      }\n\n      this.routes.push(meta)\n      this.routeMap.set(`${route.method}:${route.fullPath}`, meta)\n\n      // 按分类索引\n      const category = this.extractCategory(route.fullPath)\n      if (!this.categoryMap.has(category)) {\n        this.categoryMap.set(category, [])\n      }\n      this.categoryMap.get(category)!.push(meta)\n    }\n  }\n\n  /**\n   * 提取分类（第一段路径）\n   */\n  private extractCategory(path: string): string {\n    const segments = path.split('/').filter(Boolean)\n    return segments[0] || 'root'\n  }\n\n  // ============================================\n  // 查询接口\n  // ============================================\n\n  /**\n   * 获取所有路由元信息\n   */\n  getAll(): RouteMeta[] {\n    return [...this.routes]\n  }\n\n  /**\n   * 按 method + path 查询路由\n   */\n  get(method: string, path: string): (RouteMeta & T) | undefined {\n    return this.routeMap.get(`${method}:${path}`) as (RouteMeta & T) | undefined\n  }\n\n  /**\n   * 检查路由是否存在\n   */\n  has(method: string, path: string): boolean {\n    return this.routeMap.has(`${method}:${path}`)\n  }\n\n  /**\n   * 按分类获取路由\n   */\n  getByCategory(category: string): RouteMeta[] {\n    return this.categoryMap.get(category) || []\n  }\n\n  /**\n   * 获取所有分类\n   */\n  getCategories(): string[] {\n    return Array.from(this.categoryMap.keys()).sort()\n  }\n\n  /**\n   * 筛选有特定字段的路由\n   *\n   * @example\n   * ```typescript\n   * // 获取所有配置了 webhook 的路由\n   * const webhookRoutes = registry.filter('webhook')\n   * ```\n   */\n  filter<K extends string>(field: K): (RouteMeta & Record<K, unknown>)[] {\n    return this.routes.filter((r) => field in r && r[field] !== undefined) as (RouteMeta & Record<K, unknown>)[]\n  }\n\n  /**\n   * 按条件筛选路由\n   *\n   * @example\n   * ```typescript\n   * // 获取所有 POST 请求\n   * const postRoutes = registry.filterBy(r => r.method === 'POST')\n   * ```\n   */\n  filterBy(predicate: (route: RouteMeta) => boolean): RouteMeta[] {\n    return this.routes.filter(predicate)\n  }\n\n  /**\n   * 获取路由数量\n   */\n  get size(): number {\n    return this.routes.length\n  }\n\n  /**\n   * 遍历所有路由\n   */\n  forEach(callback: (route: RouteMeta, index: number) => void): void {\n    this.routes.forEach(callback)\n  }\n\n  /**\n   * 映射所有路由\n   */\n  map<R>(callback: (route: RouteMeta, index: number) => R): R[] {\n    return this.routes.map(callback)\n  }\n}\n\n/**\n * 创建路由注册表\n *\n * @example\n * ```typescript\n * // 定义扩展字段类型\n * interface MyRouteMeta {\n *   webhook?: { eventKey: string }\n *   permission?: string\n * }\n *\n * // 创建带类型的注册表\n * const registry = createRouteRegistry<MyRouteMeta>(server.getRoutes())\n *\n * // 类型安全的查询\n * const route = registry.get('POST', '/auth/signIn')\n * if (route?.webhook) {\n *   console.log(route.webhook.eventKey)\n * }\n * ```\n */\nexport function createRouteRegistry<T extends Record<string, unknown> = Record<string, unknown>>(\n  routes: FlattenedRoute[]\n): RouteRegistry<T> {\n  return new RouteRegistry<T>(routes)\n}\n\n"],"mappings":";AA0CO,IAAM,gBAAN,MAAiF;AAAA;AAAA,EAE9E,SAAsB,CAAC;AAAA;AAAA,EAGvB,WAAW,oBAAI,IAAuB;AAAA;AAAA,EAGtC,cAAc,oBAAI,IAAyB;AAAA,EAEnD,YAAY,QAA0B;AACpC,SAAK,cAAc,MAAM;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKQ,cAAc,QAAgC;AACpD,eAAW,SAAS,QAAQ;AAE1B,YAAM,OAAkB;AAAA,QACtB,QAAQ,MAAM;AAAA,QACd,MAAM,MAAM;AAAA,QACZ,UAAU,MAAM;AAAA,QAChB,MAAM,MAAM;AAAA,QACZ,aAAa,MAAM;AAAA,MACrB;AAGA,iBAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,YAAI,CAAC,CAAC,UAAU,QAAQ,YAAY,QAAQ,eAAe,WAAW,cAAc,iBAAiB,EAAE,SAAS,GAAG,GAAG;AACpH,eAAK,GAAG,IAAI,MAAM,GAA2B;AAAA,QAC/C;AAAA,MACF;AAEA,WAAK,OAAO,KAAK,IAAI;AACrB,WAAK,SAAS,IAAI,GAAG,MAAM,MAAM,IAAI,MAAM,QAAQ,IAAI,IAAI;AAG3D,YAAM,WAAW,KAAK,gBAAgB,MAAM,QAAQ;AACpD,UAAI,CAAC,KAAK,YAAY,IAAI,QAAQ,GAAG;AACnC,aAAK,YAAY,IAAI,UAAU,CAAC,CAAC;AAAA,MACnC;AACA,WAAK,YAAY,IAAI,QAAQ,EAAG,KAAK,IAAI;AAAA,IAC3C;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,gBAAgB,MAAsB;AAC5C,UAAM,WAAW,KAAK,MAAM,GAAG,EAAE,OAAO,OAAO;AAC/C,WAAO,SAAS,CAAC,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,SAAsB;AACpB,WAAO,CAAC,GAAG,KAAK,MAAM;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,QAAgB,MAA2C;AAC7D,WAAO,KAAK,SAAS,IAAI,GAAG,MAAM,IAAI,IAAI,EAAE;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,QAAgB,MAAuB;AACzC,WAAO,KAAK,SAAS,IAAI,GAAG,MAAM,IAAI,IAAI,EAAE;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA,EAKA,cAAc,UAA+B;AAC3C,WAAO,KAAK,YAAY,IAAI,QAAQ,KAAK,CAAC;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,gBAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,YAAY,KAAK,CAAC,EAAE,KAAK;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,OAAyB,OAA8C;AACrE,WAAO,KAAK,OAAO,OAAO,CAAC,MAAM,SAAS,KAAK,EAAE,KAAK,MAAM,MAAS;AAAA,EACvE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,SAAS,WAAuD;AAC9D,WAAO,KAAK,OAAO,OAAO,SAAS;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA,EAKA,QAAQ,UAA2D;AACjE,SAAK,OAAO,QAAQ,QAAQ;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAO,UAAuD;AAC5D,WAAO,KAAK,OAAO,IAAI,QAAQ;AAAA,EACjC;AACF;AAuBO,SAAS,oBACd,QACkB;AAClB,SAAO,IAAI,cAAiB,MAAM;AACpC;","names":[]}

package/package.json

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