TypeScript实现事件类型校验类型守卫并获得正确类型推导

现有定义与需求 #

你当前的联合事件类型定义：

type ScanSheetEvents =
  | { type: "updateStationsList"; stationsList: StationCodeList }
  | { type: "reAskPermissions" };

需要实现的工具方法满足以下要求：

• 传入事件对象和目标事件类型，类型不匹配时抛出错误
• 校验通过后TypeScript自动收窄event的具体类型，IDE可以正确提示对应属性
• 预期调用方式：

(_, event) => {
  throwIfNotEvent(event, "updateStationsList");
  // 此处可直接访问event.stationsList，无类型报错
  return event.stationsList;
}

问题根因 #

你之前的初步实现没有通过泛型关联传入的eventType参数和目标收窄类型，TypeScript无法根据传入的具体事件类型字符串，推导出对应的事件子类型。

最终可用实现 #

function throwIfNotEvent<T extends ScanSheetEvents["type"]>(
  event: ScanSheetEvents,
  eventType: T,
): asserts event is Extract<ScanSheetEvents, { type: T }> {
  if (event.type !== eventType) {
    throw new Error(`Unexpected event: got ${event.type}, expected ${eventType}`);
  }
}

关键逻辑说明 #

• 引入泛型T约束为事件type字段的所有合法字面量类型，调用方法时TS会自动捕获你传入的具体eventType字面量值，作为后续类型推导的依据
• 借助TS内置的Extract工具类型，从ScanSheetEvents联合类型中筛选出type属性匹配泛型T的子类型，作为类型收窄后的结果
• 返回值使用asserts event is ...断言函数语法，适配「不满足条件直接抛错、无返回值，满足条件则参数类型收窄」的逻辑，比普通布尔类型守卫更匹配当前场景

注意事项 #

• 不要将eventType参数的类型直接标注为ScanSheetEvents["type"]，否则TS只能识别到参数是所有事件类型的联合，无法拿到你传入的具体字面量值，无法完成精准类型推导
• 不要误用普通类型守卫的event is ...返回语法，该语法要求函数返回布尔值，和当前抛错的运行时逻辑不匹配，会导致类型收窄失效
• 错误信息里建议同时打印实际拿到的事件类型和期望的事件类型，方便调试定位问题

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