TypeScript 5.3.3中如何实现泛型keyof条件判断的类型安全？

我编写了一个函数，通过指定类型key来索引对象，或接收undefined用于类构造函数，代码如下：

class Instance {
  type: keyof OptionsMap
  constructor(type: keyof OptionsMap) {
    this.type = type
  }
}
class ClassA extends Instance {
  constructor(type: 'nothing') {
    super(type)
  }
}
class ClassB extends Instance {
  opts: Record<string, any>
  constructor(type: 'something', opts: Record<string, any>){
    super(type)
    this.opts = opts
  }
}
class ClassC extends Instance {
  opts: { name: string }
  constructor(type: 'thing', opts: { name: string }){
    super(type)
    this.opts = opts
  }
}
interface OptionsMap {
  nothing: undefined
  something: Record<string, any>
  thing: { name: string }
}

function foo<T extends keyof OptionsMap>(type: T, options: OptionsMap[T]): Instance {
  if (type === 'nothing') {
    return new ClassA(type)
  } else if (type === 'something') {
    return new ClassB(type, options)
  } else if (type === 'thing') {
    return new ClassC(type, options)
  } else {
    throw Error('Invalid type: ' + type)
  }
}

运行时遇到TypeScript类型错误：

Argument of type 'Record<string, any> | undefined' is not assignable to parameter of type 'Record<string, any>'.
  Type 'undefined' is not assignable to type 'Record<string, any>'

当前使用TypeScript 5.3.3版本，请问怎么让options参数实现类型安全？

解决方案 #

问题根源在于TypeScript无法通过泛型T的分支判断，自动窄化options的类型。可以通过以下几种方式修复：

1. 使用函数重载明确参数对应关系

给foo函数添加重载签名，让TypeScript明确每个type对应的options类型，这是最推荐的方案：

// 重载签名：定义每种type对应的参数规则
function foo(type: 'nothing'): Instance;
function foo(type: 'something', options: Record<string, any>): Instance;
function foo(type: 'thing', options: { name: string }): Instance;

// 实现签名：处理通用逻辑
function foo<T extends keyof OptionsMap>(type: T, options?: OptionsMap[T]): Instance {
  if (type === 'nothing') {
    return new ClassA(type)
  } else if (type === 'something') {
    return new ClassB(type, options!) // 重载已保证该分支下options必存在，用!断言
  } else if (type === 'thing') {
    return new ClassC(type, options!)
  } else {
    throw Error('Invalid type: ' + type)
  }
}

这种方式既保证了调用时的类型提示准确，也消除了内部分支的类型错误，符合TypeScript的类型设计逻辑。

2. 手动类型断言（简易但不够健壮）

在每个分支里，手动把options断言为对应类型，适合快速修复：

function foo<T extends keyof OptionsMap>(type: T, options: OptionsMap[T]): Instance {
  if (type === 'nothing') {
    return new ClassA(type)
  } else if (type === 'something') {
    return new ClassB(type, options as OptionsMap['something'])
  } else if (type === 'thing') {
    return new ClassC(type, options as OptionsMap['thing'])
  } else {
    throw Error('Invalid type: ' + type)
  }
}

这种方式代码改动小，但需要手动维护断言，后续如果OptionsMap结构变化，容易遗漏更新。

3. 自定义类型守卫优化类型窄化

通过自定义类型守卫函数，帮助TypeScript识别options的具体类型，适合复杂场景：

// 定义类型守卫，判断是否为something对应的options
function isSomethingOptions(opts: OptionsMap[keyof OptionsMap]): opts is Record<string, any> {
  return typeof opts === 'object' && opts !== null;
}

// 定义类型守卫，判断是否为thing对应的options
function isThingOptions(opts: OptionsMap[keyof OptionsMap]): opts is { name: string } {
  return typeof opts === 'object' && opts !== null && 'name' in opts && typeof (opts as any).name === 'string';
}

function foo<T extends keyof OptionsMap>(type: T, options: OptionsMap[T]): Instance {
  if (type === 'nothing') {
    return new ClassA(type)
  } else if (type === 'something' && isSomethingOptions(options)) {
    return new ClassB(type, options)
  } else if (type === 'thing' && isThingOptions(options)) {
    return new ClassC(type, options)
  } else {
    throw Error('Invalid type or options: ' + type)
  }
}

这种方式增加了运行时类型检查，适合需要同时保证编译和运行时类型安全的场景。

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