TypeScript type narrowing: איך עובד control flow analysis

Type narrowing הוא TypeScript שמחשב טיפוס ספציפי יותר לערך בנקודה מסוימת בקוד, על סמך הבדיקות שהקוד כבר ביצע. פרמטר מטיפוס string | number הופך ל-string בתוך if (typeof x === "string") ול-number ב-else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

קריאה ל-value.toFixed(2) לפני הבדיקה הייתה שגיאת קומפילציה, כי toFixed לא קיים על string. הבדיקה היא JavaScript רגיל ורצה בזמן ריצה; הצמצום הוא הקומפיילר שקורא אותה ומתאים את הטיפוס. שום דבר נוסף לא נוצר בפלט.

Control flow analysis

TypeScript עוקב אחרי כל מסלול בתוך פונקציה: if/else, return ו-throw מוקדמים, switch, לולאות, ואופרטורי הקיצור &&, ||, ?? ו-?:. בכל נקודה, הטיפוס של משתנה הוא מה שעדיין אפשרי שם.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

סגנון ה-return המוקדם ("guard clauses") הוא הדרך הקריאה ביותר לצמצם: מטפלים קודם במקרים החריגים, ושאר הפונקציה עובד עם הטיפוס הנקי.

כל הדרכים לצמצם

שלוש האחרונות מוסברות בעמודים של type guards ושל discriminated unions. השאר מוסברות בהמשך.

צמצום לפי truthiness

if (x) מסיר null ו-undefined (וגם את הטיפוסים הליטרליים false, 0, ""). זה קצר, ויש בו מלכודת קלאסית אחת: 0 ו-"" הם falsy, ולכן ערכים תקינים מטופלים כחסרים.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

עבור מספרים ומחרוזות, השוו במפורש ל-undefined או ל-null (או השתמשו ב-??). Truthiness מתאים לאובייקטים, למערכים ולפונקציות, שאף פעם אינם falsy.

צמצום לפי שוויון

===, !==, == ו-!= מצמצמים את שני הצדדים. השוואה לליטרל מצמצמת לאותו ליטרל; == null (שוויון רופף) תופס גם null וגם undefined בבדיקה אחת, וזה המקום היחיד שבו שוויון רופף הוא הסגנון המקובל.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

השוואה בין שני משתנים מצמצמת את שניהם למה שיכול להיות משותף להם: אם a: string | number ו-b: string | boolean עוברים את a === b, שניהם string בתוך ה-if.

האופרטור in

"key" in obj מצמצם union של טיפוסי אובייקטים לאיברים שיש להם (או שאולי יש להם) את המאפיין הזה.

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in עובד גם על unknown ברגע שיודעים שזה אובייקט: אחרי typeof v === "object" && v !== null && "id" in v, TypeScript יודע שלאובייקט v יש מאפיין id מטיפוס unknown. עבור unions שאתם מתכננים בעצמכם, מאפיין תגית משותף (kind: "fish") ברור יותר מבדיקה של מתודות: לדפוס הזה קוראים discriminated union.

צמצום לפי השמה

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

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

איפה הצמצום הולך לאיבוד

הצמצום מקומי ושמרני. כמה מצבים מאפסים אותו:

• ביטוי אחר. בדיקה של obj.name מצמצמת את obj.name (ואת obj["name"]), אבל לא את obj[key] כש-key הוא משתנה מטיפוס string ולא ליטרל, וגם לא עותק שנוצר לפני הבדיקה.
• Callbacks והשמה מחדש. בתוך callback, משתנה let מצומצם שומר על הצמצום רק אם לא מושם לו ערך שוב אחרי שה-callback נוצר. const או פרמטר שאף פעם לא מושם לו ערך מחדש נשארים מצומצמים.
• בדיקות שמוסתרות בפונקציות עזר. פונקציה isString(x: unknown): boolean לא אומרת לקומפיילר כלום. תנו לה טיפוס החזרה של type predicate, x is string, וקריאות אליה יצמצמו כמו ש-typeof מצמצם.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

הקומפיילר מדווח index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. ה-callback יכול לרוץ מאוחר יותר, אחרי x = undefined. מחקו את ההשמה האחרונה (או העתיקו את הערך ל-const בתוך ה-if), והקוד יתקמפל וידפיס 5 פעמיים.

את פונקציית העזר שמחזירה boolean אפשר לתקן בהצהרה על מה שהיא מוכיחה. זה בדיוק type guard:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

מאז TypeScript 5.5 הקומפיילר מסיק predicates כאלה עבור פונקציות חץ פשוטות, ולכן list.filter((x) => x !== undefined) מחזיר היום מערך בלי undefined.