@longzai-intelligence-transport/http-core 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -620,7 +620,10 @@ type InferRouteBody<T extends RouteDefinition> = T extends JsonResponseRoute<Htt
 /**
  * 从路由定义中推断响应数据类型
  *
- * 自动解包 ApiResponse 和 PaginatedResponse
+ * 自动解包 ApiResponse 和 PaginatedResponse。
+ * 对联合别名形态鲁棒：当 T 为 tsgo/tsc 类型规范化产物（RouteDefinition 联合别名）时，
+ * JSON 路由不联合 BinaryStreamMarker，stream 路由保留 BinaryStreamMarker（不退化为 unknown）。
+ * 实现详见 ADR-0005。
  *
  * @example
  *   type Data = InferRouteResponse<typeof routes.detail>;
@@ -628,15 +631,13 @@ type InferRouteBody<T extends RouteDefinition> = T extends JsonResponseRoute<Htt
  *
  * @typeParam T - 路由定义类型
  */
-type InferRouteResponse<T extends RouteDefinition> = T extends {
-  responseType: 'stream';
-} ? BinaryStreamMarker : T extends {
-  response: infer R;
-} ? R extends ZodType ? ExtractData<R['_output']> : never : never;
+type InferRouteResponse<T extends RouteDefinition> = [Extract<T, JsonResponseRoute>] extends [never] ? BinaryStreamMarker : Extract<T, JsonResponseRoute> extends JsonResponseRoute<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, infer R> ? [ZodType] extends [R] ? BinaryStreamMarker : ExtractData<R['_output']> : never;
 /**
  * 从路由定义中推断完整的响应类型
  *
- * 包含 ApiResponse 包装
+ * 包含 ApiResponse 包装。
+ * 对联合别名形态鲁棒：JSON 路由不联合 BinaryStreamMarker，stream 路由保留 BinaryStreamMarker。
+ * 实现详见 ADR-0005。
  *
  * @example
  *   type Response = InferRouteFullResponse<typeof routes.detail>;
@@ -644,11 +645,7 @@ type InferRouteResponse<T extends RouteDefinition> = T extends {
  *
  * @typeParam T - 路由定义类型
  */
-type InferRouteFullResponse<T extends RouteDefinition> = T extends {
-  responseType: 'stream';
-} ? BinaryStreamMarker : T extends {
-  response: infer R;
-} ? R extends ZodType ? ApiResponse<ExtractData<R['_output']>> : never : never;
+type InferRouteFullResponse<T extends RouteDefinition> = [Extract<T, JsonResponseRoute>] extends [never] ? BinaryStreamMarker : Extract<T, JsonResponseRoute> extends JsonResponseRoute<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, infer R> ? [ZodType] extends [R] ? BinaryStreamMarker : ApiResponse<ExtractData<R['_output']>> : never;
 /**
  * 从路由定义中推断分页响应的项类型
  *
@@ -2007,7 +2004,7 @@ declare function buildQuery(query?: Record<string, string | number | boolean | u
  */
 declare function concatPath<T extends string, U extends string>(a: T, b: U): `${T}${U}`;
 //#endregion
-//#region src/routes/route-group.utils.d.ts
+//#region src/routes/route-group.types.d.ts
 /**
  * API 版本号类型
  *
@@ -2029,134 +2026,76 @@ type DefaultAuthStrategy = 'public' | 'user' | 'admin' | (string & {});
  */
 type VersionedPrefix<TVersion extends ApiVersion | undefined, TPrefix extends string> = TVersion extends ApiVersion ? TPrefix extends `/${string}` ? `/${TVersion}${TPrefix}` : TPrefix extends '' ? `/${TVersion}` : `/${TVersion}/${TPrefix}` : TPrefix;
 /**
- * 路由分组配置
+ * 路由定义配置（用于分组内定义）
  *
- * @typeParam TPrefix - 路径前缀类型
- * @typeParam TVersion - API 版本号类型
- * @typeParam TAuthStrategy - 认证策略类型
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
  */
