Function Overloading TypeScript: Overload Signature

Function overloading di TypeScript berarti menulis beberapa call signature untuk satu fungsi, lalu diikuti satu implementasi. Setiap signature bisa memasangkan tipe parameter yang berbeda dengan tipe kembalian yang berbeda, dan pemanggil mendapat tipe yang tepat.

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

Tanpa overload, parse akan mengembalikan number | number[] di setiap pemanggilan, dan one + 1 akan menjadi error sampai kamu mempersempit hasilnya sendiri.

Overload Signature dan Implementasinya

Fungsi yang di-overload punya dua bagian:

1. Overload signature: deklarasi tanpa badan, satu untuk setiap bentuk pemanggilan yang didukung. Hanya signature inilah yang bisa dipakai pemanggil.
2. Implementation signature: deklarasi terakhir, yang punya badan. Parameternya harus menerima semua yang diterima overload, dan tipe kembaliannya harus mencakup tipe kembalian setiap overload. Signature ini tidak terlihat dari luar.

Tipe hanya ada saat kompilasi, jadi saat runtime hanya ada satu fungsi JavaScript. Implementasinya harus memeriksa argumennya (typeof, Array.isArray, arguments.length...) untuk memutuskan apa yang dilakukan. Compiler memeriksa bahwa overload dan implementasinya sesuai:

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

Perbaikannya adalah memperlebar implementasinya: function format(value: string | number): string | number.

Implementation Signature Tidak Bisa Dipanggil

Inilah aturan yang paling sering mengejutkan. Sebuah pemanggilan harus cocok dengan salah satu overload signature secara mandiri; TypeScript tidak menggabungkannya.

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

Compiler mencetak:

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

Implementasinya menerima string | string[], tetapi pemanggil tidak bisa melihatnya. Tambahkan overload ketiga yang menerima union dan mengembalikan union, maka pemanggilan itu bisa dikompilasi dan mencetak [ 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);
}

Jumlah Parameter yang Berbeda

Overload juga bisa mendeskripsikan pemanggilan dengan jumlah argumen yang berbeda. Di sini, sebuah tanggal bisa dibuat dari timestamp atau dari tahun, bulan, dan hari, tetapi tidak dari dua angka:

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

Satu signature dengan dua parameter opsional akan menerima makeDate(2024, 3) dan diam-diam membuat tanggal yang salah. Overload mengubahnya menjadi error kompilasi (TS2575).

Urutan Itu Penting

TypeScript mencoba overload dari atas ke bawah dan memilih yang pertama cocok. Taruh signature yang paling spesifik lebih dulu. Overload yang luas di awal daftar akan menelan pemanggilan yang seharusnya untuk overload setelahnya:

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"

Tukar dua signature pertama, dan describe("hi") akan bertipe "text".

Overload atau Parameter Union?

Overload sepadan dengan baris tambahannya ketika tipe kembalian bergantung pada tipe argumen. Kalau tidak, satu signature dengan parameter union lebih pendek, lebih mudah dibaca, dan menerima argumen union yang akan ditolak oleh overload.

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

Generic dengan conditional type bisa mengekspresikan sebagian kumpulan overload sebagai satu signature, tetapi untuk dua atau tiga kasus, overload biasanya lebih mudah dibaca.

Method dan Constructor yang Di-overload

Method memakai pola yang sama di dalam class: overload signature, lalu method dengan badannya. Constructor juga bisa di-overload dengan cara yang sama.

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 dan object type juga bisa mendeklarasikan overload, sebagai beberapa call signature atau beberapa method signature dengan nama yang sama. Banyak fungsi bawaan dideklarasikan dengan cara ini: arahkan kursor ke reduce pada sebuah array di editor dan akan muncul "+2 overloads".