为何TypeScript动态属性赋值在单对象生效，数组却报错？

这是针对此前问题的跟进提问：为何函数参数为单个对象时，动态根据条件设置属性并返回正确类型的方案可行，但参数为数组时却失效？

示例代码 #

export enum ResidenceStatusType {
    NOT_REGISTERT_AT_ADDRESS = "NOT_REGISTERT_AT_ADDRESS",
    REGISTERT_AT_ADDRESS = "REGISTERT_AT_ADDRESS",
}
export enum CivilStatusType {
    MARRIED = "MARRIED",
    NOT_MARRIED = "NOT_MARRIED",
}
export enum Source {
    PRIVATE = "PRIVATE",
    PUBLIC = "PUBLIC",
}
export interface ResidencePeriodDto {
    dateFrom?: string;
    dateTo?: string;
    residenceStatus: ResidenceStatusType;
    source: Source;
}
export interface CivilPeriodDto {
    dateFrom?: string;
    dateTo?: string;
    civilStatus: CivilStatusType;
    source: Source;
}

const isResidencePeriod = (periods: CivilPeriodDto | ResidencePeriodDto): periods is ResidencePeriodDto => periods.hasOwnProperty('residenceStatus')

function testFunc(periods: ResidencePeriodDto[]): ResidencePeriodDto[]
function testFunc(periods: CivilPeriodDto[]): CivilPeriodDto[]
function testFunc(periods: ResidencePeriodDto[] | CivilPeriodDto[]): ResidencePeriodDto[] | CivilPeriodDto[] {
  return [{
    dateFrom: "01.01.2023",
    dateTo: "31.12.2023",
    ...("residenceStatus" in periods
        ? { residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS  }
        : { civilStatus: CivilStatusType.MARRIED }
    ),
    source: Source.PRIVATE
  }]
}

const civilPeriod = [{
    dateFrom: "01.01.2023",
    dateTo: "31.12.2023",
    civilStatus: CivilStatusType.MARRIED,
    source: Source.PRIVATE
}]

const residencePeriod = [{
    dateFrom: "01.01.2023",
    dateTo: "31.12.2023",
    residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS,
    source: Source.PRIVATE
}]

testFunc(civilPeriod)
testFunc(residencePeriod)

类型错误信息 #

Type '({ source: Source.PRIVATE; residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS; dateFrom: string; dateTo: string; } | { source: Source.PRIVATE; civilStatus: CivilStatusType.MARRIED; dateFrom: string; dateTo: string; })[]' is not assignable to type 'ResidencePeriodDto[] | CivilPeriodDto[]'.
  Type '({ source: Source.PRIVATE; residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS; dateFrom: string; dateTo: string; } | { source: Source.PRIVATE; civilStatus: CivilStatusType.MARRIED; dateFrom: string; dateTo: string; })[]' is not assignable to type 'ResidencePeriodDto[]'.
    Type '{ source: Source.PRIVATE; residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS; dateFrom: string; dateTo: string; } | { source: Source.PRIVATE; civilStatus: CivilStatusType.MARRIED; dateFrom: string; dateTo: string; }' is not assignable to type 'ResidencePeriodDto'.
      Property 'residenceStatus' is missing in type '{ source: Source.PRIVATE; civilStatus: CivilStatusType.MARRIED; dateFrom: string; dateTo: string; }' but required in type 'ResidencePeriodDto'.

原因与解决方案 #

原因分析 #

1. 判断逻辑错误：当前代码用"residenceStatus" in periods判断数组对象本身，但数组作为容器并没有residenceStatus或civilStatus属性，导致条件永远为false，返回的对象始终带有civilStatus，与函数签名要求的返回类型不匹配。
2. 数组联合类型收窄限制：即使修正判断逻辑，TypeScript对数组联合类型的自动收窄能力较弱，仅通过单个元素的类型判断无法将ResidencePeriodDto[] | CivilPeriodDto[]收窄到具体的数组类型，需要显式的数组类型守卫。

解决步骤 #

1. 添加数组类型守卫

创建针对数组的类型守卫函数，用于判断传入的数组属于哪种类型：

const isResidencePeriodArray = (periods: ResidencePeriodDto[] | CivilPeriodDto[]): periods is ResidencePeriodDto[] => {
  // 若数组为空，可根据业务逻辑调整判断规则
  return periods.length > 0 && 'residenceStatus' in periods[0];
};

2. 修正函数逻辑

在函数内部使用数组类型守卫完成类型收窄，确保返回的数组类型与输入一致：

function testFunc(periods: ResidencePeriodDto[]): ResidencePeriodDto[]
function testFunc(periods: CivilPeriodDto[]): CivilPeriodDto[]
function testFunc(periods: ResidencePeriodDto[] | CivilPeriodDto[]): ResidencePeriodDto[] | CivilPeriodDto[] {
  if (isResidencePeriodArray(periods)) {
    return [{
      dateFrom: "01.01.2023",
      dateTo: "31.12.2023",
      residenceStatus: ResidenceStatusType.NOT_REGISTERT_AT_ADDRESS,
      source: Source.PRIVATE
    }];
  } else {
    return [{
      dateFrom: "01.01.2023",
      dateTo: "31.12.2023",
      civilStatus: CivilStatusType.MARRIED,
      source: Source.PRIVATE
    }];
  }
}

补充说明

单个对象参数时能正常工作，是因为类型守卫直接作用于对象本身，TypeScript可以正确收窄对象的联合类型；而数组作为容器，需要针对数组整体的类型守卫，才能让TypeScript识别出具体的数组类型，进而匹配返回值的类型要求。

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