TypeScript type guard: בדיקת הטיפוס של אובייקט

Type guard הוא בדיקה בזמן ריצה ש-TypeScript מבין, ולכן הוא מצמצם את הטיפוס בתוך הענף שנבדק. typeof, instanceof ו-in הם guards מובנים; לכל דבר אחר כותבים פונקציה שטיפוס ההחזרה שלה הוא type predicate, value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser מחזירה ערך בוליאני רגיל בזמן ריצה. טיפוס ההחזרה value is User אומר לקומפיילר מה תוצאה של true מוכיחה, ואז כל if (isUser(x)) מצמצם את x ל-User.

Type guards מובנים

הבדיקות האלה מצמצמות בלי שום פונקציית עזר:

כולן רצות כ-JavaScript רגיל. מה ש-TypeScript מוסיף הוא הצמצום: הוא קורא את הבדיקה ומתאים את הטיפוס בכל ענף. הרשימה המלאה של הצורות נמצאת בעמוד type narrowing. Guard מותאם אישית מיועד לבדיקות שלא נכנסות בביטוי אחד, או שרוצים להשתמש בהן שוב.

כתיבת type predicate

ל-type predicate יש הצורה parameterName is Type, והוא מחליף את boolean כטיפוס ההחזרה. הצמצום עובד בשני הכיוונים: true מצמצם ל-Type, ו-false מסיר את Type מה-union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

העברת guard ל-filter נותנת מערך עם טיפוס נכון. מאז TypeScript 5.5 הקומפיילר גם מסיק predicate מפונקציות חץ פשוטות, כך ש-pets.filter((p) => p.kind === "cat") מחזיר Cat[] בלי guard עם שם.

הטיפוס של ה-predicate חייב להתאים לטיפוס הפרמטר: function f(x: string): x is number היא השגיאה TS2677, A type predicate's type must be assignable to its parameter's type.

הקומפיילר סומך על ה-guard שלכם

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

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) זורק TypeError: Cannot read properties of undefined (reading 'toFixed') בזמן ריצה. הקומפיילר קיבל את data.price כ-number כי ה-guard אמר כך. בדקו כל מאפיין ששאר הקוד מסתמך עליו, ושמרו על guards קטנים, בדוקים וקרובים לטיפוס שהם מתארים.

בדיקה אם אובייקט הוא מטיפוס מסוים

זו השאלה שמאחורי רוב ה-guards המותאמים: נתונים מגיעים כ-unknown (מ-JSON.parse, fetch, localStorage, הודעה) וצריך לדעת אם הם תואמים ל-interface שלכם. המתכון:

1. typeof value === "object" && value !== null (אובייקט, לא null).
2. "prop" in value לכל מאפיין נדרש. על unknown, in מוסיף את המאפיין לטיפוס כ-unknown.
3. typeof value.prop === "..." (או guard מקונן) לטיפוס של כל מאפיין.
4. Array.isArray(value.items) && value.items.every(isItem) למערכים.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

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

פונקציות assertion: asserts value is Type

פונקציית assertion זורקת שגיאה אם הבדיקה נכשלת, ואחרת חוזרת כרגיל. טיפוס ההחזרה שלה הוא asserts value is Type (או asserts condition), וכל מה שבא אחרי הקריאה מצומצם, בלי צורך ב-if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

כלל אחד מכשיל אנשים: חייבים לקרוא לפונקציית assertion דרך שם עם טיפוס מפורש. פונקציית חץ ב-const בלי הערת טיפוס, const check = (v: unknown): asserts v is string => {...}, נותנת את השגיאה TS2775 במקום הקריאה, Assertions require every name in the call target to be declared with an explicit type annotation. השתמשו בהצהרת function, או הוסיפו לקבוע הערת טיפוס של פונקציה.

Guards מול assertions מול casts

Type assertion (as) משנה את הטיפוס בלי לבדוק כלום. בגבול שבו נתונים מגיעים מבחוץ, guard או פונקציית assertion הם הגרסה הבטוחה של אותו רעיון.

Guards מבוססי this במחלקות

מתודה יכולה לצמצם את האובייקט שעליו היא נקראת עם this is Type. זה שימושי בהיררכיות של מחלקות:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}