TypeScript Function Overloading: Overload İmzaları

TypeScript'te function overloading, bir fonksiyon için birkaç çağrı imzası ve ardından tek bir gerçekleme yazmak demektir. Her imza farklı parametre tiplerini farklı bir dönüş tipiyle eşleştirebilir ve çağıran kesin olanı alır.

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

Overload'lar olmasaydı parse her çağrı için number | number[] döndürürdü ve siz sonucu kendiniz daraltana kadar one + 1 bir hata olurdu.

Overload İmzaları ve Gerçekleme

Overload edilmiş bir fonksiyonun iki kısmı vardır:

1. Overload imzaları: desteklenen her çağrı biçimi için bir tane olmak üzere gövdesiz bildirimler. Çağıranların kullanabildiği tek imzalar bunlardır.
2. Gerçekleme imzası (implementation signature): gövdesiyle birlikte son bildirim. Parametreleri overload'ların kabul ettiği her şeyi kabul etmeli, dönüş tipi de her overload'ın dönüş tipini kapsamalıdır. Dışarıdan görünmez.

Tipler yalnızca derleme zamanında vardır, bu yüzden çalışma zamanında tek bir JavaScript fonksiyonu bulunur. Gerçekleme ne yapacağına karar vermek için argümanlarını incelemek zorundadır (typeof, Array.isArray, arguments.length...). Derleyici overload'ların ve gerçeklemenin uyuştuğunu kontrol eder:

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

Çözüm gerçeklemeyi genişletmektir: function format(value: string | number): string | number.

Gerçekleme İmzası Çağrılamaz

İnsanları en çok şaşırtan kural budur. Bir çağrı, overload imzalarından biriyle tek başına eşleşmelidir; TypeScript onları birleştirmez.

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

Derleyici şunu yazdırır:

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

Gerçekleme string | string[] kabul eder, ama çağıranlar onu göremez. Union'ı alıp union döndüren üçüncü bir overload ekleyin, çağrı derlenir ve [ 1, 2 ] yazdırır:

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

Farklı Sayıda Parametreler

Overload'lar farklı sayıda argüman içeren çağrıları da tanımlar. Burada bir tarih bir zaman damgasından ya da yıl, ay ve günden oluşturulabilir, ama iki sayıdan oluşturulamaz:

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

İki opsiyonel parametreli tek bir imza makeDate(2024, 3) çağrısını kabul eder ve sessizce yanlış tarihi oluştururdu. Overload'lar bunu bir derleme hatasına (TS2575) dönüştürür.

Sıra Önemlidir

TypeScript overload'ları yukarıdan aşağıya dener ve eşleşen ilkini seçer. En özel imzaları başa koyun. Listenin başındaki geniş bir overload, sonrakiler için yazılmış çağrıları yutar:

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"

İlk iki imzanın yerini değiştirin, describe("hi") çağrısı "text" olarak tiplenir.

Overload mu, Union Parametre mi?

Overload'lar, dönüş tipi argüman tiplerine bağlı olduğunda fazladan satırlarına değer. Bağlı olmadığında union parametreli tek bir imza daha kısa ve okunaklıdır, üstelik overload'ların reddedeceği union argümanlarını da kabul eder.

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

Bir conditional tip ile birlikte bir generic, bazı overload kümelerini tek bir imza olarak ifade edebilir; ama iki üç durum için overload'ların okunması genellikle daha kolaydır.

Overload Edilmiş Metotlar ve Constructor'lar

Metotlar bir sınıfın içinde aynı kalıbı kullanır: overload imzaları, ardından gövdesi olan metot. Constructor'lar da aynı şekilde overload edilebilir.

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

Interface'ler ve nesne tipleri de, birkaç call signature ya da aynı adı taşıyan birkaç metot imzası olarak overload bildirebilir. Pek çok yerleşik fonksiyon bu şekilde bildirilmiştir: bir editörde bir dizi üzerindeki reduce metodunun üzerine gelin, "+2 overloads" gösterir.