Item 52: Prefer Conditional Types to Overload Signatures

Things to Remember

• Prefer conditional types to overloaded type signatures. By distributing over unions, conditional types allow your declarations to support union types without additional overloads.
• If the union case is implausible, consider whether your function would be clearer as two or more functions with different names.
• Consider using the single overload strategy for implementing functions declared with conditional types.

Code Samples

declare function double(x: string | number): string | number;

💻 playground

---

const num = double(12);
//    ^? const num: string | number
const str = double('x');
//    ^? const str: string | number

💻 playground

---

declare function double<T extends string | number>(x: T): T;

const num = double(12);
//    ^? const num: 12
const str = double('x');
//    ^? const str: "x"

💻 playground

---

declare function double(x: number): number;
declare function double(x: string): string;

const num = double(12);
//    ^? const num: number
const str = double('x');
//    ^? const str: string

💻 playground

---

function f(x: string | number) {
  return double(x);
  //            ~ Argument of type 'string | number' is not assignable
  //              to parameter of type 'string'
}

💻 playground

---

declare function double<T extends string | number>(
  x: T
): T extends string ? string : number;

💻 playground

---

const num = double(12);
//    ^? const num: number
const str = double('x');
//    ^? const str: string

function f(x: string | number) {
  //     ^? function f(x: string | number): string | number
  return double(x);  // ok
}

💻 playground

---

function double<T extends string | number>(
  x: T
): T extends string ? string : number;
function double(x: string | number): string | number {
  return typeof x === 'string' ? x + x : x + x;
}

💻 playground