TypeScript中如何缩小带可选第二参数的重载函数类型范围？

问题背景 #

在TypeScript中定义重载函数时，若第一个参数支持两种类型（string和string[]），且第二个参数仅在第一个参数为string的重载变体中存在，直接通过typeof input === 'string'做类型收窄后，编译器无法自动关联出extra参数必然存在，导致类型校验失败。

尝试的错误实现及问题 #

以下是几种尝试的实现，均存在类型校验问题：

实现1：直接类型收窄

declare const bar: (input: string, extra: string) => boolean;
declare const baz: (input: string[]) => boolean;

export function foo(input: string[]): boolean;
export function foo(input: string, extra: string): boolean;
export function foo(input: string | string[], extra?: string): boolean {
  if (typeof input === 'string') {
    // 错误：extra被推断为string | undefined，不符合bar的参数要求
    return bar(input, extra);
  }

  return baz(input);
}

问题：类型收窄仅针对input，编译器无法关联到重载约定中input为string时extra必然存在的规则，因此报错。

实现2：额外判断extra存在

export function foo1(input: string[]): boolean;
export function foo1(input: string, extra: string): boolean;
export function foo1(input: string | string[], extra?: string): boolean {
  if (typeof input === 'string' && extra) {
    return bar(input, extra);
  }

  // 错误：input仍可能是string类型（当extra不存在时），无法传给要求string[]的baz
  return baz(input);
}

问题：添加extra存在判断后，分支外的input类型没有被完全收窄，导致传给baz时类型不匹配。

实现3：抛出异常处理分支

export function foo2(input: string[]): boolean;
export function foo2(input: string, extra: string): boolean;
export function foo2(input: string | string[], extra?: string): boolean {
  if (typeof input === 'string') {
    // 可行但冗余：按照重载约定，不会走到抛出异常的分支
    if (extra) {
      return bar(input, extra);
    }
    throw new Error('Unable to reach here');
  }

  return baz(input);
}

问题：虽然能通过校验，但额外的异常抛出属于冗余代码，不符合重载的设计逻辑。

正确解决方案 #

方案1：利用类型断言 #

根据重载的约定，当input为string时，extra必然存在，直接用类型断言明确extra的类型：

export function foo3(input: string[]): boolean;
export function foo3(input: string, extra: string): boolean;
export function foo3(input: string | string[], extra?: string): boolean {
  if (typeof input === 'string') {
    // 基于重载约定的安全断言
    return bar(input, extra as string);
  }

  return baz(input);
}

这种方式简洁高效，符合重载的设计逻辑，断言是安全的。

方案2：重构参数为元组联合类型 #

将实现函数的参数定义为元组的联合类型，让编译器自动关联参数间的类型关系：

export function foo4(input: string[]): boolean;
export function foo4(input: string, extra: string): boolean;
export function foo4(...args: [string[]] | [string, string]): boolean {
  if (typeof args[0] === 'string') {
    // 编译器自动推断args[1]必然是string
    return bar(args[0], args[1]);
  }

  return baz(args[0]);
}

通过元组联合类型，编译器能准确识别参数组合的合法性，无需额外判断或断言即可通过校验。

总结 #

• 若希望保持原有参数定义，使用类型断言是最简洁的方案，完全符合重载的约定逻辑。
• 若追求更严谨的类型自动推断，可重构参数为元组联合类型，让参数间的类型关联更清晰。

内容的提问来源于stack exchange，提问作者Ricardo Devis Agullo