Перегрузка функций в TypeScript: сигнатуры перегрузки

Перегрузка функций в TypeScript означает, что для одной функции пишется несколько сигнатур вызова, а за ними одна реализация. Каждая сигнатура может связывать свои типы параметров со своим возвращаемым типом, и вызывающий код получает точный тип.

// 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 ]

Без перегрузок parse возвращала бы number | number[] для любого вызова, и one + 1 оставалось бы ошибкой, пока вы сами не сузили бы результат.

Сигнатуры перегрузки и реализация

У перегруженной функции две части:

1. Сигнатуры перегрузки: объявления без тела, по одному на каждую поддерживаемую форму вызова. Только эти сигнатуры доступны вызывающему коду.
2. Сигнатура реализации: последнее объявление, с телом. Её параметры должны принимать всё, что принимают перегрузки, а её возвращаемый тип должен покрывать возвращаемый тип каждой перегрузки. Снаружи она не видна.

Типы существуют только во время компиляции, поэтому во время выполнения функция JavaScript одна. Реализация должна изучить свои аргументы (typeof, Array.isArray, arguments.length...), чтобы решить, что делать. Компилятор проверяет, что перегрузки и реализация согласованы:

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

Исправление: расширить реализацию, function format(value: string | number): string | number.

Сигнатуру реализации нельзя вызвать

Это правило удивляет больше всего. Вызов должен сам по себе подходить к одной из сигнатур перегрузки; TypeScript их не объединяет.

// 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)));

Компилятор выводит:

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[]'.

Реализация принимает string | string[], но вызывающий код её не видит. Добавьте третью перегрузку, которая принимает объединение и возвращает объединение, и вызов скомпилируется и напечатает [ 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);
}

Разное количество параметров

Перегрузки описывают и вызовы с разным числом аргументов. Здесь дату можно построить из метки времени или из года, месяца и дня, но не из двух чисел:

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);

Одна сигнатура с двумя опциональными параметрами приняла бы makeDate(2024, 3) и молча построила бы неверную дату. Перегрузки превращают это в ошибку компиляции (TS2575).

Порядок имеет значение

TypeScript перебирает перегрузки сверху вниз и выбирает первую подходящую. Ставьте самые конкретные сигнатуры первыми. Широкая перегрузка в начале списка перехватывает вызовы, предназначенные для следующих за ней:

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"

Поменяйте местами первые две сигнатуры, и describe("hi") получит тип "text".

Перегрузки или параметр-объединение?

Перегрузки оправдывают лишние строки, когда возвращаемый тип зависит от типов аргументов. Когда не зависит, одна сигнатура с параметром-объединением короче, проще читается и принимает аргументы-объединения, которые перегрузки отвергли бы.

// 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

Дженерик с условным типом может выразить некоторые наборы перегрузок одной сигнатурой, но для двух-трёх случаев перегрузки обычно читаются легче.

Перегруженные методы и конструкторы

Методы внутри класса используют ту же схему: сигнатуры перегрузки, затем метод с телом. Так же можно перегружать конструкторы.

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

Интерфейсы и объектные типы тоже могут объявлять перегрузки: несколько сигнатур вызова или несколько сигнатур метода с одним именем. Так объявлены многие встроенные функции: наведите курсор на reduce у массива в редакторе, и он покажет «+2 overloads».