跳到正文

我所理解的 TypeScript 最佳实践(20):用逆向映射推断还原字段类型

我所理解的 TypeScript 最佳实践

  1. 为什么选择 TypeScript
  2. 严格模式
  3. 使用常量枚举来管理状态
  4. 按运行环境处理 TypeScript 代码
  5. 类型检查、Lint 与测试
  6. TypeScript 7 升级与工具链兼容
  7. 用 satisfies 检查类型并保留推断
  8. 用 import type 区分类型依赖和运行时依赖
  9. 用对象类型表达字段约束
  10. 用联合类型表达备选,用交集类型叠加约束
  11. 用元组描述位置固定的数据
  12. 用泛型保留类型关系,用 extends 写约束和条件
  13. 按目标类型判断赋值是否成立
  14. 按输入和输出设计泛型的协变与逆变
  15. 先校验外部数据,再使用收窄后的类型
  16. 让局部实现保留推断,用注解约束公开接口
  17. 从一份定义派生配置、命令和事件的类型
  18. 用判别联合排除互斥的状态组合
  19. 用 never 表示没有值的类型
  20. 用逆向映射推断还原字段类型(当前)

写一个接收对象的工具函数时,调用方有时会传来包装后的字段。例如,每个字段都是 { value: 原始值 },每个字段都是返回值的函数,或者每个字段都是解析器。函数需要根据这些字段推断结果对象的类型,让调用方不用再手写一份泛型参数。

TypeScript 的逆向映射推断可以处理其中一些场景。它根据参数里的映射关系,逐字段推断映射前的对象类型。这个机制适合设计对象转换、配置和 Schema API,也能解释为什么 Vue 的 toRefs() 参数增加一层映射后,某些泛型 props 能恢复数组推断。

本文先从普通对象讲起。示例结果在 TypeScript 6.0.3 和 7.0.2 的 strict 模式下验证。代码里的 declare function 只描述函数的类型契约,不提供运行时实现;需要实现函数时,仍要真正遍历字段、读取包装值或调用解析器。

从包装字段推断原始对象

先看正向变换。Box<Value> 给一个值加上 value 字段;BoxFields<T> 则把对象 T 的每个字段都做一次这样的包装。

// 用 value 字段包装一个值。
type Box<Value> = { value: Value };

// 保留原对象的键,把每个字段的值包进 Box。
type BoxFields<T> = {
  [Key in keyof T]: Box<T[Key]>;
};

// 描述原始资料的字段。
type Profile = {
  age: number;
  name: string;
};

type Wrapped = BoxFields<Profile>; // { age: Box<number>; name: Box<string> }

这里的方向很明确:已经知道 T 是 Profile,按 keyof T 取出 age 和 name,再分别计算 Box<T['age']> 和 Box<T['name']>。

逆向推断面对的是另一种输入。调用方已经有包装后的对象,希望检查器反推出包装前的 T。

// 根据各字段的 Box 内容,推断拆箱后的对象类型。
declare function unboxFields<T>(input: BoxFields<T>): T;

const profile = unboxFields({
  age: { value: 18 },
  name: { value: 'Ada' },
}); // { age: number; name: string }

const age = profile.age; // number
const name = profile.name; // string

这一调用没有提供 <{ age: number; name: string }>。检查器先根据实参发现两个键,再把每个源字段和参数里的包装结构对应起来:

  1. age 的源类型是 { value: number },目标形状是 Box<T['age']>,因此为 T['age'] 推断出 number。
  2. name 的源类型是 { value: string },目标形状是 Box<T['name']>,因此为 T['name'] 推断出 string。
  3. 把这些字段组合起来,得到 T = { age: number; name: string },再用它检查参数和计算返回类型。

正向映射从 T 计算包装结果,逆向推断从包装结果寻找 T。这个过程利用了具体的字段关系;并不是任意类型运算都有唯一的逆运算。

这个机制来自同态映射类型的推断设计

TypeScript 在 2.1 引入映射类型。最初的映射类型 PR #12114 讨论了如何从已有对象类型派生逐字段变换。随后,PR #12528 在 2016 年 11 月加入了同态映射类型的推断,其中就有 Box 和逐字段拆箱的例子。

同态映射通常写成 { [Key in keyof T]: 某种涉及 T[Key] 的变换 }:它沿着原对象的键逐字段变换,并按映射的声明处理字段修饰符。关于 keyof、索引访问和映射类型的基础语法,可以先看第九篇。

#12528 对推断过程给出了一个关键说明:推断映射前的对象时,检查器把模板中的 T[Key] 当作一个等待推断的类型位置。可以先把它理解为「这一格原来是什么类型」。源对象各字段提供候选结果,最后再合成对象。TypeScript 的检查器推断说明也用拆箱例子描述了这种逐成员推断。

因此,参数中的 T[Key] 此时承担了特殊的任务:T 还没确定,检查器正在根据实参寻找它。等这次推断结束,返回类型里的 T 就使用得到的结果。这也解释了为什么下面两种写法可能不同。

