Nạp chồng hàm trong TypeScript: overload signature

Nạp chồng hàm (function overloading) trong TypeScript là viết nhiều chữ ký gọi cho một hàm, theo sau là một phần cài đặt duy nhất. Mỗi chữ ký có thể ghép các kiểu tham số khác nhau với một kiểu trả về khác nhau, và nơi gọi nhận được đúng kiểu chính xác.

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

Nếu không có các overload, parse sẽ trả về number | number[] cho mọi lời gọi, và one + 1 sẽ là lỗi cho đến khi bạn tự thu hẹp kết quả.

Overload signature và phần cài đặt

Một hàm được nạp chồng có hai phần:

1. Overload signature: các khai báo không có thân hàm, mỗi khai báo cho một dạng lời gọi được hỗ trợ. Đây là những chữ ký duy nhất mà nơi gọi dùng được.
2. Chữ ký cài đặt: khai báo cuối cùng, có thân hàm. Tham số của nó phải nhận được mọi thứ các overload nhận, và kiểu trả về của nó phải bao quát kiểu trả về của mọi overload. Từ bên ngoài không nhìn thấy nó.

Kiểu chỉ tồn tại lúc biên dịch, nên lúc chạy chỉ có một hàm JavaScript. Phần cài đặt phải tự xem xét các đối số (typeof, Array.isArray, arguments.length...) để quyết định làm gì. Trình biên dịch kiểm tra rằng các overload và phần cài đặt khớp với nhau:

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

Cách sửa là mở rộng phần cài đặt: function format(value: string | number): string | number.

Không gọi được chữ ký cài đặt

Đây là quy tắc khiến nhiều người bất ngờ nhất. Một lời gọi phải tự khớp với một trong các overload signature; TypeScript không kết hợp chúng lại.

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

Trình biên dịch in ra:

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

Phần cài đặt nhận string | string[], nhưng nơi gọi không thấy được nó. Thêm một overload thứ ba nhận union và trả về union, thế là lời gọi biên dịch được và in ra [ 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);
}

Số lượng tham số khác nhau

Overload cũng mô tả được các lời gọi với số lượng tham số khác nhau. Ở đây một ngày có thể được tạo từ timestamp hoặc từ năm, tháng và ngày, nhưng không thể từ hai số:

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

Một chữ ký duy nhất với hai tham số không bắt buộc sẽ nhận makeDate(2024, 3) và âm thầm tạo ra một ngày sai. Các overload biến điều đó thành lỗi biên dịch (TS2575).

Thứ tự rất quan trọng

TypeScript thử các overload từ trên xuống dưới và chọn overload đầu tiên khớp. Hãy đặt các chữ ký cụ thể nhất lên trước. Một overload quá rộng nằm sớm trong danh sách sẽ nuốt mất những lời gọi dành cho các overload phía sau:

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"

Đổi chỗ hai chữ ký đầu tiên thì describe("hi") có kiểu "text".

Overload hay tham số union?

Overload đáng mấy dòng code thêm khi kiểu trả về phụ thuộc vào kiểu của đối số. Khi không phải vậy, một chữ ký với tham số union sẽ ngắn hơn, dễ đọc hơn, và nhận được các đối số union mà overload sẽ từ chối.

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

Một generic kết hợp với conditional type có thể diễn đạt một số bộ overload bằng một chữ ký, nhưng với hai hay ba trường hợp thì overload thường dễ đọc hơn.

Nạp chồng phương thức và hàm khởi tạo

Phương thức dùng cùng mẫu này bên trong lớp: các overload signature, rồi đến phương thức có thân. Hàm khởi tạo cũng nạp chồng được theo cách tương tự.

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 và kiểu đối tượng cũng khai báo được overload, dưới dạng nhiều chữ ký gọi hoặc nhiều chữ ký phương thức trùng tên. Nhiều hàm có sẵn được khai báo theo cách này: di chuột lên reduce của một mảng trong trình soạn thảo sẽ thấy "+2 overloads".