vafast 0.3.10 → 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/defineRoute.d.ts

@@ -1,5 +1,103 @@
-import { Route } from './types/types.js';
+import { RouteSchema } from './types/schema.js';
+import { InferableHandler } from './utils/create-handler.js';
+import '@sinclair/typebox';
 
-declare function defineRoutes(routes: Route[]): Route[];
+/**
+ * 可推断的路由类型（用于类型推断）
+ * 供 vafast-api-client 使用，保留完整的类型信息
+ */
+type InferableRoute<TMethod extends string = string, TPath extends string = string, TReturn = unknown, TSchema extends RouteSchema = RouteSchema> = {
+    readonly method: TMethod;
+    readonly path: TPath;
+    readonly handler: InferableHandler<TReturn, TSchema>;
+    readonly middleware?: ReadonlyArray<(req: Request, next: () => Promise<Response>) => Promise<Response>>;
+};
+/**
+ * 中间件类型
+ */
+type Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * 路由定义类型（保留完整 handler 类型）
+ */
+type RouteDefinition<TMethod extends string = string, TPath extends string = string, THandler = unknown> = {
+    readonly method: TMethod;
+    readonly path: TPath;
+    readonly handler: THandler;
+    readonly middleware?: ReadonlyArray<Middleware>;
+};
+/**
+ * 创建单个路由定义（自动保留字面量类型，无需 as const）
+ *
+ * @example
+ * ```typescript
+ * import { route, defineRoutes, createHandler, Type } from 'vafast'
+ *
+ * const routes = defineRoutes([
+ *   route('GET', '/users', createHandler(
+ *     { query: Type.Object({ page: Type.Number() }) },
+ *     async ({ query }) => ({ users: [], total: 0 })
+ *   )),
+ *   route('POST', '/users', createHandler(
+ *     { body: Type.Object({ name: Type.String() }) },
+ *     async ({ body }) => ({ id: '1', name: body.name })
+ *   )),
+ *   route('GET', '/users/:id', createHandler(
+ *     { params: Type.Object({ id: Type.String() }) },
+ *     async ({ params }) => ({ id: params.id, name: 'User' })
+ *   ))
+ * ])
+ *
+ * // 无需 as const！类型自动推断
+ * type Api = InferEden<typeof routes>
+ * ```
+ */
+declare function route<TMethod extends string, TPath extends string, THandler>(method: TMethod, path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<TMethod, TPath, THandler>;
+/**
+ * GET 路由快捷方法
+ */
+declare function get<TPath extends string, THandler>(path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<'GET', TPath, THandler>;
+/**
+ * POST 路由快捷方法
+ */
+declare function post<TPath extends string, THandler>(path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<'POST', TPath, THandler>;
+/**
+ * PUT 路由快捷方法
+ */
+declare function put<TPath extends string, THandler>(path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<'PUT', TPath, THandler>;
+/**
+ * DELETE 路由快捷方法
+ */
+declare function del<TPath extends string, THandler>(path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<'DELETE', TPath, THandler>;
+/**
+ * PATCH 路由快捷方法
+ */
+declare function patch<TPath extends string, THandler>(path: TPath, handler: THandler, middleware?: Middleware[]): RouteDefinition<'PATCH', TPath, THandler>;
+/**
+ * 定义路由数组（保留完整类型信息）
+ *
+ * 推荐配合 route() 函数使用，无需 as const
+ *
+ * @example
+ * ```typescript
+ * import { defineRoutes, route, createHandler, Type } from 'vafast'
+ *
+ * // ✨ 新方式：使用 route() 函数，无需 as const
+ * const routes = defineRoutes([
+ *   route('GET', '/users', createHandler(...)),
+ *   route('POST', '/users', createHandler(...))
+ * ])
+ *
+ * // 🔙 旧方式：需要 as const（仍然支持）
+ * const routes = defineRoutes([
+ *   { method: 'GET', path: '/users', handler: createHandler(...) }
+ * ] as const)
+ * ```
+ */
+declare function defineRoutes<const T extends readonly {
+    readonly method: string;
+    readonly path: string;
+    readonly handler: unknown;
+    readonly middleware?: ReadonlyArray<Middleware>;
+}[]>(routes: T): T;
 
-export { defineRoutes };
+export { type InferableRoute, type RouteDefinition, defineRoutes, del, get, patch, post, put, route };

package/dist/defineRoute.js

@@ -1,8 +1,37 @@
 // src/defineRoute.ts
+function route(method, path, handler, middleware) {
+  return {
+    method,
+    path,
+    handler,
+    middleware
+  };
+}
+function get(path, handler, middleware) {
+  return route("GET", path, handler, middleware);
+}
+function post(path, handler, middleware) {
+  return route("POST", path, handler, middleware);
+}
+function put(path, handler, middleware) {
+  return route("PUT", path, handler, middleware);
+}
+function del(path, handler, middleware) {
+  return route("DELETE", path, handler, middleware);
+}
+function patch(path, handler, middleware) {
+  return route("PATCH", path, handler, middleware);
+}
 function defineRoutes(routes) {
   return routes;
 }
 export {
-  defineRoutes
+  defineRoutes,
+  del,
+  get,
+  patch,
+  post,
+  put,
+  route
 };
 //# sourceMappingURL=defineRoute.js.map

package/dist/defineRoute.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/defineRoute.ts"],"sourcesContent":["import type { Route } from \"./types\";\n\nexport function defineRoutes(routes: Route[]): Route[] {\n  return routes;\n}\n"],"mappings":";AAEO,SAAS,aAAa,QAA0B;AACrD,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/defineRoute.ts"],"sourcesContent":["import type { RouteSchema } from \"./types\";\nimport type { InferableHandler } from \"./utils/create-handler\";\n\n/**\n * 可推断的路由类型（用于类型推断）\n * 供 vafast-api-client 使用，保留完整的类型信息\n */\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 handler: InferableHandler<TReturn, TSchema>;\n  readonly middleware?: ReadonlyArray<(req: Request, next: () => Promise<Response>) => Promise<Response>>;\n}\n\n/**\n * 中间件类型\n */\ntype Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response>;\n\n/**\n * 路由定义类型（保留完整 handler 类型）\n */\nexport type RouteDefinition<\n  TMethod extends string = string,\n  TPath extends string = string,\n  THandler = unknown\n> = {\n  readonly method: TMethod;\n  readonly path: TPath;\n  readonly handler: THandler;\n  readonly middleware?: ReadonlyArray<Middleware>;\n}\n\n/**\n * 创建单个路由定义（自动保留字面量类型，无需 as const）\n * \n * @example\n * ```typescript\n * import { route, defineRoutes, createHandler, Type } from 'vafast'\n * \n * const routes = defineRoutes([\n *   route('GET', '/users', createHandler(\n *     { query: Type.Object({ page: Type.Number() }) },\n *     async ({ query }) => ({ users: [], total: 0 })\n *   )),\n *   route('POST', '/users', createHandler(\n *     { body: Type.Object({ name: Type.String() }) },\n *     async ({ body }) => ({ id: '1', name: body.name })\n *   )),\n *   route('GET', '/users/:id', createHandler(\n *     { params: Type.Object({ id: Type.String() }) },\n *     async ({ params }) => ({ id: params.id, name: 'User' })\n *   ))\n * ])\n * \n * // 无需 as const！类型自动推断\n * type Api = InferEden<typeof routes>\n * ```\n */\nexport function route<\n  TMethod extends string,\n  TPath extends string,\n  THandler\n>(\n  method: TMethod,\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<TMethod, TPath, THandler> {\n  return {\n    method,\n    path,\n    handler,\n    middleware\n  };\n}\n\n/**\n * GET 路由快捷方法\n */\nexport function get<TPath extends string, THandler>(\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<'GET', TPath, THandler> {\n  return route('GET', path, handler, middleware);\n}\n\n/**\n * POST 路由快捷方法\n */\nexport function post<TPath extends string, THandler>(\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<'POST', TPath, THandler> {\n  return route('POST', path, handler, middleware);\n}\n\n/**\n * PUT 路由快捷方法\n */\nexport function put<TPath extends string, THandler>(\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<'PUT', TPath, THandler> {\n  return route('PUT', path, handler, middleware);\n}\n\n/**\n * DELETE 路由快捷方法\n */\nexport function del<TPath extends string, THandler>(\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<'DELETE', TPath, THandler> {\n  return route('DELETE', path, handler, middleware);\n}\n\n/**\n * PATCH 路由快捷方法\n */\nexport function patch<TPath extends string, THandler>(\n  path: TPath,\n  handler: THandler,\n  middleware?: Middleware[]\n): RouteDefinition<'PATCH', TPath, THandler> {\n  return route('PATCH', path, handler, middleware);\n}\n\n/**\n * 定义路由数组（保留完整类型信息）\n * \n * 推荐配合 route() 函数使用，无需 as const\n * \n * @example\n * ```typescript\n * import { defineRoutes, route, createHandler, Type } from 'vafast'\n * \n * // ✨ 新方式：使用 route() 函数，无需 as const\n * const routes = defineRoutes([\n *   route('GET', '/users', createHandler(...)),\n *   route('POST', '/users', createHandler(...))\n * ])\n * \n * // 🔙 旧方式：需要 as const（仍然支持）\n * const routes = defineRoutes([\n *   { method: 'GET', path: '/users', handler: createHandler(...) }\n * ] as const)\n * ```\n */\nexport function defineRoutes<\n  const T extends readonly {\n    readonly method: string\n    readonly path: string\n    readonly handler: unknown\n    readonly middleware?: ReadonlyArray<Middleware>\n  }[]\n>(routes: T): T {\n  return routes;\n}\n"],"mappings":";AAgEO,SAAS,MAKd,QACA,MACA,SACA,YAC2C;AAC3C,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAKO,SAAS,IACd,MACA,SACA,YACyC;AACzC,SAAO,MAAM,OAAO,MAAM,SAAS,UAAU;AAC/C;AAKO,SAAS,KACd,MACA,SACA,YAC0C;AAC1C,SAAO,MAAM,QAAQ,MAAM,SAAS,UAAU;AAChD;AAKO,SAAS,IACd,MACA,SACA,YACyC;AACzC,SAAO,MAAM,OAAO,MAAM,SAAS,UAAU;AAC/C;AAKO,SAAS,IACd,MACA,SACA,YAC4C;AAC5C,SAAO,MAAM,UAAU,MAAM,SAAS,UAAU;AAClD;AAKO,SAAS,MACd,MACA,SACA,YAC2C;AAC3C,SAAO,MAAM,SAAS,MAAM,SAAS,UAAU;AACjD;AAuBO,SAAS,aAOd,QAAc;AACd,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { ComponentServer } from './server/component-server.js';
 export { ServerFactory } from './server/server-factory.js';
 export { BaseServer } from './server/base-server.js';
 export { VafastError, composeMiddleware } from './middleware.js';
-export { createHandler, createHandlerWithExtra, simpleHandler } from './utils/create-handler.js';
+export { InferableHandler, createHandler, createHandlerWithExtra, simpleHandler } from './utils/create-handler.js';
 export { getCookie, getHeader, parseBody, parseCookies, parseCookiesFast, parseHeaders, parseQuery, parseQueryFast } from './utils/parsers.js';
 export { empty, html, json, redirect, stream, text } from './utils/response.js';
 export { goAwait } from './utils/go-await.js';
@@ -14,13 +14,15 @@ export { HtmlRenderer } from './utils/html-renderer.js';
 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';
 export { CORSOptions, createCORS } from './middleware/cors.js';
 export { TokenError, TokenOptions, TokenPayload, TokenResult, createTokenPair, generateToken, getTokenTimeRemaining, isTokenExpired, parseToken, refreshToken, verifyToken } from './auth/token.js';
 export { createAuth, createOptionalAuth, createPermissionAuth, createRoleAuth } from './middleware/auth.js';
-export { defineRoutes } from './defineRoute.js';
+export { InferableRoute, RouteDefinition, defineRoutes, del, get, patch, post, put, route } from './defineRoute.js';
 export { FlattenedRoute, Handler, Method, Middleware, NestedRoute, ResponseBody, Route } from './types/types.js';
 export { BaseRouteConfig, CompatibleRoute, ExtendedRouteConfig, NestedRouteConfig, TypedRoute, createTypedRoute, isTypedRoute } from './types/route.js';
 export { ComponentRoute, FlattenedComponentRoute, NestedComponentRoute } from './types/component-route.js';