// 根据映射后的字段直接推断原对象 T。
declare function unboxDirect<T>(input: BoxFields<T>): T;

// 先推断 Input,再要求它满足 BoxFields<T> 的约束。
declare function unboxIndirect<T, Input extends BoxFields<T>>(input: Input): T;

const direct = unboxDirect({ age: { value: 18 } }); // { age: number }
const indirect = unboxIndirect({ age: { value: 18 } }); // unknown

第二个参数类型直接提到的是 Input,映射关系藏在另一个泛型的约束里。在这个例子中,检查器推断出了 Input,却没有从它反推出 T。extends 约束可以检查类型是否满足要求,但这份声明没有取得和第一种写法相同的推断结果。

Anders 在#12528 的讨论中建议减少多余的类型参数,把关系表达在实际参数类型上。实际设计 API 时,可以先尝试只保留需要推断的对象,把每个字段如何关联结果写进参数。复杂约束仍有自己的用途,但应当用真实调用检查推断效果,不能仅凭约束看起来等价就认为结果相同。

用返回值函数和解析器描述字段关系

拆箱是最容易观察的例子。日常代码里,同样的机制可以用于收集一组 getter 的结果。

// 从每个函数的返回值推断结果对象的对应字段。
declare function collect<T>(input: {
  [Key in keyof T]: () => T[Key];
}): T;

const result = collect({
  count: () => 1,
  title: () => 'Ready',
}); // { count: number; title: string }

现在源字段是函数,参数模板是 () => T[Key]。检查器对照返回类型,为 T['count'] 推断 number,为 T['title'] 推断 string。调用方提供一份函数表,就能同时确定结果对象的字段。

解析配置时,也可以让每个字段提供一个解析器。每个解析器接收原始文本,并返回这一项真正的数据。

// 描述一个把文本解析成 Value 的解析器。
type Decoder<Value> = {
  parse: (input: string) => Value;
};

// 根据解析器的输出类型推断完整配置。
declare function decodeFields<T>(schema: {
  [Key in keyof T]: Decoder<T[Key]>;
}): T;

const config = decodeFields({
  enabled: { parse: (input: string) => input === 'true' },
  port: { parse: (input: string) => Number(input) },
}); // { enabled: boolean; port: number }

这里描述的是类型关系。运行时仍需要从文本来源读取每个配置项,并调用相应的 parse;Number(input) 得到 NaN 时如何处理,也需要实现约定。类型推断不会替代外部数据校验。

如果一个普通函数只接收已经明确的对象并返回原对象,就直接写 input: T。只有 API 确实需要从逐字段包装或回调中推断结果时,才需要考虑这样的映射参数。

模板必须提供足够的字段信息

逆向推断需要从源字段找到原字段类型。只有键对应上,但模板里没有能够推断 T[Key] 的位置,就得不到字段值的类型。

// 只把每个键映射成 boolean,没有描述原字段的值类型。
declare function inferFlags<T>(flags: {
  [Key in keyof T]: boolean;
}): T;

const flags = inferFlags({
  count: true,
  title: false,
}); // { count: unknown; title: unknown }

count: true 只能证明这一格接受布尔值,无法说明映射前的 count 是数字、字符串还是别的类型。于是检查器找到了键,却只能把对应值留作 unknown。这也是设计 Schema API 时要明确输入和输出关系的原因。

字段间互相依赖的回调会带来额外困难。例如,一个回调产生类型,另一个尚未获得上下文类型的回调又需要消费它,推断可能依赖检查器的处理顺序。#53018 讨论了这一类逆向映射与表达式内推断的限制。上面的独立 getter 和解析器有直接的返回类型来源,不能据此推导出任意相互依赖的回调都会得到相同效果。

显式泛型参数会固定要使用的类型

调用方如果手动提供类型参数,检查器就按这份类型检查。这个原则在处理复杂泛型对象时尤其重要:逆向推断能换一个逐字段的输入类型,但显式固定输入后,就没有同样的推断空间了。

// 根据输入对象的各个字段推断 ObjectType。
declare function inferFields<ObjectType extends object>(input: {
  [Key in keyof ObjectType]: ObjectType[Key];
}): ObjectType;

const inferred = inferFields({ count: 1 }); // { count: number }
const fixed = inferFields<{ count: number | undefined }>({ count: 1 }); // { count: number | undefined }

第二个调用里的值确实是 1,但调用方已经选择了包含 undefined 的对象类型,返回值就沿用这个契约。如果传入的原对象类型本来含有待定的交集索引,显式写 <typeof 原对象> 也会把那个原类型带进返回类型。它不会因为参数中有一层映射,就必然被重新计算成普通字段。

保留键的映射也有可推断范围

同态映射最常见的写法保留 keyof T。键重映射则通过 as 改变键,可能重命名、筛选或合并字段。它和普通同态映射不能随意互换。

// 直接使用原来的键,为值保留推断位置。
declare function inferPlain<T>(input: {
  [Key in keyof T]: T[Key];
}): T;

