Course contentsShow
← TypeScript
Lesson 273 of 1,7966. FunctionsFree lesson

Overload Resolution Order Matters

Understanding how TypeScript matches calls to the first compatible overload signature.

Overload Resolution Order Matters

You'll learn why the order of overload signatures directly affects which signature TypeScript selects for a given function call.

The First-Match Rule

TypeScript doesn't find the "best" overload signature—it finds the first compatible one. When you call an overloaded function, TypeScript checks each overload signature from top to bottom and uses the first one that matches your arguments.

This means order matters tremendously. If you place a very general overload before a more specific one, the general overload will always win, and the specific one becomes unreachable.

Why This Happens

Think of overload resolution like a restaurant menu where dishes are ordered from most general to most specific. If "Any Pasta" appears before "Gluten-Free Fettuccine," and you order pasta, you'll always get the generic version—even if you're gluten-free. The waiter stops reading at the first match.

TypeScript works the same way. It's not smart enough to pick the "most specific" match; it just picks the first workable match.

The Golden Rule

Always order overload signatures from most specific to most general. Place narrow, specialized signatures at the top and broad, catch-all signatures at the bottom.

If you have an overload that accepts string and another that accepts string | number, the string-only signature must come first. Otherwise, string | number will match string arguments before TypeScript ever sees the specialized signature.

Key Takeaway: TypeScript matches overloads top-to-bottom, stopping at the first compatible signature—always order from most specific to most general to avoid unreachable overloads.