我所理解的 TypeScript 最佳实践(20):用逆向映射推断还原字段类型
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型(当前)
写一个接收对象的工具函数时,调用方有时会传来包装后的字段。例如,每个字段都是 { 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 }>。检查器先根据实参发现两个键,再把每个源字段和参数里的包装结构对应起来:
age的源类型是{ value: number },目标形状是Box<T['age']>,因此为T['age']推断出number。name的源类型是{ value: string },目标形状是Box<T['name']>,因此为T['name']推断出string。- 把这些字段组合起来,得到
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 修复分析中。