// 使用键重映射语法,虽然这里仍写回同一个 Key。
declare function inferRemapped<T>(input: {
  [Key in keyof T as Key]: T[Key];
}): T;

const plain = inferPlain({ count: 1 }); // { count: number }
const remapped = inferRemapped({ count: 1 }); // unknown

这个对照在本文验证的两个版本上结果一致。即使 as Key 看起来没有改变结果类型,检查器也没有走出相同的反向推断结果。设计这类 API 时,应当保留能直接推断的输入关系,需要的键重命名可以另行表达,再用实际调用验证。

字段修饰符也要按声明理解。PR #12589 专门调整过这部分:如果目标映射显式添加了 readonly 或 ?,逆向推断时可以把这些修饰符视为映射加上去的,再从待推断的源对象里去掉。因此,「用映射推断原对象」不等于任何映射都原样保留源字段的可选性和只读性。

用输入推断改善 Vue 的字段类型

Vue 的泛型 props 问题提供了另一种用途。原来的 toRefs() 直接接收整个对象类型,返回 ToRefs<ObjectType>。在某些泛型 props 中,整份类型带有尚未确定的布尔键映射,结果索引 ObjectType['options'] 也留到后面计算。

候选修复在参数处给检查器一个同态映射目标,让它根据实参字段推断新的 ObjectType。

declare function toRefs<ObjectType extends object>(object: {
  [Key in keyof ObjectType]: ObjectType[Key];
}): ToRefs<ObjectType>;

参数中的 ObjectType[Key] 是等待推断的字段位置。调用结束后,返回类型使用这一轮推断结果。在复现用例中,options 被推断成明确的数组,后续 ToRef 就能排除「输入本身已经是 Ref」的分支。

可以用同一份 props 对照三种调用。下面的结果针对带逆向映射重载的 Vue 候选声明;普通函数只用于观察类型,实际组件中的宏仍放在 <script setup> 顶层。

import { defineProps, toRefs } from 'vue';

// 描述选择器的一个选项。
type Option<Value> = { value: Value };

// 让候选项和当前值使用同一个类型参数。
type Props<Value> = {
  options: readonly Option<Value>[];
  value: Value;
};

// 对照自动推断、指定原类型和指定普通字段形状。
function inspectCalls<Value>() {
  const props = defineProps<Props<Value>>(); // 原来的 DefineProps 交集类型。

  const inferred = toRefs(props); // 根据实参逐字段推断新的 ObjectType。
  const fixedOriginal = toRefs<typeof props>(props); // ObjectType 被指定为原来的交集。
  const fixedShape = toRefs<{
    readonly options: readonly Option<Value>[];
    readonly value: Value;
  }>(props); // ObjectType 被指定为这份普通对象类型。

  const inferredOptions = inferred.options.value; // readonly Option<Value>[]
  const originalOptions = fixedOriginal.options.value; // any
  const shapeOptions = fixedShape.options.value; // readonly Option<Value>[]
}

第一种调用没有指定 ObjectType。检查器根据实参字段,为这一轮调用推断出 { readonly options: readonly Option<Value>[]; readonly value: Value }。后续 ToRefs<ObjectType> 使用的是这份新对象类型,options 的外层已经明确是数组。元素里的 Value 仍是泛型,不妨碍排除数组本身是 Ref 的分支。

第二种调用已经指定 ObjectType = typeof props,因此返回类型继续使用 ToRefs<typeof props>。参数里的映射仍用于描述和检查输入,却不会把返回类型中的 ObjectType 替换成一份展开后的对象。原来的交集及其待定索引继续传给 ToRef,所以这组复现读取 .value 时仍得到 any。

第三种调用说明,显式类型参数本身也可以得到数组。这里指定的就是普通对象类型,返回类型使用它,自然能直接取得明确的 options 字段。

调用 交给 ToRefs 的对象类型 options.value
toRefs(props) 根据实参逐字段推断出的新对象类型 readonly Option<Value>[]
toRefs<typeof props>(props) 原来的 props 交集类型 any
toRefs<明确字段形状>(props) 显式指定的普通对象类型 readonly Option<Value>[]

原来的 typeof props 在三种调用中都没有改变。自动推断改善的是这次调用选用的类型参数,并没有把原交集展开或改写。上表也不表示只要写映射参数,就能化简任何待定类型;它记录的是这份 props 在候选重载下的推断结果。

这里改善的是一次函数调用的输入推断。[X] extends [Ref] 仍然是控制条件分支和联合分配的写法;逆向映射也没有要求检查器强行展开任意泛型类型。返回类型同样可能参与其他形式的上下文推断,需要按所在调用分析。

现有公共 API 还要考虑数组索引、元组和私有品牌。只把原签名换成上面这一条,可能改变其他输入的推断或让它不再匹配。Vue 候选因此保留了数字索引入口和原签名回退。完整的 props 输入、三条重载、兼容性用例,以及显式写 toRefs<typeof props>() 的边界,放在 Vue 修复分析中。