🔍 Search Terms

最宽松的捕获所有情况，覆盖，重载，间隙，签名调用错误，要求重载捕获所有情况
这个提案与 #57004 重叠，但不包括从单一匹配重载到多重匹配重载的更改。这使得它的变化小得多。值得注意的是，这个提案满足了可行性检查清单，而57004没有。

✅ Viability Checklist

• 这不会在现有的TypeScript/JavaScript代码中引起破坏性的变化
• 这不会改变现有JavaScript代码的运行时行为
• 这可以在不根据表达式的类型生成不同的JS的情况下实现
• 这不是一个运行时特性(例如库功能、JavaScript输出的非ECMAScript语法、新的JS语法糖等)
• 这不是一个请求添加一个新的实用类型： https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• 这个特性将符合我们设计目标的其他方面： https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

在当前的TypeScript中，当编译器面对一个不包含“最宽松的捕获所有情况”的重载时，编译器假设用户通过省略声明了“最宽松的捕获所有情况”可能导致意外错误，因此会发出编译错误以防止这种情况发生。(见下面的示例)。
注意：在这里，“最宽松的捕获所有情况”被称为覆盖)。
这个提案添加了一个新的编译器标志：

--requireOverloadCatchAll

当此标志被设置时，编译器将检查覆盖是否像重载声明那样被声明，或者在用户的源代码中作为重载类型声明，而不是在声明文件(即导入)中编写的重载。
为了向后兼容，该标志的默认值为 false 。

📃 动机示例

示例1,不必要的签名调用错误

• 示例1:当前行为-不必要的签名调用错误的简单例子*

function stringOrNum(x: string): number;
function stringOrNum(x: number): string;
function stringOrNum(x: string|number): string|number {
    return x;
}

stringOrNum(Math.random()<0.5 ? "" : 0); // error
//          ~~~~~~~~~~~~~~~~~~~~~~~~~~~
// No overload matches this call.
//   Overload 1 of 2, '(x: string): number', gave the following error.
//     Argument of type 'string | number' is not assignable to parameter of type 'string'.
//       Type 'number' is not assignable to type 'string'.
//   Overload 2 of 2, '(x: number): string', gave the following error.
//     Argument of type 'string | number' is not assignable to parameter of type 'number'.
//       Type 'string' is not assignable to type 'number'.(2769)

当设置 --requireOverloadCatchAll 标志时，用户需要编写覆盖案例，

function stringOrNum(x: string): number;
function stringOrNum(x: number): string;
function stringOrNum(x: string|number): string|number;
function stringOrNum(x: string|number): string|number {
    return x;
}

错误就不会发出。

示例2:当前行为-通过编写覆盖案例可以轻松解决难以理解的错误

一个简单的Map重载函数的结果在应用于数组Map函数时会产生难以理解的错误：

function f(x:string):1;
function f(x:number):2;
function f(x:string|number): 1|2 {
    if (typeof x==="string") return 1;
    if (typeof x==="number") return 2;
    throw "impossible";
}

当设置 --requireOverloadCatchAll 标志时，用户需要编写覆盖案例，

let arr: number[] | string[] = [];
arr = arr.map(f); // error
//      ~
// Argument of type '{ (x: string): 1; (x: number): 2; }' is not assignable to parameter of type '((value: number, index: number, array: number[]) => 2) & ((value: string, index: number, array: string[]) => 2)'.
//   Type '{ (x: string): 1; (x: number): 2; }' is not assignable to type '(value: string, index: number, array: string[]) => 2'.
//     Type '1' is not assignable to type '2'.(2345)
// function f(x: string): 1 (+1 overload)

错误就不会发生。

示例3:当前行为-不编写覆盖案例对库编写者来说不好的做法

• 示例3a:*

一个简单的Map函数。库编写者在文档中声明了覆盖案例，但没有在实现中声明。

// Library writer
/**
* @throws "rangeError" if (x,y) is not in the input range described
* by the overload declaration.
*/
function g0(x:string,y:number):1;
function g0(x:number,y:boolean):2;
function g0(x:string|number,y:number|boolean):1|2 {
    if (typeof x === "string" && typeof y === "number") return 1;
    if (typeof x === "number" && typeof y === "boolean") return 2;
    throw "rangeError"; // from library writer's POV, not  an unexpected error
}

