Course contentsShow
← TypeScript
Lesson 1413 of 1,79632. Advanced PatternsFree lesson

Guidelines for Choosing Between Them

Practical decision tree for when overloads add clarity versus when union signatures with conditional types are superior.

Guidelines for Choosing Between Them

You'll learn practical criteria for deciding when function overloads clarify your API versus when union signatures with conditional types are the superior choice.

The Core Decision Framework

Both function overloads and union signatures with conditional types solve the same problem: typing functions where different inputs produce different outputs. The key question is clarity vs. maintainability.

Overloads excel when:

  • You have 2-4 distinct, easily-described signatures
  • Each signature represents a genuinely different use case
  • Parameter types are completely different (not variations)
  • You want IDE autocomplete to show separate signatures

Union signatures with conditional types excel when:

  • Logic is shared across all input types
  • You have many variations (5+ cases)
  • Parameters are related (like generic constraints)
  • Return types follow a predictable pattern based on input

When Overloads Add Clarity

Overloads shine for intentionally separate behaviors that happen to share a name:

// Different behaviors deserve separate signatures
function process(data: string): string[];
function process(data: number): boolean;
function process(data: unknown): string[] | boolean {
  // Two unrelated implementations
}

Here, the operations are fundamentally different—overloads document this clearly.

When Unions Are Superior

Use union signatures when the logic is unified and return types depend on input types:

function wrap<T extends string | number>(
  value: T
): T extends string ? string[] : number[] {
  // Single unified logic
}

This communicates "same operation, type-dependent result" more honestly than overloads would.

The Maintenance Test

Ask: "If I add a new case, what breaks?" With overloads, you add another signature manually. With conditional types, the pattern often extends automatically. Choose based on how your function evolves.

Key Takeaway: Use overloads when signatures represent distinct APIs (2-4 cases), and union signatures with conditional types when return types follow a pattern from input types or you have many related cases.