Flow 中的实用类型(Utility Types)与 TypeScript 转换实践:以 utility_types_filter_collections 评测为例
Flow 中的实用类型(Utility Types)与 TypeScript 转换实践:以 utility_types_filter_collections 评测为例
本篇文章以当前仓库 Flow AI Evals 评测套件中的 evals/evals/04_ts_to_flow/utility_types_filter_collections 任务为切入口,系统讲解 Flow 中对 Exclude、Extract、Required、Awaited、ReadonlyMap、ReadonlySet、NoInfer 等实用类型的原生支持与底层实现,并结合参考解法与 AST 评测规则,说明如何把一段 TypeScript 模块"逐类型保真"地移植为符合现代规范的 idiomatic Flow。读完本文,你将掌握 TS→Flow 转换中实用类型、只读集合类型与泛型约束的对应关系,理解为何现代 Flow 禁止 $ 前缀旧拼写,并能独立运行该评测验证转换结果。
一、任务背景:这个评测在测什么
utility_types_filter_collections 位于评测分类 04_ts_to_flow,该分类的定位是把一段 TypeScript 程序移植为"惯用的、现代的 Flow"(idiomatic Flow)。与"根据自然语言规格书写 Flow"的评测不同,这里的核心挑战是转换:TypeScript 中有不少惯用法在 Flow 中并没有 1:1 对应物(如函数重载、数组协变、泛型索引访问写入、品牌类型),而本评测恰好选取了那些两边都存在、但拼写与语义细节不同的实用类型场景。
每个评测目录遵循统一的 SWE-bench 风格布局:
utility_types_filter_collections/
├── prompt.md # 任务描述(即本次关联文档)
├── config.json # 元数据 + 评测器(flow_check + AST 查询)
├── input/
│ ├── source.ts # 待转换的 TypeScript(评测器惰性,不进入补丁)
│ ├── main.js # 带 // @flow 的 TODO 占位
└── ideal/
└── main.js # 参考解法(gold patch)
关联文档 prompt.md 全文只有一句话:
The file
source.tscontains a TypeScript module. Convert it to idiomatic Flow inmain.js, preserving the runtime behavior and the precision of every type.
这段描述浓缩了评测的两个硬性约束:运行时行为不变(语义改动不被允许,类型层面的选择如 ReadonlyArray 可以接受)与类型精度不丢失(每种类型都要完整保留其约束力)。同时,prompt 刻意不点名任何具体构造,因为"idiomatic Flow"的判定标准由 config.json 中的 AST 评测器强制执行。
二、逐行对照:从 TypeScript 到 Flow 的实用类型映射
input/source.ts 是一段模拟"通知渠道"场景的模块。下面把它与参考解法 ideal/main.js 逐段对照,理解每处转换背后的原理。
1. 字面量联合类型与 Exclude / Extract
TypeScript 侧:
type Channel = "email" | "sms" | "push" | "webhook";
type PublicChannel = Exclude<Channel, "webhook">;
type InstantChannel = Extract<Channel, "sms" | "push">;
Flow 侧:
type Channel = 'email' | 'sms' | 'push' | 'webhook';
type PublicChannel = Exclude<Channel, 'webhook'>;
type InstantChannel = Extract<Channel, 'sms' | 'push'>;
转换要点:
- 字符串字面量从双引号改为单引号:这是 Flow 社区代码风格的默认偏好,两种引号在语义上等价,但 idiomatic Flow 统一使用单引号;
Exclude与Extract在 Flow 中是一等公民,无需引入任何 polyfill。查看 Flow 内置库 lib/lib.es5.js,可以看到它们的条件类型实现:
type Exclude<T, U> = T extends U ? empty : T;
type Extract<T, U> = T extends U ? T : empty;
即 Exclude 从联合类型 T 中剔除可赋给 U 的分支,Extract 则保留这些分支,二者互为对偶。因此 PublicChannel 收敛为 'email' | 'sms' | 'push',InstantChannel 收敛为 'sms' | 'push'。注意底层用 empty(不可达类型/底部类型)作为排除分支的产物,这保证了被剔除的类型不会残留任何可赋值性。
2. interface → 对象类型 + Required
TypeScript 侧:
interface ChannelConfig {
retries?: number;
timeoutMs?: number;
}
type ResolvedConfig = Required<ChannelConfig>;
Flow 侧:
type ChannelConfig = {
retries?: number,
timeoutMs?: number,
};
type ResolvedConfig = Required<ChannelConfig>;
转换要点:
interface改写为 Flow 对象类型字面量:Flow 中声明对象形状的惯用方式就是对象类型,成员之间以逗号分隔;interface关键字仅用于声明合并、实现等特定场景;Required<...>原样保留:Required会把所有可选属性(?)变为必选。转换后ResolvedConfig要求retries与timeoutMs都必须存在,这解释了后续describe函数中config.retries与config.timeoutMs为什么可以直接访问而不必判空;- 值得强调的是,
Required与Exclude/Extract一样都是 Flow 内置的实用类型,直接可用,无需手写$ObjMap之类的底层映射。
3. declare function + Awaited<ReturnType<typeof ...>>
TypeScript 侧:
declare function send(channel: PublicChannel): Promise<boolean>;
type SendResult = Awaited<ReturnType<typeof send>>;
Flow 侧:
declare function send(channel: PublicChannel): Promise<boolean>;
type SendResult = Awaited<ReturnType<typeof send>>;
转换要点:
declare function直接保留:用于声明一个没有函数体的函数签名,两侧语法一致;ReturnType<typeof send>保留:typeof在类型位置提取send的函数类型,ReturnType取其返回值类型,即Promise<boolean>;Awaited<...>保留:把Promise<boolean>展开为boolean。Flow 内置库 lib/lib.es5.js 中的实现为:
type Awaited<T> = T extends Promise<infer U> ? U : T;
它通过 infer U 从 Promise 中提取内部类型;非 Promise 类型则原样返回。因此 SendResult 最终等于 boolean,与后续 const result: SendResult = true; 形成对照——若把 Awaited 漏掉,result 的类型就会是 Promise<boolean>,赋值 true 将无法通过类型检查。保留 Awaited 不是风格问题,而是类型精度问题。
4. ReadonlyMap / ReadonlySet:现代拼写与 $ 前缀的底层关系
TypeScript 侧:
type RateLimits = ReadonlyMap<Channel, number>;
type Enabled = ReadonlySet<PublicChannel>;
Flow 侧:
type RateLimits = ReadonlyMap<Channel, number>;
type Enabled = ReadonlySet<PublicChannel>;
这里表面上看"什么都没改",但它恰恰是评测中最容易被忽略的考点。查看 Flow 内置集合库 lib/lib.es2015.collection.js:
type ReadonlyMap<K, out V> = $ReadOnlyMap<K, V>;
type ReadonlySet<out V> = $ReadOnlySet<V>;
ReadonlyMap/ReadonlySet是现代拼写的别名,内部转写为$ReadOnlyMap/$ReadOnlySet,并带有out(协变)变型标注;- 在 04_ts_to_flow 分类的设计说明 中明确写到:
flow check会对$ReadOnly、$ReadOnlyArray、$NonMaybeType、mixed、+变型、<T: Bound>等废弃拼写直接报错。因此,把 TypeScript 的ReadonlyMap机械地翻译成$ReadOnlyMap反而会让评测失败——正确的做法是保留现代形式,让 Flow 内部完成转写; - 语义上,
ReadonlySet<PublicChannel>表明enabled集合只能读不能写,enabled.has('email')这类查询操作被允许,而add等修改操作会被类型系统拒绝。
5. NoInfer:抑制泛型推断的实用类型
TypeScript 侧:
function pick<T extends PublicChannel>(options: T[], fallback: NoInfer<T>): T {
return options.includes(fallback) ? fallback : options[0];
}
Flow 侧:
function pick<T extends PublicChannel>(
options: Array<T>,
fallback: NoInfer<T>,
): T {
return options.includes(fallback) ? fallback : options[0];
}
转换要点:
T[]改写为Array<T>:Flow 偏好完整拼写Array<T>(尽管T[]语法同样受支持,idiomatic 风格要求Array<T>);- 泛型约束
<T extends PublicChannel>原样保留:注意这里不是旧式<T: PublicChannel>(冒号写法已被现代 Flow 弃用),而是与 TypeScript 一致的extends写法; NoInfer<T>原样保留:NoInfer的作用是禁止 TypeScript/Flow 从fallback参数推断T,从而保证T完全由options决定。调用点pick(<a href="https://link.gitcode.com/i/916de84fed980f0b365026ab58c37d2b" target="_blank">'email', 'sms'], 'sms')中,options推断出T = 'email' | 'sms',fallback也必须落在该范围内。Flow 的 React 库 [lib/react.js 中大量使用NoInfer<Props>来避免组件 props 被错误推断,可见它是 Flow 原生支持的实用类型;- 若去掉
NoInfer,fallback的字符串字面量类型会参与推断,导致T被收窄,进而破坏options与fallback之间的类型联动——这正是"精度丢失"的典型形态。
三、参考解法全貌与运行时行为一致性
完整参考解法 ideal/main.js 如下(省略版权头):
// @flow
type Channel = 'email' | 'sms' | 'push' | 'webhook';
type PublicChannel = Exclude<Channel, 'webhook'>;
type InstantChannel = Extract<Channel, 'sms' | 'push'>;
type ChannelConfig = {
retries?: number,
timeoutMs?: number,
};
type ResolvedConfig = Required<ChannelConfig>;
declare function send(channel: PublicChannel): Promise<boolean>;
type SendResult = Awaited<ReturnType<typeof send>>;
type RateLimits = ReadonlyMap<Channel, number>;
type Enabled = ReadonlySet<PublicChannel>;
function pick<T extends PublicChannel>(
options: Array<T>,
fallback: NoInfer<T>,
): T {
return options.includes(fallback) ? fallback : options[0];
}
function describe(
config: ResolvedConfig,
limits: RateLimits,
enabled: Enabled,
): string {
const instant: InstantChannel = 'sms';
return [
`retries=${config.retries}`,
`timeout=${config.timeoutMs}`,
`smsLimit=${limits.get('sms') ?? 0}`,
`emailEnabled=${String(enabled.has('email'))}`,
`instant=${instant}`,
].join(' ');
}
const result: SendResult = true;
const chosen = pick(['email', 'sms'], 'sms');
console.log(
describe({retries: 3, timeoutMs: 1000}, new Map(), new Set()),
result,
chosen,
);
值得留意的运行时行为细节:
describe接收new Map()与new Set():空集合在运行时完全合法,而类型上它们分别符合ReadonlyMap<Channel, number>与ReadonlySet<PublicChannel>(联合类型参数使Map/Set构造器推断出最宽类型);limits.get('sms') ?? 0在Map查询缺失时兜底为 0,enabled.has('email')用String(...)显式转成布尔字符串;pick(['email', 'sms'], 'sms')返回'email' | 'sms'类型,console.log输出三组值。转换不能改变这些执行结果,改动任何类型标注以外的运行时逻辑都会使评测失去意义。
四、AST 评测器:如何强制"现代拼写"
config.json 定义了该评测的元数据与专属评测器,难度标记为 hard。评测器全部是 ast_query 类型,即通过 flow ast 输出 + jq 断言 AST 形状(详见 评测框架说明):
- 正向断言——AST 中必须存在以下名字的
GenericTypeAnnotation(泛型类型注解):Exclude、Extract、Required、Awaited、ReadonlyMap、ReadonlySet、NoInfer
- 反向断言(
negate: true)——不允许出现任何名字以$开头的泛型类型注解:
{
"type": "ast_query",
"selector": ".type == \"GenericTypeAnnotation\" and (.id.name // \"\" | startswith(\"$\"))",
"negate": true
}
这组规则的用意非常清晰:
- 它确认
Exclude等实用类型是被显式书写的,而不是被展开成手写条件类型绕过去——评测测的就是这些类型本身; - 它强制模型输出现代拼写:任何
$ReadOnly、$ReadOnlyMap、$NonMaybeType之类的$前缀形式都会触发反向断言而失败。这与 04_ts_to_flow/README.md 中"现代拼写是硬性要求"的设计原则完全一致。
除上述专属评测器外,分类级基线评测器还会自动附加 flow_check(零 Flow 错误)、file_modified(目标文件确实被修改)、no_tsc(不得调用 tsc)等检查。
五、本地验证:让参考解法跑起来
该评测无需调用任何模型 API 即可验证。按 evals/README.md 的说明,在仓库根目录执行:
# 全量流水线:编译 + 对每个 gold patch 打补丁并评测(无 API 调用)
make validate
# 只针对本评测做 dry-run
python3 run_swebench.py --dry-run --flow-bin "$FLOW_BIN" --eval utility_types_filter_collections
# 按分类或标签过滤
make dry-run ARGS="--category 04_ts_to_flow"
make dry-run ARGS="--tag readonly_collections"
流程上,compile_swebench.py 会对 input/ 与 ideal/ 做 diff 生成 gold patch,run_swebench.py 在临时工作目录中应用补丁并运行评测脚本。若没有自建 Flow 二进制,默认使用 npm install 安装的 flow-bin 预编译二进制(node_modules/.bin/flow),也可以用 --flow-bin /path/to/flow 指向本地构建的 Flow。dry-run 模式下,所有 AST 评测器与 flow_check 都会对参考解法跑一遍,任何输出都会被判定为评测不通过。
六、小结:从本评测提炼的 TS→Flow 转换清单
回顾整个 utility_types_filter_collections 评测,可以提炼出一份可复用的转换清单:
- 字面量字符串改用单引号,风格层面统一到 Flow 惯例;
Exclude/Extract/Required/Awaited/ReturnType/NoInfer直接保留,它们都是 Flow 内置实用类型,底层实现见 lib/lib.es5.js;ReadonlyMap/ReadonlySet保留现代拼写,不要退化成$ReadOnlyMap/$ReadOnlySet,Flow 会在内部完成别名转写(见 lib/lib.es2015.collection.js);interface改写为对象类型字面量,T[]改写为Array<T>,泛型约束使用extends而非旧式冒号;- 任何
$前缀的旧拼写都会使现代 Flow 评测失败,同时 AST 评测器也会以negate断言直接拦截。
本评测通过"类型保真的转换"这一单一任务,把 Flow 实用类型系统的现代拼写规则、内置实现与评测机制串联在了一起,是理解 TS→Flow 迁移中"哪些能直译、哪些必须改写"的最佳范例之一。