How to correctly overload functions in TypeScript?

Can anyone please tell me what's the problem with types here? I'm trying to make myself clear with overloads in TS but that problem below makes me really confused...

type myNumbers = 1 | 2 | 3
type myStrings = 'a' | 'b' | 'c';

interface ReturnValue {
  (tag: 'a'): 1
  (tag: 'b'): 2
  (tag: 'c'): 3
  (tag: myStrings): myNumbers
}

class Log {
  public returnValue: ReturnValue = (tag: myStrings): myNumbers => {
    switch (tag) {
      case 'a':
        return 1;
      case 'b':
        return 2;
      case 'c':
        return 3;
    }
  }
}

Type '(tag: myStrings) => myNumbers' is not assignable to type 'ReturnValue'.
  Type 'myNumbers' is not assignable to type '1'.
    Type '2' is not assignable to type '1'.

Overloads in TypeScript consist of multiple call signatures and a single implementation, which has its own signature. TypeScript never really "correctly" type checks the implementation against the call signatures. It's either checked too loosely and allows incorrect implementations, or too strictly and prohibits correct implementations. So there is no way to "correctly" overload functions in TypeScript. Instead you have to pick a direction in which to err.

If you write an overloaded function statement or a class method, the compiler will check the implementation loosely. This makes it easy to write overloads without compiler errors:

function returnValue(tag: "a"): 1;
function returnValue(tag: "b"): 2;
function returnValue(tag: "c"): 3;
function returnValue(tag: MyStrings): MyNumbers;
function returnValue(tag: MyStrings) {
  switch (tag) {
    case 'a': return 1;
    case 'b': return 2;
    case 'c': return 3;
  }
}

class Log {
  public returnValue: ReturnValue = returnValue;
}

or

class Log {
  public returnValue(tag: "a"): 1;
  public returnValue(tag: "b"): 2;
  public returnValue(tag: "c"): 3;
  public returnValue(tag: MyStrings): MyNumbers;
  public returnValue(tag: MyStrings) {
    switch (tag) {
      case 'a': return 1;
      case 'b': return 2;
      case 'c': return 3;
    }
  }
}

So that's one approach you can take: change your function expression to a function statement or a class method.

But that looseness only catches the most egregious of errors in which the implementation signature is definitely incompatible with the call signatures. It won't catch situations where you mix up which return type goes with which call signature:

function returnValue(tag: "a"): 1;
function returnValue(tag: "b"): 2;
function returnValue(tag: "c"): 3;
function returnValue(tag: MyStrings): MyNumbers;
function returnValue(tag: MyStrings) {
  switch (tag) {
    case 'a': return 3; // oops, but no error
    case 'b': return 1; // oops, but no error
    case 'c': return 2; // oops, but no error
  }
} 

In some sense function statement and class method overloads only care that the implementation returns the union of the call signature return types.

So remember to check your implementations carefully if you use such overloads, because the compiler can't

On the other hand, if you try to write an overloaded function expression or arrow function, the compiler will only type check if the implementation's return type is assignable to all of the call signature's return types, that is, their intersection.

const ret: ReturnValue = (tag: MyStrings) => {
  throw new Error();
} // okay

const slightlyLessContrived: {
  (x: string): { a: string };
  (x: number): { b: number };
} = (x: string | number) => ({ a: "", b: 1 }); // okay

The first line compiles because the implementation of ret returns the never type which is what you get when you try to say a value is 1 & 2 & 3 all at once... that is, it's impossible. And the second line compiles because the implementation returns {a: string, b: number} which is equivalent to {a: string} & {b: number}.

But such implementations are fairly useless; if you were willing to return the intersection of the return types, you wouldn't need overloads in the first place. You'd just use the implementation directly.

There currently is no option to write a function expression and get the loose type checking from function statements. There's an open feature request at microsoft/TypeScript#47669 for that, but so far it's not part of the language.

But, if you want to loosen type checking of a function expression you can do so the same way you loosen type checking for any expression: use a type assertion:

class Log {
  public returnValue = ((tag: MyStrings): MyNumbers => {
    switch (tag) {
      case 'a': return 1;
      case 'b': return 2;
      case 'c': return 3;
    }
  }) as ReturnValue; // okay
}

But this has the same problem as before in terms of allowing unsafe implementations:

class Log {
  public returnValue = ((tag: MyStrings): MyNumbers => {
    switch (tag) {
      case 'a': return 3; // oops
      case 'b': return 1; // I
      case 'c': return 2; // messed up
    }
  }) as ReturnValue; // still okay
}

Again, you'll have to be careful.

So those are your choices if you want to write overloads: either write a function statement or class method, or write a function expression with a type assertion. Whether or not this is "correct" is subjective, though.

Playground link to code