TypeScript联合类型同步问题：FilterMap类型兼容方案咨询

问题重现 #

假设你的联合类型定义如下，hasPartial标志决定了filters的属性值是否允许undefined：

type FilterProps = 
  | { hasPartial: false; filters: Record<string, string> }
  | { hasPartial: true; filters: Record<string, string | undefined> };

当实现批量处理filters的FilterMap函数时，直接访问props.filters会触发类型不兼容错误——TypeScript无法自动关联hasPartial的取值和filters的类型：

// 错误示例：TS无法识别hasPartial与filters的同步关系
function FilterMap(props: FilterProps) {
  return Object.entries(props.filters).map(([key, value]) => {
    if (props.hasPartial) {
      return `${key}: ${value ?? 'N/A'}`; 
      // TS提示：value可能为string，但这里期望允许undefined
    } else {
      return `${key}: ${value}`;
      // TS提示：value可能为undefined，但此时hasPartial为false，filters值应为string
    }
  });
}

优雅解决方案：泛型绑定类型关系 #

使用泛型将hasPartial的布尔类型与filters的类型做条件绑定，让TypeScript可以精准追踪两者的关联，无需冗余判断或any断言：

步骤1：定义泛型基础类型（可选，便于复用）

// 用泛型T绑定hasPartial和filters的类型关系
type BaseFilterProps<T extends boolean> = {
  hasPartial: T;
  filters: T extends true 
    ? Record<string, string | undefined> 
    : Record<string, string>;
};

// 保留原联合类型作为对外暴露的类型（可选）
type FilterProps = BaseFilterProps<true> | BaseFilterProps<false>;

步骤2：实现泛型处理函数

function FilterMap<T extends boolean>(props: BaseFilterProps<T>) {
  return Object.entries(props.filters).map(([key, value]) => {
    if (props.hasPartial) {
      // TS自动识别：value为string | undefined
      return `${key}: ${value ?? 'N/A'}`;
    } else {
      // TS自动识别：value为string
      return `${key}: ${value}`;
    }
  });
}

调用示例（无类型错误）

const strictResult = FilterMap({ 
  hasPartial: false, 
  filters: { name: 'Alice', age: '30' } 
});

const partialResult = FilterMap({ 
  hasPartial: true, 
  filters: { name: 'Bob', age: undefined } 
});

替代方案：解构触发类型窄化 #

如果场景简单，也可以通过解构分离hasPartial和filters，让TypeScript自动关联两者的类型关系：

function FilterMap(props: FilterProps) {
  const { hasPartial, filters } = props; // 解构后TS会自动跟踪类型关联
  return Object.entries(filters).map(([key, value]) => {
    if (hasPartial) {
      return `${key}: ${value ?? 'N/A'}`;
    } else {
      return `${key}: ${value}`;
    }
  });
}

原理说明 #

• 原联合类型的问题在于：TypeScript对整个对象的类型窄化存在局限性，仅检查props.hasPartial时，无法自动同步窄化props.filters的类型。
• 泛型方案通过将hasPartial的布尔值作为泛型参数，直接在类型层面绑定filters的结构，让TypeScript可以在编译期精准推断每个分支的类型。
• 解构方案则利用了TypeScript的关联类型窄化特性：当从联合类型对象中解构出多个属性后，检查其中一个属性的取值，会自动同步窄化其他关联属性的类型。

内容的提问来源于stack exchange，提问作者Evyatar Shafran