TypeScript Function Overloading: Overload Signatures

Function overloading in TypeScript means writing several call signatures for one function, followed by a single implementation. Each signature can pair different parameter types with a different return type, and the caller gets the precise one.

// Overload signatures: what callers see
function parse(input: string): number;
function parse(input: string[]): number[];
// Implementation: one body that handles every case
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

const one = parse("42");          // one: number
const many = parse(["1", "2.5"]); // many: number[]

console.log(one + 1);             // 43
console.log(many.map((n) => n * 2)); // [ 2, 5 ]

Without the overloads, parse would return number | number[] for every call, and one + 1 would be an error until you narrowed the result yourself.

Overload Signatures and the Implementation

An overloaded function has two parts:

1. Overload signatures: declarations with no body, one per supported call shape. These are the only signatures callers can use.
2. The implementation signature: the last declaration, with the body. Its parameters must accept everything the overloads accept, and its return type must cover every overload's return type. It is invisible from outside.

Types exist only at compile time, so there is one JavaScript function at run time. The implementation has to inspect its arguments (typeof, Array.isArray, arguments.length...) to decide what to do. The compiler checks that the overloads and the implementation agree:

function format(value: string): string;
function format(value: number): number {
  return value;
}
// error TS2394: This overload signature is not compatible with its implementation signature.

The fix is to widen the implementation: function format(value: string | number): string | number.

The Implementation Signature Is Not Callable

This is the rule that surprises people most. A call has to match one of the overload signatures on its own; TypeScript does not combine them.

// This does not compile: no single overload takes string | string[].
function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

function readInput(multi: boolean): string | string[] {
  return multi ? ["1", "2"] : "3";
}

console.log(parse(readInput(true)));

The compiler prints:

index.ts(12,19): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string | string[]' is not assignable to parameter of type 'string[]'.
      Type 'string' is not assignable to type 'string[]'.

The implementation accepts string | string[], but callers cannot see it. Add a third overload that takes the union and returns the union, and the call compiles and prints [ 1, 2 ]:

function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

Different Numbers of Parameters

Overloads also describe calls with different arities. Here a date can be built from a timestamp or from year, month and day, but not from two numbers:

function makeDate(timestamp: number): Date;
function makeDate(year: number, month: number, day: number): Date;
function makeDate(a: number, month?: number, day?: number): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(Date.UTC(a, month - 1, day));
  }
  return new Date(a);
}

console.log(makeDate(0).toISOString());          // 1970-01-01T00:00:00.000Z
console.log(makeDate(2024, 3, 15).toISOString()); // 2024-03-15T00:00:00.000Z

// @ts-expect-error: No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
makeDate(2024, 3);

A single signature with two optional parameters would accept makeDate(2024, 3) and silently build the wrong date. The overloads turn that into a compile error (TS2575).

Order Matters

TypeScript tries the overloads from top to bottom and picks the first one that matches. Put the most specific signatures first. A broad overload early in the list swallows the calls meant for the ones after it:

function describe(value: unknown): string;   // matches everything
function describe(value: string): "text";    // never chosen
function describe(value: unknown): string {
  return typeof value === "string" ? "text" : "other";
}

const d = describe("hi"); // d: string, not "text"

Swap the first two signatures and describe("hi") is typed "text".

Overloads or a Union Parameter?

Overloads are worth their extra lines when the return type depends on the argument types. When it does not, one signature with a union parameter is shorter, easier to read, and accepts union arguments that overloads would reject.

// Overloads that add nothing: the return type is always number
function lengthOfA(x: string): number;
function lengthOfA(x: unknown[]): number;
function lengthOfA(x: string | unknown[]): number {
  return x.length;
}

// Better: one signature
function lengthOf(x: string | unknown[]): number {
  return x.length;
}

function pick(useList: boolean): string | number[] {
  return useList ? [1, 2, 3] : "abc";
}

const input = pick(true);
console.log(lengthOf(input)); // 3 (lengthOfA(input) would be TS2769)
console.log(lengthOfA("abcd")); // 4

A generic with a conditional type can express some overload sets as one signature, but for two or three cases overloads are usually easier to read.

Overloaded Methods and Constructors

Methods use the same pattern inside a class: overload signatures, then the method with a body. Constructors can be overloaded the same way.

class Money {
  readonly cents: number;

  constructor(cents: number);
  constructor(amount: string);
  constructor(value: number | string) {
    this.cents = typeof value === "number" ? value : Math.round(parseFloat(value) * 100);
  }

  add(other: Money): Money;
  add(cents: number): Money;
  add(value: Money | number): Money {
    const extra = typeof value === "number" ? value : value.cents;
    return new Money(this.cents + extra);
  }
}

const price = new Money("19.99");
console.log(price.add(1).cents);               // 2000
console.log(price.add(new Money(1)).cents);    // 2000

Interfaces and object types can declare overloads too, as several call signatures or several method signatures with the same name. Many built-in functions are declared this way: hover over reduce on an array in an editor and it shows "+2 overloads".