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!

Comienza reproduciendo el ejemplo de sobrecarga en el TypeScript Playground enlazado y compara el error de compatibilidad informado con la solución alternativa del tipo de retorno explícito de la implementación. Rastrea el comportamiento de compatibilidad de las sobrecargas del compilador y determina después si el resultado debe corregirse o explicarse en la documentación canónica, y añade cobertura o documentación según corresponda.