פרמטרים אופציונליים ב-TypeScript: ערכי ברירת מחדל ו-rest

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

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScript בודק את מספר הארגומנטים, ולכן בלי ה-? הקריאה הראשונה הייתה שגיאת קומפילציה: Expected 2 arguments, but got 1. (TS2554).

פרמטרים אופציונליים עלולים להיות undefined

מכיוון שמי שקורא לפונקציה יכול להשמיט אותו, הטיפוס של פרמטר אופציונלי בתוך הפונקציה הוא T | undefined. תחת strictNullChecks צריך לטפל במקרה של undefined לפני שמשתמשים בו כ-T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

Optional chaining (?.) ו-nullish coalescing (??) הם הכלים הרגילים כאן. כשערך הגיבוי קבוע, פרמטר עם ברירת מחדל קצר יותר.

ערכי ברירת מחדל לפרמטרים

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

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

מי שקורא לפונקציה רואה את החתימה repeat(text: string, times?: number, separator?: string). ברירות מחדל פועלות לפי הכלל של JavaScript: הן חלות כשהארגומנט הוא undefined, בין אם הושמט ובין אם הועבר במפורש, ולא כשהוא null. ביטוי ברירת מחדל יכול להשתמש בפרמטרים קודמים: function range(start: number, end = start + 10).

כללי סדר הפרמטרים

פרמטר עם ברירת מחדל לפני פרמטר חובה הוא חוקי אבל מסורבל. הטיפוס שלו עבור מי שקורא הופך ל-number | undefined, ואף אחד לא נהנה לכתוב undefined כממלא מקום. אם צריך פרמטר ראשון גמיש, השתמשו במקום זאת באובייקט אפשרויות או ב-function overloading.

השמטה מול undefined

x?: number ו-x: number | undefined נראים דומים ויש להם אותו טיפוס בתוך הפונקציה. ההבדל הוא אצל מי שקורא: את הראשון אפשר להשמיט, את השני חובה להעביר.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

השתמשו ב-| undefined לארגומנט חובה שמותר לו להיות בלי ערך, כך שכל מי שקורא לפונקציה ייאלץ לחשוב עליו. השתמשו ב-? כשהשמטה היא קריאה רגילה. (ההודעה באמת אומרת "1 arguments": זה הניסוח של TypeScript.)

פרמטרי rest

פרמטר rest, ...name: T[], אוסף כל מספר של ארגומנטים לתוך מערך. הוא חייב להיות הפרמטר האחרון.

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

פרישת מערך לתוך פרמטרים קבועים קפדנית יותר. פרמטר rest מקבל פרישה של כל number[], אבל פונקציה שהוצהרה כ-(a: number, b: number) מקבלת רק פרישה של tuple, כי TypeScript חייב לדעת את האורך:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

גם לפרמטר rest יכול להיות טיפוס tuple, שנותן טיפוס לכל מיקום: ...args: [name: string, age?: number].

אובייקטי אפשרויות

ברגע שלפונקציה יש יותר משניים או שלושה פרמטרים אופציונליים, מי שקורא לה מאבד את המעקב אחרי המיקומים. אובייקט אפשרויות עם ברירות מחדל נותן ארגומנטים עם שמות, בלי חשיבות לסדר.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

ה-= {} בסוף הופך את כל האובייקט לאופציונלי. בלעדיו, fetchData("/a") היא שגיאת קומפילציה (Expected 2 arguments, but got 1., TS2554), וב-JavaScript רגיל אותה קריאה הייתה זורקת TypeError בזמן ריצה, כי destructuring צריך אובייקט לקרוא ממנו.

פרמטרים אופציונליים בטיפוסי callback

בטיפוס פונקציה, ? פירושו "מי שקורא ל-callback הזה עשוי לא להעביר אותו". הוא לא אומר "ה-callback יכול לדלג עליו": callback תמיד יכול להתעלם מפרמטרים בסוף. לכן אל תסמנו פרמטרים של callback כאופציונליים רק כדי לאפשר ל-handlers לקבל פחות ארגומנטים.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);