TypeScript Funktionsüberladung: Overload Signatures

Funktionsüberladung in TypeScript bedeutet, für eine Funktion mehrere Aufrufsignaturen zu schreiben, gefolgt von einer einzigen Implementierung. Jede Signatur kann andere Parametertypen mit einem anderen Rückgabetyp verbinden, und der Aufrufer bekommt den genauen.

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

Ohne die Überladungen würde parse für jeden Aufruf number | number[] zurückgeben, und one + 1 wäre ein Fehler, bis du das Ergebnis selbst eingeengt hättest.

Overload Signatures und die Implementierung

Eine überladene Funktion besteht aus zwei Teilen:

1. Overload Signatures: Deklarationen ohne Rumpf, eine pro unterstützter Aufrufform. Nur diese Signaturen können Aufrufer verwenden.
2. Die Implementierungssignatur: die letzte Deklaration, mit Rumpf. Ihre Parameter müssen alles akzeptieren, was die Überladungen akzeptieren, und ihr Rückgabetyp muss den Rückgabetyp jeder Überladung abdecken. Von außen ist sie unsichtbar.

Typen gibt es nur beim Kompilieren, zur Laufzeit existiert also eine JavaScript-Funktion. Die Implementierung muss ihre Argumente untersuchen (typeof, Array.isArray, arguments.length...), um zu entscheiden, was zu tun ist. Der Compiler prüft, dass Überladungen und Implementierung zusammenpassen:

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

Die Lösung ist, die Implementierung zu erweitern: function format(value: string | number): string | number.

Die Implementierungssignatur ist nicht aufrufbar

Diese Regel überrascht am meisten. Ein Aufruf muss für sich allein zu einer der Overload Signatures passen; TypeScript kombiniert sie nicht.

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

Der Compiler gibt aus:

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

Die Implementierung akzeptiert string | string[], aber Aufrufer sehen sie nicht. Füge eine dritte Überladung hinzu, die die Union nimmt und die Union zurückgibt, dann kompiliert der Aufruf und gibt [ 1, 2 ] aus:

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

Unterschiedliche Anzahl von Parametern

Überladungen beschreiben auch Aufrufe mit unterschiedlicher Stelligkeit. Hier lässt sich ein Datum aus einem Zeitstempel oder aus Jahr, Monat und Tag bauen, aber nicht aus zwei Zahlen:

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

Eine einzige Signatur mit zwei optionalen Parametern würde makeDate(2024, 3) akzeptieren und stillschweigend das falsche Datum bauen. Die Überladungen machen daraus einen Compilerfehler (TS2575).

Die Reihenfolge zählt

TypeScript probiert die Überladungen von oben nach unten und nimmt die erste, die passt. Setze die spezifischsten Signaturen an den Anfang. Eine breite Überladung weit oben in der Liste schluckt die Aufrufe, die für die folgenden gedacht sind:

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"

Vertausche die ersten beiden Signaturen, und describe("hi") ist als "text" typisiert.

Überladungen oder ein Union-Parameter?

Überladungen sind ihre zusätzlichen Zeilen wert, wenn der Rückgabetyp von den Argumenttypen abhängt. Ist das nicht so, ist eine Signatur mit Union-Parameter kürzer, leichter zu lesen und akzeptiert Union-Argumente, die Überladungen ablehnen würden.

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

Ein Generic mit einem Conditional Type kann manche Sätze von Überladungen als eine Signatur ausdrücken, aber bei zwei oder drei Fällen sind Überladungen meist leichter zu lesen.

Überladene Methoden und Konstruktoren

Methoden verwenden in einer Klasse dasselbe Muster: Overload Signatures, dann die Methode mit Rumpf. Konstruktoren lassen sich genauso überladen.

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

Auch Interfaces und Objekttypen können Überladungen deklarieren, als mehrere Call Signatures oder mehrere gleichnamige Methodensignaturen. Viele eingebaute Funktionen sind so deklariert: Fahre im Editor mit der Maus über reduce eines Arrays, und es zeigt „+2 overloads“.