TypeScript as: הסבר על type assertions ו-casting

value as Type הוא type assertion: הוא אומר ל-TypeScript להתייחס ל-value כאל Type. אנשים קוראים לזה cast, אבל זו רק הוראה לקומפיילר. היא נמחקת מפלט ה-JavaScript, לא ממירה כלום ולא בודקת כלום בזמן ריצה.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

זה השימוש הטיפוסי: אתם יודעים על ערך יותר ממה שהקומפיילר יכול לדעת (כאן, את המבנה של JSON מסוים), ואתם אומרים את זה. אם טעיתם, שום דבר לא מזהיר אתכם. הסעיפים הבאים מראים מה זה אומר ומתי בדיקה בזמן ריצה היא הבחירה הטובה יותר.

as ותחביר הסוגריים המשולשים

יש שתי דרכים לכתוב את אותו assertion:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

הצורה עם הסוגריים המשולשים אסורה בקובצי .tsx, שם <string> ייקרא כתגית JSX. השתמשו ב-as בכל מקום, והשאלה לא תעלה אף פעם. Assertions נקשרים בחולשה, ולכן עטפו אותם בסוגריים כשממשיכים את הביטוי: (value as string).length.

Assertions לא ממירים ערכים

זה החלק שגורם לבאגים אמיתיים. Assertion משנה את מה שהקומפיילר מאמין לגבי ערך, לא את הערך עצמו:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

הקומפיילר מאמין ש-asserted הוא number, ולכן asserted + 1 עובר את בדיקת הטיפוסים כחישוב אריתמטי. בזמן ריצה הוא עדיין המחרוזת "42", ו-JavaScript משרשר. כדי לשנות את הטיפוס של ערך, המירו אותו: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). העמוד המרת מחרוזת למספר משווה בין פונקציות ההמרה.

מה הקומפיילר מתיר

as אינו בלתי מוגבל. TypeScript מתיר x as T כשאחד הטיפוסים ניתן להשמה לשני: הרחבה ("a" as string, dog as Animal) וצמצום (animal as Dog, unknown as User) תקינים שניהם. כשאין שום חפיפה בין הטיפוסים, הוא מסרב:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

הקומפיילר מדווח index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. ההודעה עצמה מציינת את פתח המילוט: input as unknown as number. ה-assertion הכפול הזה מתקמפל, והוא שגוי בזמן ריצה בדיוק כמו הדוגמה שלמעלה. כשנראה לכם שאתם צריכים אותו, התיקון הנכון הוא בדרך כלל המרה (Number(input)) או טיפוס אחר.

כלל החפיפה מקל עם אובייקטים. אובייקט ליטרלי שיש לו חלק מהמאפיינים מתקבל, וכך as מעביר בשקט אובייקטים חלקיים:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

הערת טיפוס (const draft: User = { name: "Ada" }) או satisfies User היו מדווחות על ה-email החסר (TS2741). השתמשו ב-as על אובייקט ליטרלי רק כשאתם באמת מתכוונים להשלים אותו מאוחר יותר, והעדיפו לבנות את האובייקט השלם.

as const זה משהו אחר

as const נראה כמו assertion, אבל הוא עושה את ההפך מהקלה: הוא הופך ליטרל לצר ככל האפשר. מחרוזות נשארות טיפוסים ליטרליים, מערכים הופכים ל-tuples לקריאה בלבד, ומאפייני אובייקטים הופכים ל-readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

הוא בטוח, כי הוא מתאר את הליטרל בדיוק ולא טוען משהו שהקומפיילר לא יכול לראות. (ה-sizes as readonly string[] שבתוך isSize הוא assertion מרחיב, גם הוא בטוח: הוא מאפשר ל-includes לקבל כל מחרוזת.) ראו literal types להרחבה.

מתי type guard הוא הכלי הטוב יותר

as הוא טענה; type guard הוא בדיקה. בגבול שבו נתונים מגיעים מחוץ לקוד שלכם (JSON, fetch, localStorage, קלט של משתמש, הודעה), הטענה עלולה להיות שקרית, ו-assertion הופך שגיאה ברורה בגבול לשגיאה מבלבלת במקום אחר.

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

מדריך כללי לכלים שנראים דומים:

נשארים שני שימושים טובים ל-as: צמצום של משהו שהקומפיילר לא יכול לעקוב אחריו (רשומה ב-Map שהגדרתם שתי שורות קודם, ערך מספרייה בלי טיפוסים), וקוד בדיקות שבונה fixtures חלקיים. שמרו עליהם קטנים וקרובים למקום שבו אתם יודעים שהטענה נכונה.