تحميل الدوال الزائد في TypeScript: Overload Signatures

التحميل الزائد للدوال (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 ]

دون توقيعات التحميل كانت parse ستعيد number | number[] لكل استدعاء، وكان one + 1 سيكون خطأ حتى تضيّق الناتج بنفسك.

توقيعات التحميل والتطبيق

للدالة المحمّلة جزءان:

1. توقيعات التحميل: تصريحات بلا جسم، واحد لكل شكل استدعاء مدعوم. وهي التوقيعات الوحيدة التي يستطيع المستدعون استخدامها.
2. توقيع التطبيق: التصريح الأخير، مع الجسم. يجب أن تقبل معاملاته كل ما تقبله توقيعات التحميل، وأن يغطي نوع قيمته المُعادة نوع القيمة المُعادة لكل توقيع. وهو غير مرئي من الخارج.

الأنواع موجودة وقت الترجمة فقط، لذلك توجد دالة JavaScript واحدة وقت التشغيل. يجب أن يفحص التطبيق وسائطه (typeof وArray.isArray وarguments.length...) ليقرر ما يفعل. ويتحقق المترجم من توافق توقيعات التحميل مع التطبيق:

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.

توقيع التطبيق غير قابل للاستدعاء

هذه القاعدة الأكثر مفاجأة للناس. يجب أن يطابق الاستدعاء أحد توقيعات التحميل وحده؛ ولا تجمع 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[]، لكن المستدعين لا يرونه. أضف توقيع تحميل ثالثًا يأخذ الـ 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);
}

أعداد مختلفة من المعاملات

يصف التحميل الزائد أيضًا استدعاءات بأعداد وسائط مختلفة. هنا يمكن بناء تاريخ من طابع زمني أو من سنة وشهر ويوم، لكن ليس من رقمين:

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) ويبني التاريخ الخاطئ بصمت. أما توقيعات التحميل فتحوّل ذلك إلى خطأ ترجمة (TS2575).

الترتيب مهم

تجرب TypeScript توقيعات التحميل من الأعلى إلى الأسفل وتختار أول توقيع يطابق. ضع التوقيعات الأكثر تحديدًا أولًا. التوقيع الواسع في بداية القائمة يبتلع الاستدعاءات المقصودة للتوقيعات التي بعده:

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".

التحميل الزائد أم معامل union؟

يستحق التحميل الزائد أسطره الإضافية عندما يعتمد نوع القيمة المُعادة على أنواع الوسائط. وعندما لا يعتمد، يكون توقيع واحد بمعامل union أقصر وأسهل قراءة، ويقبل وسائط union كان التحميل الزائد سيرفضها.

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

يستطيع نوع عام مع نوع شرطي التعبير عن بعض مجموعات التحميل الزائد كتوقيع واحد، لكن مع حالتين أو ثلاث يكون التحميل الزائد عادة أسهل قراءة.

التحميل الزائد للدوال داخل الأصناف وللمُنشئات

تستخدم الدوال داخل الصنف النمط نفسه: توقيعات تحميل، ثم الدالة مع جسمها. ويمكن التحميل الزائد للمُنشئات بالطريقة نفسها.

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

يمكن للواجهات وأنواع الكائنات أيضًا إعلان توقيعات تحميل، كعدة call signatures أو عدة method signatures بالاسم نفسه. وكثير من الدوال المدمجة معلن بهذه الطريقة: مرّر المؤشر فوق reduce على مصفوفة في محرر فيعرض "+2 overloads".