Overload Resolution Order

The plain-language idea

The function-overloads lesson covers the split between the declared overload signatures callers see and the wider implementation signature underneath. This lesson is about the specific algorithm TypeScript uses to pick which declared overload applies when a call could plausibly match more than one: it checks them top to bottom, in the order you wrote them, and stops at the first one the arguments are assignable to.

That's a meaningfully different rule than languages like Java or C#, which pick the most specific matching overload regardless of where it's declared. TypeScript does no such comparison — first match wins, full stop, even if a later overload would have been a tighter fit.

See it in a real thing: a silently wrong return type

function pickup(x: string | number): string;
function pickup(x: number): number;
function pickup(x: string | number): string | number {
  return typeof x === "number" ? x * 2 : x.toUpperCase();
}

const result = pickup(5);
// result: string — not number!

5 is a number, and it's assignable to string | number — the first overload — so TypeScript stops there and never even considers the second, more specific number overload below it. The call still runs correctly at runtime (the implementation's typeof check handles it fine), but the type callers see is wrong: result is inferred as string, and nothing before this line warns you. Swapping the two declarations fixes it completely:

function pickup(x: number): number;         // ✅ more specific, now checked first
function pickup(x: string | number): string;
function pickup(x: string | number): string | number {
  return typeof x === "number" ? x * 2 : x.toUpperCase();
}

const result = pickup(5); // result: number — correct

Nothing about the implementation changed — only the declaration order. That's the entire bug and the entire fix.

What people usually miss

Watch out

• TypeScript never backtracks or compares candidates. It's not "find the best match among all overloads" — it's "find the first one that fits, and stop looking," which is exactly why a too-general overload placed early can permanently shadow a more specific one placed later.
• A shadowed overload doesn't produce any error or warning. The call still compiles, still runs correctly — only the inferred type is wrong, which makes this bug specifically the kind that slips past a code review that isn't checking hover types line by line.
• The implementation signature is never part of this search. If an argument list doesn't match any declared overload — even if the wider implementation signature underneath could technically accept it — that's a hard "no overload matches this call" compile error, not a fallback to the implementation.
• Arity matters as much as type. An overload requiring three arguments simply doesn't match a two-argument call, regardless of where it sits in the order — ordering only decides between overloads that are actually compatible with the call being made.

Why this matters in interviews

Given the pickup example above, "what type does result get, and why?" is a sharp diagnostic question — it's easy to assume TypeScript is smart enough to find the tightest-fitting overload, and the honest answer (it isn't; it's first-match, top to bottom) is the kind of detail that only shows up once you've actually been bitten by it.