TypeScript flatMap类型推断失效，为何需显式指定泛型？

问题重现 #

以下代码中，flatMap 触发类型错误：

type ApiItem = Record<string, unknown>;
type CSVItem = Record<string, unknown>;
type Model = { converter: (item: ApiItem) => CSVItem | CSVItem[] };

function convertItems(model: Model, { main }: { main: ApiItem[] }): CSVItem[] {
    const { converter } = model;

    return main.flatMap((item) => converter(item)); // 类型错误
}

错误信息：

Type 'unknown[]' is not assignable to type 'CSVItem[]'.
Type 'unknown' is not assignable to type 'CSVItem'.

手动指定 flatMap 的泛型参数后代码正常运行：

return main.flatMap<CSVItem>((item) => converter(item));

原因分析 #

TypeScript 对 Array.flatMap 的类型推断在处理返回值为单个元素与数组的联合类型时存在局限：

1. flatMap 的类型定义要求回调函数返回 U | Iterable<U>，其中 U 是最终展开后的元素类型。
2. 你的 converter 返回 CSVItem | CSVItem[]，理论上 CSVItem[] 属于 Iterable<CSVItem>，TS 应该能推断出 U = CSVItem。但由于 CSVItem 是 Record<string, unknown>（内部值为 unknown），TS 的类型推断器无法自动将联合类型 CSVItem | CSVItem[] 与 U | Iterable<U> 做精确匹配，反而 fallback 到了更宽泛的 unknown 类型。

简单来说：TS 没认出 CSVItem[] 就是 Iterable<CSVItem>，导致它无法正确锁定 U 的类型，只能给出 unknown。

解决方案 #

除了手动指定泛型参数 <CSVItem>，还可以调整 Model 的类型定义，让推断更明确：

// 把返回类型改为 CSVItem | Iterable<CSVItem>，明确告知TS这是可迭代的CSVItem集合
type Model = { converter: (item: ApiItem) => CSVItem | Iterable<CSVItem> };

function convertItems(model: Model, { main }: { main: ApiItem[] }): CSVItem[] {
    const { converter } = model;
    return main.flatMap((item) => converter(item)); // 无需手动指定泛型，推断正常
}

这样修改后，TS 能直接识别回调返回值符合 U | Iterable<U> 的结构，自动推断出 U = CSVItem。

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