-type RouteGroupConfig<TPrefix extends string = '', TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType = ZodType> = {
   /**
-   * 父路由分组（可选）
-   *
-   * 指定父分组时，当前分组会继承父分组的配置并追加路径
-   * - prefix 会追加到父分组的 prefix 后面
-   * - auth 和 tags 会继承父分组的值（如果未指定）
+   * HTTP 方法
    */
-  parent?: RouteGroup<string, ApiVersion | undefined, TAuthStrategy>;
+  method: TMethod;
   /**
-   * 路径前缀（可选）
-   *
-   * 所有子路由的路径都会自动拼接此前缀
-   * 如果指定了 parent，此前缀会追加到父分组的 prefix 后面
-   * 如果指定了 version，版本前缀会自动添加到 prefix 前面
-   * 如果未指定，默认为空字符串
+   * 路径模板，会自动拼接分组前缀
    */
-  prefix?: TPrefix;
+  path: TPath;
   /**
-   * API 版本号
-   *
-   * 版本前缀会自动添加到 prefix 前面，格式为 /{version}
-   * 例如：version: 'v1', prefix: 'client' -> 实际前缀: /v1/client
-   * 例如：version: 'v1', prefix: '' -> 实际前缀: /v1
-   *
-   * 注意：如果指定了 parent，version 应该在父分组中指定，子分组会自动继承
+   * 路径参数 Schema
    */
-  version?: TVersion;
+  params?: TParams;
   /**
-   * 认证策略
-   *
-   * 标识分组内路由的认证要求，可由适配器读取并应用相应的中间件
-   * 如果指定了 parent 且未设置此字段，会继承父分组的 auth
+   * 查询参数 Schema
    */
-  auth?: TAuthStrategy;
+  query?: TQuery;
   /**
-   * API 标签（用于 Swagger 分组和 TypedController）
-   *
-   * TypedController 装饰器会使用这些标签设置 @ApiTags()
-   * 子路由会继承这些标签，并可追加自己的标签
-   * 如果指定了 parent 且未设置此字段，会继承父分组的 tags
+   * 请求体 Schema
    */
-  tags?: string[];
+  body?: TBody;
   /**
-   * 路由定义集合（可选）
-   *
-   * 提供 routes 时，defineRouteGroup 返回 RouteGroup & { routes }，
-   * 可直接用于 TypedController 和 TypedRoute。
-   * 不提供 routes 时，返回纯 RouteGroup，可用于 defineRoute 拆分定义。
-   *
-   * 接受两种输入：
-   * - 内联原始配置对象（简单场景，少量路由）
-   * - group.defineRoute() 的返回值（复杂场景，拆分定义）
+   * 响应 Schema
    */
-  routes?: Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>;
-};
-/**
- * 路由分组
- *
- * 提供路由分组功能，子路由自动继承分组的配置
- *
- * @typeParam TPrefix - 路径前缀类型
- * @typeParam TVersion - API 版本号类型
- * @typeParam TAuthStrategy - 认证策略类型
- */
-type RouteGroup<TPrefix extends string = string, TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+  response: TResponse;
   /**
-   * 完整路径前缀（包含版本）
-   *
-   * 如果指定了 version，格式为 /{version}/{prefix}
-   * 如果未指定 version，则为原始 prefix
+   * 接口摘要描述
    */
-  readonly prefix: VersionedPrefix<TVersion, TPrefix>;
+  summary?: string;
   /**
-   * API 版本号
+   * 接口标签，会与分组标签合并
    */
-  readonly version?: TVersion;
+  tags?: string[];
   /**
-   * 认证策略
-   *
-   * 标识分组内路由的认证要求
+   * 是否需要 CSRF 令牌保护
    */
-  readonly auth?: TAuthStrategy;
+  csrf?: boolean;
   /**
-   * API 标签（用于 Swagger 分组和 TypedController）
-   *
-   * 用于接口分组和文档生成
+   * 请求内容类型
    */
