我所理解的 TypeScript 最佳实践(17):从一份定义派生配置、命令和事件的类型
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型(当前)
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
给编辑器新增一个导出格式时,格式列表、扩展名和界面文案通常一起变。如果先写一份格式联合,再维护另一份配置表,每次都要确认两份定义有没有漏改。先找出谁决定支持哪些格式。如果格式由应用自己的配置决定,可以从配置派生类型。如果键名来自外部协议,就用协议规定的键检查配置有没有写全。
配置决定有哪些选项时,从对象取键名和字段值
一个导出对话框需要格式标识、扩展名和标签。把三者放在一份表里,界面可以从它读取标签,保存逻辑也能查询正确的扩展名。
type ExportFormatConfig = {
extension: `.${string}`;
label: string;
};
const exportFormats = {
html: { extension: '.html', label: '网页' },
markdown: { extension: '.md', label: 'Markdown' },
} as const satisfies Record<string, ExportFormatConfig>;
type ExportFormat = keyof typeof exportFormats; // 'html' | 'markdown'
type ExportExtension = (typeof exportFormats)[ExportFormat]['extension']; // '.html' | '.md'
const markdownExtension = exportFormats.markdown.extension; // '.md'
从表里派生类型分两步。先用 keyof typeof exportFormats 取格式名,再按格式索引 extension。加上 pdf 配置后,两个联合会一起扩展。表末尾的 as const 保留 '.md' 这样的字面量,并给字面量中的属性加上只读约束。satisfies 则检查标签和扩展名的格式,同时保留这张表的具体键。可分别查阅 const 断言、索引访问和 satisfies。
如果对外提供查询函数,也可以保留格式和扩展名的对应关系。在下面的签名里,传入 'markdown' 得到 '.md',传入 'html' 得到 '.html'。把这段接到上面的格式表之后即可检查。
function getExportExtension<Format extends ExportFormat>(format: Format): (typeof exportFormats)[Format]['extension'] {
return exportFormats[format].extension;
}
返回类型里的 [Format] 取的是这次调用选择的配置。它和第 12 篇按输入模式保留返回类型的做法一致。参见《用泛型保留类型关系,用 extends 写约束和条件》。
as const 的只读约束用于类型检查,表在 JavaScript 里仍是普通对象。需要控制界面顺序时,用显式数组表达顺序,例如让 Markdown 始终排在 HTML 前面。格式从 URL 或文件进入程序时,也要在读取表之前校验键名。参见《先校验外部数据,再使用收窄后的类型》。
外部协议决定有哪些键时,用它检查配置
如果宿主程序已经规定插件必须支持 'open' 和 'save' 两条命令,插件的命令表只负责实现这份约定。直接从命令表派生命令名会把遗漏的键也排除在类型之外。可以用宿主的命令类型校验表。
type HostCommand = 'open' | 'save';
const commandLabels = {
open: '打开文档',
save: '保存文档',
} as const satisfies Record<HostCommand, string>;
如果宿主导出了 HostCommand,插件可以直接用它检查配置。漏写 save、把它拼成 svae,或宿主新增命令后漏补标签,错误都会落在命令表上。
从负载类型表派生事件联合
有的来源只需要在类型层维护。例如编辑器约定保存事件要带路径,缩放事件要带百分比。事件名称和负载应该一起传递,避免调用方拿着一个可能是任意事件名的变量,再另外传入一个可能是任意负载的变量。
type EditorEventPayloads = {
saved: { path: string };
zoomChanged: { percentage: number };
};
type EditorEvent = {
[Name in keyof EditorEventPayloads]: {
payload: EditorEventPayloads[Name];
type: Name;
};
}[keyof EditorEventPayloads];
function getEventDescription(event: EditorEvent) {
switch (event.type) {
case 'saved':
return `已保存 ${event.payload.path}`;
case 'zoomChanged':
return `缩放到 ${event.payload.percentage}%`;
}
}
getEventDescription({ payload: { path: 'draft.md' }, type: 'saved' });
// @ts-expect-error saved 事件需要 path 字段。
getEventDescription({ payload: { percentage: 100 }, type: 'saved' });
映射类型先为每个事件构造一条带 type 和 payload 的记录。末尾的索引把所有记录取出来,得到一个联合。接收方看到 event.type === 'saved' 时,能在同一分支读出 event.payload.path。如果分别写成 type: keyof EditorEventPayloads 和 payload: EditorEventPayloads[keyof EditorEventPayloads],两个字段会独立检查,也就允许把缩放负载配到保存事件上。
配置表适合承载运行时需要读取的值,负载类型表则适合组织只参与静态检查的约定。变更约定时,先改定义,再用类型检查找出受影响的调用。