@longzai-intelligence-transport/http-core 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -583,39 +583,40 @@ type RouteDefinition<TMethod extends HttpMethod = HttpMethod, TPath extends stri
 /**
  * 从路由定义中推断路径参数类型
  *
+ * 使用位置泛型匹配直接捕获 TParams 参数，避免结构属性匹配中
+ * 可选属性 `?` 剥离联合类型中 `undefined` 导致的推断偏差。
+ *
  * @example
  *   type Params = InferRouteParams<typeof routes.detail>;
  *   // { id: string }
  *
  * @typeParam T - 路由定义类型
  */
-type InferRouteParams<T extends RouteDefinition> = T extends {
-  params?: infer P;
-} ? P extends ZodType ? P['_output'] : undefined : undefined;
+type InferRouteParams<T extends RouteDefinition> = T extends JsonResponseRoute<HttpMethod, string, infer P, ZodType | undefined, ZodType | undefined, ZodType> ? [P] extends [ZodType] ? P['_output'] : undefined : T extends StreamResponseRoute<HttpMethod, string, infer P, ZodType | undefined, ZodType | undefined> ? [P] extends [ZodType] ? P['_output'] : undefined : undefined;
 /**
  * 从路由定义中推断查询参数类型
  *
+ * 使用位置泛型匹配直接捕获 TQuery 参数。
+ *
  * @example
  *   type Query = InferRouteQuery<typeof routes.list>;
  *   // { page?: number; pageSize?: number }
  *
  * @typeParam T - 路由定义类型
  */
-type InferRouteQuery<T extends RouteDefinition> = T extends {
-  query?: infer Q;
-} ? Q extends ZodType ? Q['_output'] : undefined : undefined;
+type InferRouteQuery<T extends RouteDefinition> = T extends JsonResponseRoute<HttpMethod, string, ZodType | undefined, infer Q, ZodType | undefined, ZodType> ? [Q] extends [ZodType] ? Q['_output'] : undefined : T extends StreamResponseRoute<HttpMethod, string, ZodType | undefined, infer Q, ZodType | undefined> ? [Q] extends [ZodType] ? Q['_output'] : undefined : undefined;
 /**
  * 从路由定义中推断请求体类型
  *
+ * 使用位置泛型匹配直接捕获 TBody 参数。
+ *
  * @example
  *   type Body = InferRouteBody<typeof routes.create>;
  *   // { name: string; price: number }
  *
  * @typeParam T - 路由定义类型
  */
-type InferRouteBody<T extends RouteDefinition> = T extends {
-  body?: infer B;
-} ? B extends ZodType ? B['_output'] : undefined : undefined;
+type InferRouteBody<T extends RouteDefinition> = T extends JsonResponseRoute<HttpMethod, string, ZodType | undefined, ZodType | undefined, infer B, ZodType> ? [B] extends [ZodType] ? B['_output'] : undefined : T extends StreamResponseRoute<HttpMethod, string, ZodType | undefined, ZodType | undefined, infer B> ? [B] extends [ZodType] ? B['_output'] : undefined : undefined;
 /**
  * 从路由定义中推断响应数据类型
  *
@@ -2006,7 +2007,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 版本号类型
  *
@@ -2028,134 +2029,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 方法
    */
@@ -2177,9 +2120,13 @@ type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends st
    */
   body?: TBody;
   /**
-   * 响应 Schema
+   * 响应类型标记：二进制流，显式必填
    */
-  response: TResponse;
+  responseType: 'stream';
+  /**
+   * 流式响应元数据
+   */
+  stream: StreamResponseMeta;
   /**
    * 接口摘要描述
    */
@@ -2198,30 +2145,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>;
 };
 /**
  * 已处理的路由类型
@@ -2331,6 +2325,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.1",
+  "version": "0.1.3",
   "keywords": [
     "api",
     "contract",