Function overloads in TypeScript how and when to use them

What are function overloads

Overloads let a function accept different parameter types and return different types depending on the call. TypeScript picks the matching overload signature at compile time.

// Overload signatures (no body)
function format(value: string): string;
function format(value: number): string;

// Implementation (must be compatible with all overloads)
function format(value: string | number): string {
  if (typeof value === "string") return value.trim();
  return value.toFixed(2);
}

format("  hello  "); // "hello"
format(3.14159);     // "3.14"

When to use overloads

Use overloads when the return type changes based on the input type, and a union return type would be too imprecise:

function parse(input: string): number;
function parse(input: number): string;
function parse(input: string | number): string | number {
  return typeof input === "string" ? parseInt(input) : input.toString();
}

Do not overuse overloads. If a union parameter with a union return type is accurate enough, prefer that. Overloads shine when callers need precise return types without manual casting.