أنواع الدوال في TypeScript: صياغة السهم وأنواع callbacks

يصف نوع الدالة معاملات الدالة وقيمتها المُعادة، ويُكتب بسهم: (a: number, b: number) => number. سمّه بـ type فتستطيع استخدامه للمتغيرات والمعاملات وخصائص الكائنات.

type Operation = (a: number, b: number) => number;

const add: Operation = (a, b) => a + b;       // a and b are number
const multiply: Operation = (x, y) => x * y;  // names do not have to match

function apply(op: Operation, a: number, b: number): number {
  return op(a, b);
}

console.log(apply(add, 2, 3));      // 5
console.log(apply(multiply, 2, 3)); // 6

الدالة المسندة إلى add لا تحتاج إلى تعليقات أنواع: تأتي أنواع معاملاتها من Operation. يُسمى هذا الأنواع السياقية (contextual typing)، وهو السبب الرئيسي لتسمية أنواع الدوال.

صياغة نوع الدالة

الشكل هو (parameters) => ReturnType. يحتاج كل معامل إلى اسم ونوع. الأسماء موجودة لسهولة القراءة ولتلميحات المحرر؛ فأي دالة بأنواع معاملات متوافقة تطابق، أيًا كانت الأسماء التي تستخدمها.

type Predicate = (value: number) => boolean;
type Formatter = (value: number, digits?: number) => string; // optional parameter
type Logger = (...parts: string[]) => void;                    // rest parameter
type Factory = () => { id: number };                           // no parameters

الاسم ليس اختياريًا. يعلن (string) => void معاملًا اسمه string بلا نوع، ويرفضه الوضع الصارم بـ TS7051: Parameter has a name but no type. Did you mean 'arg0: string'?. اكتب (value: string) => void.

تحديد أنواع الدوال السهمية

يمكن تحديد نوع الدالة السهمية بطريقتين. حدد نوع الدالة نفسها، أو حدد نوع المتغير بنوع دالة ودع المعاملات تُستنتج.

// 1. Annotations on the function
const toCelsius = (f: number): number => ((f - 32) * 5) / 9;

// 2. A function type on the variable
const toFahrenheit: (c: number) => number = (c) => (c * 9) / 5 + 32;

// 3. The same, with a named type
type Convert = (value: number) => number;
const round1: Convert = (v) => Math.round(v * 10) / 10;

console.log(round1(toCelsius(100)));  // 37.8
console.log(toFahrenheit(37));        // 98.6

الصيغة 1 هي الخيار المعتاد لدالة مستقلة. وتؤتي الصيغة 3 ثمارها عندما تشترك عدة دوال في توقيع واحد (معالجات، ودوال مقارنة، ودوال تحويل)، لأن التوقيع يُكتب مرة واحدة وأي تغيير فيه يُفحص في كل مكان.

أنواع Callbacks

المعامل الذي نوعه نوع دالة هو callback. تُفحص دالة المستدعي مقابله، وتُستنتج معاملاتها منه.

function repeat(times: number, action: (index: number) => void): void {
  for (let i = 0; i < times; i++) action(i);
}

repeat(3, (i) => console.log("run", i));

function mapValues(values: number[], fn: (value: number, index: number) => string): string[] {
  const out: string[] = [];
  values.forEach((v, i) => out.push(fn(v, i)));
  return out;
}

// A callback may ignore trailing parameters: this one takes only value.
console.log(mapValues([1.5, 2.25], (v) => v.toFixed(1))); // [ '1.5', '2.3' ]

قاعدتان تجعلان استخدام الـ callbacks مريحًا:

• المعاملات الأقل مقبولة. يمكن تمرير دالة تأخذ معاملًا واحدًا حيث يُعرض معاملان. تتجاهل JavaScript الوسائط الإضافية، فتسمح TypeScript بذلك. أما المعاملات الأكثر مما يعرضه النوع فخطأ (Target signature provides too few arguments.).
• القيمة المُعادة void تقبل أي شيء. الـ callback الذي نوعه (...) => void يمكن أن يعيد قيمة؛ والمستدعي يتعهد بعدم استخدامها. ولهذا يُترجم list.forEach((x) => other.push(x)) رغم أن push تعيد رقمًا.

