Przeciążanie funkcji w TypeScript: sygnatury przeciążeń

Przeciążanie funkcji w TypeScript polega na napisaniu kilku sygnatur wywołania dla jednej funkcji, a po nich jednej implementacji. Każda sygnatura może łączyć inne typy parametrów z innym typem zwracanym, a wywołujący dostaje ten dokładny.

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

Bez przeciążeń parse zwracałoby number | number[] przy każdym wywołaniu, a one + 1 byłoby błędem, dopóki sam nie zawęzisz wyniku.

Sygnatury przeciążeń i implementacja

Przeciążona funkcja ma dwie części:

1. Sygnatury przeciążeń: deklaracje bez ciała, po jednej na każdy obsługiwany kształt wywołania. Tylko tych sygnatur mogą używać wywołujący.
2. Sygnatura implementacji: ostatnia deklaracja, z ciałem. Jej parametry muszą przyjmować wszystko, co przyjmują przeciążenia, a jej typ zwracany musi obejmować typ zwracany każdego przeciążenia. Z zewnątrz jest niewidoczna.

Typy istnieją tylko w czasie kompilacji, więc w czasie wykonania jest jedna funkcja JavaScript. Implementacja musi sprawdzić swoje argumenty (typeof, Array.isArray, arguments.length...), aby zdecydować, co zrobić. Kompilator sprawdza, czy przeciążenia i implementacja się zgadzają:

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

Rozwiązanie to poszerzenie implementacji: function format(value: string | number): string | number.

Sygnatury implementacji nie da się wywołać

To reguła, która najbardziej zaskakuje. Wywołanie musi samodzielnie pasować do jednej z sygnatur przeciążeń; TypeScript ich nie łączy.

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

Kompilator wypisuje:

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

Implementacja przyjmuje string | string[], ale wywołujący jej nie widzą. Dodaj trzecie przeciążenie, które przyjmuje i zwraca unię, a wywołanie się skompiluje i wypisze [ 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);
}

Różna liczba parametrów

Przeciążenia opisują też wywołania z różną liczbą argumentów. Tutaj datę można zbudować ze znacznika czasu albo z roku, miesiąca i dnia, ale nie z dwóch liczb:

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

Jedna sygnatura z dwoma opcjonalnymi parametrami przyjęłaby makeDate(2024, 3) i po cichu zbudowała złą datę. Przeciążenia zamieniają to w błąd kompilacji (TS2575).

Kolejność ma znaczenie

TypeScript próbuje przeciążeń od góry do dołu i wybiera pierwsze pasujące. Najbardziej szczegółowe sygnatury umieszczaj na początku. Szerokie przeciążenie na początku listy przechwytuje wywołania przeznaczone dla kolejnych:

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"

Zamień miejscami dwie pierwsze sygnatury, a describe("hi") dostanie typ "text".

Przeciążenia czy parametr unii?

Przeciążenia są warte dodatkowych linii, gdy typ zwracany zależy od typów argumentów. Gdy nie zależy, jedna sygnatura z parametrem unii jest krótsza, czytelniejsza i przyjmuje argumenty typu unii, które przeciążenia by odrzuciły.

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

Generyk z conditional type potrafi wyrazić niektóre zestawy przeciążeń jedną sygnaturą, ale przy dwóch lub trzech przypadkach przeciążenia są zwykle czytelniejsze.

Przeciążone metody i konstruktory

Metody używają tego samego wzorca wewnątrz klasy: sygnatury przeciążeń, a potem metoda z ciałem. Konstruktory można przeciążać tak samo.

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

Interfejsy i typy obiektowe też mogą deklarować przeciążenia, jako kilka sygnatur wywołania albo kilka sygnatur metod o tej samej nazwie. Wiele wbudowanych funkcji jest zadeklarowanych właśnie tak: najedź kursorem na reduce na tablicy w edytorze, a zobaczysz "+2 overloads".