TypeScript Function Overloading: חתימות overload

Function overloading ב-TypeScript פירושו לכתוב כמה חתימות קריאה לפונקציה אחת, ואחריהן מימוש יחיד. כל חתימה יכולה לצמד טיפוסי פרמטרים שונים לטיפוס החזרה שונה, ומי שקורא לפונקציה מקבל את הטיפוס המדויק.

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

בלי ה-overloads, parse היה מחזיר number | number[] בכל קריאה, ו-one + 1 היה שגיאה עד שהייתם מצמצמים את התוצאה בעצמכם.

חתימות overload והמימוש

לפונקציה עם overloads יש שני חלקים:

1. חתימות overload: הצהרות בלי גוף, אחת לכל צורת קריאה נתמכת. אלה החתימות היחידות שמי שקורא לפונקציה יכול להשתמש בהן.
2. חתימת המימוש: ההצהרה האחרונה, זו עם הגוף. הפרמטרים שלה חייבים לקבל את כל מה שה-overloads מקבלים, וטיפוס ההחזרה שלה חייב לכסות את טיפוס ההחזרה של כל overload. היא לא נראית מבחוץ.

טיפוסים קיימים רק בזמן הקומפילציה, ולכן בזמן ריצה יש פונקציית JavaScript אחת. המימוש צריך לבדוק את הארגומנטים שלו (typeof, Array.isArray, arguments.length...) כדי להחליט מה לעשות. הקומפיילר בודק שה-overloads והמימוש מתאימים זה לזה:

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

הפתרון הוא להרחיב את המימוש: function format(value: string | number): string | number.

אי אפשר לקרוא לחתימת המימוש

זה הכלל שמפתיע הכי הרבה אנשים. קריאה צריכה להתאים בעצמה לאחת מחתימות ה-overload; TypeScript לא משלב ביניהן.

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

הקומפיילר מדפיס:

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

המימוש מקבל string | string[], אבל מי שקורא לפונקציה לא רואה אותו. הוסיפו overload שלישי שמקבל את ה-union ומחזיר את ה-union, והקריאה מתקמפלת ומדפיסה [ 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);
}

מספר שונה של פרמטרים

overloads מתארים גם קריאות עם מספר שונה של ארגומנטים. כאן אפשר לבנות תאריך מ-timestamp או משנה, חודש ויום, אבל לא משני מספרים:

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

חתימה אחת עם שני פרמטרים אופציונליים הייתה מקבלת את makeDate(2024, 3) ובונה בשקט תאריך שגוי. ה-overloads הופכים את זה לשגיאת קומפילציה (TS2575).

הסדר חשוב

TypeScript מנסה את ה-overloads מלמעלה למטה ובוחר את הראשון שמתאים. שימו את החתימות הספציפיות ביותר ראשונות. overload רחב שמופיע מוקדם ברשימה בולע את הקריאות שנועדו לאלה שאחריו:

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"

החליפו את הסדר של שתי החתימות הראשונות, ו-describe("hi") יקבל את הטיפוס "text".

overloads או פרמטר union?

overloads שווים את השורות הנוספות כשטיפוס ההחזרה תלוי בטיפוסי הארגומנטים. כשהוא לא תלוי, חתימה אחת עם פרמטר union קצרה יותר, קלה יותר לקריאה, ומקבלת ארגומנטים מסוג union ש-overloads היו דוחים.

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

גנרי עם conditional type יכול לבטא חלק מקבוצות ה-overloads כחתימה אחת, אבל בשניים או שלושה מקרים overloads בדרך כלל קלים יותר לקריאה.

מתודות ובנאים עם overloads

מתודות משתמשות באותה תבנית בתוך מחלקה: חתימות overload, ואחריהן המתודה עם הגוף. אפשר לעשות overload לבנאים באותה דרך.

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

גם interfaces וטיפוסי אובייקט יכולים להצהיר על overloads, בתור כמה חתימות קריאה או כמה חתימות מתודה עם אותו שם. הרבה פונקציות מובנות מוצהרות כך: רחפו עם העכבר מעל reduce של מערך בעורך, ותראו "+2 overloads".