库客户端收到了一个难以理解的签名调用错误消息，如下所示：

• 示例3b:*

declare const arr2: [string, number][]|[number, boolean][];
let mappped = arr2.map(g0);
// error               ~~~
// Argument of type '{ (x: string, y: number): 1; (x: number, y: boolean): 2; }' is not assignable to parameter of type '((value: [string, number], index: number, array: [string, number][]) => 2) & ((value: [number, boolean], index: number, array: [number, boolean][]) => 2)'.
//   Type '{ (x: string, y: number): 1; (x: number, y: boolean): 2; }' is not assignable to type '(value: [string, number], index: number, array: [string, number][]) => 2'.
//     Types of parameters 'x' and 'value' are incompatible.
//       Type '[string, number]' is not assignable to type 'string'.(2345)

错误对库客户端来说很麻烦，因为库用户已经在文档中声明了覆盖案例，所以没有出错的风险。
当设置 --requireOverloadCatchAll 标志时，库编写者将被要求编写覆盖案例，

declare function g0(x:string,y:number):1;
declare function g0(x:number,y:boolean):2;
declare function g0(x:number|string,y:boolean):1|2; // throws "rangeError" (library client needs to know this)

客户端就不会遇到这个错误。
反驳的一个论点是，库编写者可能想节省一些字符，不写覆盖案例就写出实现，例如：

function g(x:string|number,y:number|boolean):1|2 {
    if (typeof x === "string" && typeof y === "number") return 1;
    else return 2;
}

然后让编译器发出错误，即使对于用户来说有点麻烦也没关系。这是可能的，但对于库编写者来说并不是一种好的做法，所以这不是一个很好的论据。

示例4:不编写覆盖案例使继承变得困难，对库编写者来说也不是一种好的做法

改编自 issue #56829 。
当设置 --requireOverloadCatchAll 标志时，库编写者将被要求编写覆盖案例，
这将使库客户端成功继承。

SetupOverload(
    functionSymbol: TypeScript Symbol // e.g. overloadFunction,
    // the extra type in addition to the explicit overloads cover type
    gapReturnType: throws | never | any = never,
    thrownType: any = undefined
): void;

其中

• functionSymbol 是重载函数声明的符号，
• gapReturnType 是一个类型，可以是 throws、never 或其他任何类型，
• 这里 throws 是一个关键字，但不是一个新的类型。具体来说：throws 对应于 never,而 void 对应于 undefined。
• gapReturnType 被添加到显式重载的覆盖中。
• thrownType 表示在 gapReturnType 为 throws 时应该抛出的类型，否则忽略。

而不是像这样写出最后一个情况的覆盖类型：

function g2(x:string,y:number):1;
function g2(x:number,y:boolean):2;
function g2(x:string|number,y:number|boolean):1|2|throws "rangeError"
function g2(... // implementation

库编写者可以写成：

function g2(x:string,y:number):1;
function g2(x:number,y:boolean):2;
SetupOverload(g2, throws "rangeError");
function g2(... // implementation

同样地，为了定义一个没有声明的重载类型：

type CreateOverload<
    TupleOfFuncs extends [... ((...args:any[])=>any)[]],
    GapReturnType extends throws | never | any = never,
    ThrownType extends any = undefined
>; // intrinsic

SetupOverload 和 CreateOverload 也包含在提案 #57004 中。尽管 --requireOverloadCatchAll 提案不包括多个匹配，但这些内置函数对于当前的单重载匹配算法也很有用。

更新 1/26/2024 - 为 GapReturn 提供另一个选择：compilerError,它对应于当前不包含 catch-all 情况的行为。考虑以下场景：

• 用户有一个单独的 UI 行，对应于每个重载情况，因此他们 打算总是使用缩小到单个重载的参数调用 - 他们只是想确保在编译时，UI-to-overload Map是正确的。已知重载函数永远不会以其他方式被调用。