Call signature returning a wide union type not seen as compatible with implementation

Bug Report

🔎 Search Terms

overload "not compatible" 2394 union return type

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about overloads and unions

⏯ Playground Link

Playground link with relevant code

💻 Code

function foo(x: true): 0 | 1; // error!
// ----> ~~~
// This overload signature is not compatible with its implementation signature.(2394)
function foo(x: false): 2;
function foo(x: boolean) {
  return x ? 0 : 2;
}

🙁 Actual behavior

The compiler complains that the first call signature which returns 0 | 1 is not compatible with the implementation signature which returns 0 | 2.

🙂 Expected behavior

The compiler "should" allow the 0 | 1 call signature return type because of the significant overlap with 0 | 2.

So, this is probably not actually a bug, but I'm having a hard time locating any canonical documentation or issues that mention this particular behavior. It makes sense for the compiler to warn that a call signature is claiming to return something the implementation can never return, but in this particular instance (adapted from this SO question) it seems unfortunate/misplaced: while the implementation cannot return a value of type 1, it can return a value of type 0 | 1. Obviously there are workarounds, the easiest of which would be an explicit implementation return type annotation of the full union 0 | 1 | 2:

function foo(x: true): 0 | 1;  // no error now
function foo(x: false): 2;
function foo(x: boolean): 0 | 1 | 2 {
  return x ? 0 : 2;
}

So... is this working as intended? If so, could someone explain the intent? Thanks!

Beginne damit, das Überladungsbeispiel im verknüpften TypeScript Playground zu reproduzieren, und vergleiche den gemeldeten Kompatibilitätsfehler mit der expliziten Implementierungs-Rückgabetyp-Umgehung. Verfolge das Kompatibilitätsverhalten des Compilers bei Überladungen und ermittle anschließend, ob das Ergebnis behoben oder in der kanonischen Dokumentation erklärt werden sollte, und füge entsprechend Tests oder Dokumentation hinzu.