-  readonly tags?: string[];
+  contentType?: 'json' | 'formData';
   /**
-   * 定义单条路由
-   *
-   * 语法糖，用于需要单独引用某条路由或拆分复杂路由定义的场景。
-   * 子路由的路径会自动拼接分组前缀，并继承分组的认证策略和标签。
+   * 覆盖分组的认证策略
    *
-   * @typeParam TMethod - HTTP 方法类型
-   * @typeParam TPath - 路径模板字符串
-   * @typeParam TParams - 路径参数 Zod Schema
-   * @typeParam TQuery - 查询参数 Zod Schema
-   * @typeParam TBody - 请求体 Zod Schema
-   * @typeParam TResponse - 响应 Zod Schema
-   * @param config - 路由配置对象
-   * @returns 类型安全的路由定义，路径已拼接前缀
-   */
-  defineRoute: <TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = undefined, TQuery extends ZodType | undefined = undefined, TBody extends ZodType | undefined = undefined, TResponse extends ZodType = ZodType>(config: RouteDefineConfig<TMethod, TPath, TParams, TQuery, TBody, TResponse>) => RouteDefinition<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
-    /**
-     * 认证策略
-     */
-    auth?: TAuthStrategy;
-  };
+   * 用于覆盖父路由分组的认证设置
+   */
+  auth?: string;
 };
 /**
- * 路由定义配置（用于分组内定义）
+ * 流式路由分组定义配置
+ *
+ * 用于 RouteGroup.defineRoute 创建流式响应路由，responseType 必填 'stream'，
+ * stream 字段描述响应元数据。
  *
  * @typeParam TMethod - HTTP 方法类型
  * @typeParam TPath - 路径模板字符串
  * @typeParam TParams - 路径参数 Schema 类型
  * @typeParam TQuery - 查询参数 Schema 类型
  * @typeParam TBody - 请求体 Schema 类型
- * @typeParam TResponse - 响应 Schema 类型
  */
-type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType = ZodType> = {
+type StreamRouteGroupDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined> = {
   /**
    * HTTP 方法
    */
@@ -2178,9 +2117,13 @@ type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends st
    */
   body?: TBody;
   /**
-   * 响应 Schema
+   * 响应类型标记：二进制流，显式必填
    */
-  response: TResponse;
+  responseType: 'stream';
+  /**
+   * 流式响应元数据
+   */
+  stream: StreamResponseMeta;
   /**
    * 接口摘要描述
    */
@@ -2199,30 +2142,77 @@ type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends st
   contentType?: 'json' | 'formData';
   /**
    * 覆盖分组的认证策略
-   *
-   * 用于覆盖父路由分组的认证设置
    */
   auth?: string;
 };
 /**
- * 路由定义结果类型
+ * defineRoute 重载类型
  *
- * defineRoute 返回的类型，包含完整的路由定义和可选的 auth 属性
+ * stream config 返回精确的 StreamResponseRoute，
+ * JSON config 返回精确的 JsonResponseRoute。
  *
- * @typeParam TMethod - HTTP 方法类型
  * @typeParam TVersion - API 版本号类型
  * @typeParam TPrefix - 路径前缀类型
- * @typeParam TPath - 路径模板字符串
- * @typeParam TParams - 路径参数 Schema 类型
- * @typeParam TQuery - 查询参数 Schema 类型
- * @typeParam TBody - 请求体 Schema 类型
- * @typeParam TResponse - 响应 Schema 类型
+ * @typeParam TAuthStrategy - 认证策略类型
  */
-type RouteDefineResult<TMethod extends HttpMethod, TVersion extends ApiVersion | undefined, TPrefix extends string, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TResponse extends ZodType> = RouteDefinition<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
+type DefineRouteOverloads<TVersion extends ApiVersion | undefined, TPrefix extends string, TAuthStrategy extends string> = {
+  /**
+   * 定义单条路由（流式响应）
+   */
+  <TMethod extends HttpMethod, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TLocalAuth extends string | undefined = undefined>(config: StreamRouteGroupDefineConfig<TMethod, TPath, TParams, TQuery, TBody> & {
+    auth?: TLocalAuth;
+  }): StreamResponseRoute<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody> & {
+    auth?: TLocalAuth extends string ? TLocalAuth : TAuthStrategy;
+  };
+  /**
+   * 定义单条路由（JSON 响应）
+   */
+  <TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = undefined, TQuery extends ZodType | undefined = undefined, TBody extends ZodType | undefined = undefined, TResponse extends ZodType = ZodType, TLocalAuth extends string | undefined = undefined>(config: RouteDefineConfig<TMethod, TPath, TParams, TQuery, TBody, TResponse> & {
+    auth?: TLocalAuth;
+  }): JsonResponseRoute<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
+    auth?: TLocalAuth extends string ? TLocalAuth : TAuthStrategy;
+  };
+};
+/**
+ * 路由分组
+ *
+ * 提供路由分组功能，子路由自动继承分组的配置
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ */
+type RouteGroup<TPrefix extends string = string, TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+  /**
+   * 完整路径前缀（包含版本）
+   *
+   * 如果指定了 version，格式为 /{version}/{prefix}
+   * 如果未指定 version，则为原始 prefix
+   */
+  readonly prefix: VersionedPrefix<TVersion, TPrefix>;
+  /**
+   * API 版本号
+   */
+  readonly version?: TVersion;
   /**
    * 认证策略
+   *
+   * 标识分组内路由的认证要求
    */