يجب أن تظل أنواع المعاملات متوافقة. تمرير (x: string) => ... حيث يُتوقع (a: number, b: number) => number يفشل بـ Types of parameters 'x' and 'a' are incompatible.

Call Signatures

(n: number) => string اختصار لنوع كائن فيه call signature: { (n: number): string }. تحتاج إلى الصيغة الطويلة عندما تحمل الدالة خصائص أيضًا.

type Counter = {
  (): number;        // call signature: calling it returns a number
  count: number;     // and it has a property
  reset: () => void; // and a method
};

function makeCounter(): Counter {
  const fn = () => ++fn.count;
  fn.count = 0;
  fn.reset = () => { fn.count = 0; };
  return fn;
}

const next = makeCounter();
next();
next();
console.log(next(), next.count); // 3 3
next.reset();
console.log(next.count);         // 0

تتيح لك TypeScript إضافة خصائص إلى دالة معلنة بـ const في النطاق نفسه، وتتتبعها في نوع الدالة. ويمكن للواجهة أن تحمل call signature أيضًا: interface Counter { (): number; count: number }.

يصف construct signature شيئًا يُستدعى بـ new. يضيف new في البداية: new (name: string) => User، أو { new (name: string): User } بصيغة الكائن. وبه تحدد نوع معامل يستقبل صنفًا.

صياغة method مقابل صياغة الخاصية

في نوع كائن، يمكن كتابة عضو الدالة كـ method، handle(value: string): void، أو كخاصية تحمل دالة، handle: (value: string) => void. يبدوان قابلين للاستبدال لكنهما يُفحصان بشكل مختلف تحت strict:

// This does not compile: the property form checks parameters strictly.
interface WithMethod { handle(value: string | number): void }
interface WithProperty { handle: (value: string | number) => void }

const onlyStrings = (value: string) => console.log(value.toUpperCase());

const a: WithMethod = { handle: onlyStrings };   // accepted
const b: WithProperty = { handle: onlyStrings }; // rejected
a.handle(42);

يبلّغ المترجم:

index.ts(8,27): error TS2322: Type '(value: string) => void' is not assignable to type '(value: string | number) => void'.
  Types of parameters 'value' and 'value' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.

الخطأ في محله: onlyStrings لا تستطيع التعامل مع رقم. أما صيغة method فتمرر الخطأ نفسه (معاملات methods تُفحص «bivariantly» لأسباب تاريخية)، وكان a.handle(42) سينهار وقت التشغيل بـ TypeError: value.toUpperCase is not a function. احذف سطر b لترى هذا الانهيار. عندما تكتب أنواع كائناتك، تكتشف صيغة الخاصية أخطاء أكثر.

تجنب النوع Function

Function هو النوع المدمج الذي تحققه كل قيمة دالة. ونادرًا ما يكون ما تريده: لا تعرف TypeScript المعاملات ولا نوع القيمة المُعادة، فيُقبل كل استدعاء ويعيد any.

const loose: Function = Math.max;
const result = loose("a", {});   // compiles: any arguments, result is any
console.log(result);             // NaN

const strict: (...values: number[]) => number = Math.max;
console.log(strict(3, 9, 4));    // 9
// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
strict("a");

استبدل Function بالتوقيع الحقيقي. وعندما تقبل فعلًا أي دالة (مثل debounce عامة أو غلاف للتسجيل)، يقبل (...args: never[]) => unknown كل الدوال ويُبقي الناتج unknown بدل any. وللدوال التي تعتمد أنواعها على مدخلاتها، انظر الأنواع العامة: نوع الدالة العامة يبدو هكذا <T>(value: T) => T.