TypeScript Function: טיפוסי פרמטרים והחזרה, void

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

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

שתי הקריאות השגויות הן שגיאות בזמן קומפילציה (TS2345 ו-TS2554). ההערות // @ts-expect-error אומרות לקומפיילר שצפויה שגיאה בשורה הבאה, כך ששאר הקובץ עדיין רץ. הסירו אחת מהן והריצו שוב כדי לראות את ההודעה האמיתית.

טיפוסי פרמטרים

כל פרמטר נכתב name: Type. תחת strict, שפועל כברירת מחדל ב-TypeScript 7, פרמטר בלי הערת טיפוס ובלי הקשר שממנו אפשר להסיק הוא שגיאה: Parameter 'x' implicitly has an 'any' type. (TS7006). לכן בפועל כל פרמטר של פונקציה עצמאית מקבל הערת טיפוס.

כל טיפוס יכול לשמש כטיפוס של פרמטר: טיפוסים פרימיטיביים, מערכים, טיפוסי אובייקט, unions ופונקציות אחרות.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

TypeScript בודק גם את מספר הארגומנטים. העברה של יותר או פחות ארגומנטים ממה שהפונקציה מצהירה היא שגיאה, בניגוד ל-JavaScript רגיל, שממלא ארגומנטים חסרים ב-undefined ומתעלם מעודפים. כדי להפוך פרמטר לאופציונלי או לתת לו ערך ברירת מחדל, ראו פרמטרים אופציונליים.

טיפוסי החזרה: לכתוב או להסיק

טיפוס ההחזרה בא אחרי הסוגר של רשימת הפרמטרים: function f(): Type. הוא אופציונלי. בלעדיו, TypeScript מסיק את הטיפוס מכל return בגוף הפונקציה.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

הערת טיפוס מצדיקה את מקומה כשהפונקציה מיוצאת, כשיש לה כמה מסלולי החזרה, או כשהיא רקורסיבית. השגיאה מופיעה אז בתוך הפונקציה, ב-return השגוי, ולא אצל מי שקורא לה. מקרה קלאסי הוא ענף ששוכח להחזיר ערך:

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

הקומפיילר מדווח index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. הוסיפו return "C"; בסוף והקוד ירוץ. בלי ההערה : string הפונקציה הייתה מתקמפלת עם הטיפוס המוסק "A" | "B" | undefined, והבעיה הייתה עוברת למי שמשתמש בתוצאה.

void: פונקציות שלא מחזירות כלום

לפונקציה שרק עושה משהו (כותבת ללוג, שומרת, משנה נתונים) יש טיפוס ההחזרה void. זה מה ש-TypeScript מסיק כשאין return עם ערך, ואפשר גם לכתוב אותו במפורש.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

הכללים האלה על void מפתיעים אנשים:

השורה השנייה מכוונת. בגללה arr.forEach(x => list.push(x)) מתקמפל, למרות ש-push מחזיר מספר. void בטיפוס של פונקציה אומר "לא משנה מה זה מחזיר, אף אחד לא קורא את זה". לפונקציה שאף פעם לא מסיימת (היא תמיד זורקת שגיאה או נכנסת ללולאה אינסופית), טיפוס ההחזרה הוא never.

פונקציות חץ ו-function expressions

פונקציות חץ ו-function expressions מקבלות את אותן הערות טיפוס. טיפוס ההחזרה בא אחרי רשימת הפרמטרים, לפני =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

בלי הסוגריים, (x, y) => { x, y } הוא בלוק בלי return, והפונקציה מחזירה undefined. כללי זמן הריצה של פונקציות חץ (אין להן this משלהן, אין arguments) זהים לאלה של JavaScript; ראו פונקציות חץ ב-JavaScript.

כשפונקציה נכתבת ישירות כארגומנט, בדרך כלל לא כותבים טיפוסים לפרמטרים שלה בכלל. TypeScript יודע מה ה-callback מקבל מתוך הפונקציה שאליה הוא מועבר (contextual typing): ב-[1, 2].map(n => n * 2), ה-n כבר number. כתיבת הטיפוס של פונקציה כערך, (n: number) => string, מוסברת בעמוד על טיפוסי פונקציות.

החזרה של כמה ערכים

פונקציה מחזירה ערך אחד, אז החזירו אובייקט או tuple ועשו להם destructuring.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

טיפוס ההחזרה מסוג tuple צריך הערת טיפוס. בלעדיה, [a, b] מוסק כ-string[]: ה-destructuring עדיין עובד, אבל הטיפוס כבר לא אומר שיש בדיוק שני איברים.

פונקציות async

פונקציית async תמיד מחזירה Promise. כתבו את טיפוס ההחזרה בתור Promise<T>, כאשר T הוא מה שהפונקציה מחזירה בפנים.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

הכתיבה async function f(): number היא שגיאה: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

הפרמטר this

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

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

בלי הפרמטר this, ה-this בתוך פונקציה עצמאית הוא any מרומז, ומצב strict מדווח 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). במתודות של מחלקה this כבר מקבל את הטיפוס של המופע, ולכן הפרמטר שימושי בעיקר לפונקציות עצמאיות שמוצמדות לאובייקטים ול-callbacks שספריות קוראות להם עם this מסוים.