-  auth?: string;
+  readonly auth?: TAuthStrategy;
+  /**
+   * API 标签（用于 Swagger 分组和 TypedController）
+   *
+   * 用于接口分组和文档生成
+   */
+  readonly tags?: string[];
+  /**
+   * 定义单条路由（支持 JSON 响应和流式响应）
+   *
+   * stream config → 精确的 StreamResponseRoute
+   * JSON config   → 精确的 JsonResponseRoute
+   */
+  defineRoute: DefineRouteOverloads<TVersion, TPrefix, TAuthStrategy>;
 };
 /**
  * 已处理的路由类型
@@ -2332,6 +2322,99 @@ T extends {
  * @typeParam TRoutes - 路由定义集合类型
  */
 type ProcessRoutes<TRoutes extends Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>> = { [K in keyof TRoutes]: ProcessedRoute<InferRouteDefinitionFromValue<TRoutes[K]>> };
+/**
+ * 路由分组配置
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ */
+type RouteGroupConfig<TPrefix extends string = '', TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+  /**
+   * 父路由分组（可选）
+   *
+   * 指定父分组时，当前分组会继承父分组的配置并追加路径
+   * - prefix 会追加到父分组的 prefix 后面
+   * - auth 和 tags 会继承父分组的值（如果未指定）
+   */
+  parent?: RouteGroup<string, ApiVersion | undefined, TAuthStrategy>;
+  /**
+   * 路径前缀（可选）
+   *
+   * 所有子路由的路径都会自动拼接此前缀
+   * 如果指定了 parent，此前缀会追加到父分组的 prefix 后面
+   * 如果指定了 version，版本前缀会自动添加到 prefix 前面
+   * 如果未指定，默认为空字符串
+   */
+  prefix?: TPrefix;
+  /**
+   * API 版本号
+   *
+   * 版本前缀会自动添加到 prefix 前面，格式为 /{version}
+   * 例如：version: 'v1', prefix: 'client' -> 实际前缀: /v1/client
+   * 例如：version: 'v1', prefix: '' -> 实际前缀: /v1
+   *
+   * 注意：如果指定了 parent，version 应该在父分组中指定，子分组会自动继承
+   */
+  version?: TVersion;
+  /**
+   * 认证策略
+   *
+   * 标识分组内路由的认证要求，可由适配器读取并应用相应的中间件
+   * 如果指定了 parent 且未设置此字段，会继承父分组的 auth
+   */
+  auth?: TAuthStrategy;
+  /**
+   * API 标签（用于 Swagger 分组和 TypedController）
+   *
+   * TypedController 装饰器会使用这些标签设置 @ApiTags()
+   * 子路由会继承这些标签，并可追加自己的标签
+   * 如果指定了 parent 且未设置此字段，会继承父分组的 tags
+   */
+  tags?: string[];
+  /**
+   * 路由定义集合（可选）
+   *
+   * 提供 routes 时，defineRouteGroup 返回 RouteGroup & { routes }，
+   * 可直接用于 TypedController 和 TypedRoute。
+   * 不提供 routes 时，返回纯 RouteGroup，可用于 defineRoute 拆分定义。
+   *
+   * 接受两种输入：
+   * - 内联原始配置对象（简单场景，少量路由）
+   * - group.defineRoute() 的返回值（复杂场景，拆分定义）
+   */
+  routes?: Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>;
+};
+/**
+ * defineRouteGroup 函数配置类型
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ * @typeParam TRoutes - 路由定义集合类型
+ */
+/**
+ * 路由定义结果类型
+ *
+ * defineRoute 返回的类型，包含完整的路由定义和可选的 auth 属性
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
+ */
+type RouteDefineResult<TMethod extends HttpMethod, TVersion extends ApiVersion | undefined, TPrefix extends string, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TResponse extends ZodType> = RouteDefinition<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
+  /**
+   * 认证策略
+   */
+  auth?: string;
+};
+//#endregion
+//#region src/routes/route-group.utils.d.ts
 /**
  * 定义路由分组（含 routes，保留具体键类型）
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longzai-intelligence-transport/http-core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "keywords": [
     "api",
     "contract",