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!

Inizia riproducendo l’esempio di overload nel TypeScript Playground collegato e confronta l’errore di compatibilità segnalato con il workaround che usa il tipo di ritorno esplicito dell’implementazione. Traccia il comportamento di compatibilità degli overload del compilatore, quindi determina se il risultato debba essere corretto o spiegato nella documentazione canonica e aggiungi di conseguenza la coverage o la documentazione.