如何通过TypeScript工具函数正确收窄联合类型适配第三方库？

问题场景 #

对接第三方库时遇到联合类型收窄问题，示例代码如下：

// 第三方函数：只能配置detail的类型，无法修改实现
const reply = (detail: { status: 400 } | { status: 403; cause: string }) => {
  return true;
};

// 自定义工具函数
type Param<S, C> = {
  status: S;
} & (C extends string ? { cause: C } : unknown);

const getDetail = <S, C>(param: Param<S, C>) => {
  return param;
};

const test1 = getDetail({ status: 400 } as const);
// { status: 400 } 类型正常
const test2 = getDetail({ status: 403, cause: "no-permission" } as const);
// { status: 403, cause: "no-permission" } 类型正常

// 报错场景
reply(getDetail({ status: 400 }));
// 错误提示：
// Argument of type '{ status: 400; }' is not assignable to parameter of type 'Param<400, string>'.
// Property 'cause' is missing in type '{ status: 400; }' but required in type '{ cause: string; }'.ts(2345)

问题核心是原Param类型未建立status与cause的关联逻辑，导致TypeScript无法正确推断类型结构，无法匹配reply的联合参数要求。

解决方案 #

方案1：直接复用第三方联合类型 #

既然reply的参数类型是固定的联合结构，直接提取并复用该类型作为工具函数的约束：

// 提取第三方函数的参数类型
type ReplyDetail = Parameters<typeof reply>[0];

const getDetail = <T extends ReplyDetail>(param: T) => {
  return param;
};

// 调用正常
reply(getDetail({ status: 400 }));
reply(getDetail({ status: 403, cause: "no-permission" }));

方案2：显式定义关联的联合类型 #

自定义参数类型时，直接明确status值与cause属性的对应关系：

type Param = 
  | { status: 400 }
  | { status: 403; cause: string };

const getDetail = <T extends Param>(param: T) => {
  return param;
};

// 调用正常
reply(getDetail({ status: 400 }));
reply(getDetail({ status: 403, cause: "no-permission" }));

方案3：用条件类型建立泛型关联 #

如果需要保留泛型灵活性，通过条件类型让cause的存在依赖于status的值：

type Param<S> = 
  S extends 400 ? { status: S } : 
  S extends 403 ? { status: S; cause: string } : 
  never;

const getDetail = <S extends 400 | 403>(param: Param<S>) => {
  return param;
};

// 调用正常
reply(getDetail({ status: 400 }));
reply(getDetail({ status: 403, cause: "no-permission" }));

原理说明 #

原Param<S, C>泛型中，S和C是独立的泛型参数，TypeScript无法推断两者的关联关系，导致调用getDetail({ status: 400 })时默认将C推断为string，进而要求必须传入cause属性。上述方案要么复用已有联合类型，要么通过条件类型显式绑定status与cause的依赖，让TypeScript能正确识别对应类型结构。

内容的提问来源于stack exchange，提问作者Bright Lee