TypeScript为何未检测映射函数中新增的非法属性？

我编写了一个格式化数据的函数，其中TextBox的values结构已通过TextBoxValue明确定义，但在映射这些值时，TypeScript未检测到新增的非法属性foo，而另一个返回分支里直接创建对象时却报错了。代码示例如下：

type TextBoxValue = {
  text: string;
}
type TextBox = {
  values: TextBoxValue[];
}
type Result = {
  result: string | object;
}

const getTheValue = (): Result => ({ result: 'This comes from a child process.' });

const formatTextBox = (textbox: TextBox): TextBox => {
  const { result } = getTheValue();
  const originalValue = textbox.values[0];

  if (typeof result === 'object') {
    const arr = Array.isArray(result) ? result : [result];
    return {
      ...textbox,
      values: arr.map(res => {
        return { 
          foo: 'bar', // 此处未报错
          text: res.text || originalValue.text,
        };
      })
    }
  }

  return {
    ...textbox,
    values: [{ 
      ...originalValue, 
      foo: 'bar', // 此处报错
      text: String(result) 
    }]
  }
}

问题原因 #

这是由于TypeScript的上下文类型推断和额外属性检查的行为差异导致的：

1. 直接赋值分支的严格检查
   在第二个返回分支中，values被直接赋值为[{ ...originalValue, foo: 'bar', ... }]，这个数组的元素被TypeScript直接关联到TextBoxValue类型（因为TextBox['values']明确是TextBoxValue[]）。此时对象字面量是直接赋值给一个明确的类型位置，TypeScript会触发额外属性检查——这是专门针对对象字面量的严格检查，会阻止添加目标类型中未定义的属性，所以foo会被检测为非法。

2. map回调的类型兼容逻辑
   在第一个返回分支的arr.map(res => { ... })中，arr的类型是object[]（因为result是object类型，转换为数组后是object[]）。map回调返回的对象字面量会先被TypeScript推断为{ foo: string; text: string }，而这个类型结构兼容TextBoxValue（包含了TextBoxValue要求的text属性）。由于TypeScript的结构类型系统允许兼容类型赋值，且这里的对象是通过回调返回的推断类型，而非直接赋值给明确类型的字面量，所以不会触发额外属性检查，因此foo不会被报错。

解决方案 #

如果需要在map回调中也触发非法属性检查，可以通过以下方式：

• 显式指定回调返回类型：
  明确告诉TypeScript回调的返回值必须是TextBoxValue，这样会强制检查属性合法性：

  values: arr.map((res): TextBoxValue => {
    return { 
      foo: 'bar', // 此时会报错
      text: res.text || originalValue.text,
    };
  })
  

• 使用satisfies约束字面量：
  用satisfies关键字强制对象字面量符合TextBoxValue类型，同时保留推断的灵活性：

  return { 
    foo: 'bar', // 此时会报错
    text: res.text || originalValue.text,
  } satisfies TextBoxValue;
  

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