TypeScript typeof: type guards ואופרטור הטיפוסים typeof

ל-typeof יש שתי משמעויות ב-TypeScript. בביטוי הוא האופרטור של JavaScript: הוא רץ, מחזיר מחרוזת כמו "string" או "number", ו-TypeScript מצמצם את המשתנה כשמשווים את המחרוזת הזו. במיקום של טיפוס הוא type query: typeof config נותן את הטיפוס הסטטי של המשתנה config.

// 1. The runtime operator: a check that narrows
function double(value: string | number): string | number {
  if (typeof value === "string") {
    return value.repeat(2); // value: string
  }
  return value * 2;         // value: number
}
console.log(double("ab"), double(21)); // abab 42

// 2. The type query: reuse the type of an existing value
const defaults = { retries: 3, verbose: false };
type Options = typeof defaults; // { retries: number; verbose: boolean }

const custom: Options = { retries: 5, verbose: true };
console.log(typeof custom, custom); // object { retries: 5, verbose: true }

השורה האחרונה מראה את ההבדל: typeof custom בתוך console.log הוא האופרטור של זמן הריצה ומדפיס object, ואילו typeof defaults אחרי type Options = הוא השאילתה של זמן הקומפילציה ולעולם לא מגיע ל-JavaScript.

שתי המשמעויות במבט אחד

TypeScript מבחין ביניהם לפי המיקום, כך שאותה מילת מפתח אף פעם לא מתכוונת לשניהם בבת אחת.

התוצאות של typeof בזמן ריצה

האופרטור של זמן הריצה מחזיר אחת משמונה מחרוזות. הריצו את הקוד כדי לראות מה ערכים נפוצים נותנים:

const samples: [string, unknown][] = [
  ['"hi"', "hi"],
  ["42", 42],
  ["NaN", NaN],
  ["10n", 10n],
  ["true", true],
  ["undefined", undefined],
  ["null", null],
  ["{}", {}],
  ["[]", []],
  ["new Date(0)", new Date(0)],
  ['new String("x")', new String("x")],
  ["() => 1", () => 1],
  ["class A {}", class A {}],
  ['Symbol("id")', Symbol("id")],
];

for (const [label, value] of samples) {
  console.log(label.padEnd(16), typeof value);
}

ב-JavaScript רגיל, typeof על משתנה שמעולם לא הוצהר מחזיר "undefined" במקום לזרוק שגיאה. ב-TypeScript קוד כזה לא מתקמפל: Cannot find name 'notDeclared'. (TS2304).

צמצום עם typeof

השוואה של typeof בתוך if, switch, אופרטור טרנרי או אחרי && מצמצמת את המשתנה בכל ענף. זו הדרך הסטנדרטית לטפל ב-union של טיפוסים פרימיטיביים, והבדיקה הראשונה שכדאי לנסות על unknown.

function format(value: unknown): string {
  switch (typeof value) {
    case "string":
      return `"${value}"`;                 // value: string
    case "number":
    case "bigint":
      return value.toLocaleString("en-US"); // value: number | bigint
    case "boolean":
      return value ? "yes" : "no";         // value: boolean
    case "function":
      return `function ${value.name}()`;   // value: Function
    default:
      return String(value);
  }
}

console.log(format("hi"));          // "hi"
console.log(format(1234567.891));   // 1,234,567.891
console.log(format(2n ** 64n));     // 18,446,744,073,709,551,616
console.log(format(true));          // yes
console.log(format(Math.max));      // function max()
console.log(format(undefined));     // undefined

typeof x !== "string" מצמצם בכיוון השני, לכל מה שאינו string. והקומפיילר מכיר את שמונה המחרוזות האפשריות, כך ששגיאת כתיב בהשוואה היא שגיאת קומפילציה ולא בדיקה שתמיד מחזירה false בשקט:

// This does not compile: "strnig" is not a possible typeof result.
function kind(value: string | number): string {
  if (typeof value === "strnig") {
    return "text";
  }
  return "number";
}

console.log(kind("hey"));

הקומפיילר מדפיס index.ts(3,7): error TS2367: This comparison appears to be unintentional because the types '"bigint" | "boolean" | "function" | "number" | "object" | "string" | "symbol" | "undefined"' and '"strnig"' have no overlap. ב-JavaScript רגיל, שגיאת הכתיב הייתה שולחת בשקט כל מחרוזת למסלול של number. תקנו את האיות והקוד ידפיס text.

המלכודת של typeof null

מכיוון ש-typeof null הוא "object", TypeScript מצמצם את typeof x === "object" ל-object | null, לא ל-object. הוסיפו בדיקת null, אחרת קריאת מאפיין היא שגיאה (TS18047 'x' is possibly 'null'.).

function hasId(value: unknown): boolean {
  // typeof alone leaves value as object | null
  if (typeof value === "object" && value !== null) {
    // value: object
    return "id" in value;
  }
  return false;
}

console.log(hasId({ id: 7 }));  // true
console.log(hasId(null));       // false
console.log(hasId([1, 2]));     // false (arrays pass the typeof check but have no id)
console.log(hasId("id"));       // false

typeof לא יכול להבחין בין מערכים, תאריכים, maps ואובייקטים רגילים: כולם "object". השתמשו ב-Array.isArray(x) למערכים וב-x instanceof Date למופעים של מחלקות. לא typeof ולא שום דבר אחר יכול לבדוק בזמן ריצה אם ערך תואם ל-interface, כי interfaces נמחקים; לשם כך כתבו פונקציית type guard שבודקת את המאפיינים.

typeof במיקומים של טיפוס

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

const theme = {
  primary: "#3178c6",
  spacing: 8,
  dark: false,
};

type Theme = typeof theme;
// { primary: string; spacing: number; dark: boolean }

function withSpacing(t: Theme, factor: number): Theme {
  return { ...t, spacing: t.spacing * factor };
}

console.log(withSpacing(theme, 2)); // { primary: '#3178c6', spacing: 16, dark: false }

let userName = "Ada";
const fixed = "Ada";
type A = typeof userName; // string
type B = typeof fixed;    // "Ada" (a const keeps its literal type)

התוצאה תלויה באופן שבו המשתנה הוצהר: let או מאפיין של אובייקט מורחבים (string, number), ו-const פרימיטיבי שומר על הטיפוס הליטרלי שלו. הוסיפו as const לאובייקט או למערך, ו-typeof ייתן טיפוסים ליטרליים לקריאה בלבד לכל העומק. typeof מקבל גם גישה למאפיין, typeof theme.spacing הוא number, אבל לא ביטויים שרירותיים: type T = typeof getTheme(); היא שגיאת תחביר (';' expected., TS1005). לטיפוס שקריאה מחזירה, השתמשו ב-ReturnType<typeof getTheme>.

keyof typeof: המפתחות של אובייקט כטיפוס

keyof typeof obj הוא השילוב הנפוץ ביותר. typeof הופך את האובייקט לטיפוס, keyof לוקח את המפתחות שלו, ומקבלים union של שמות המאפיינים שנשאר נכון גם כשהאובייקט משתנה.

const prices = { apple: 1.2, pear: 0.8, kiwi: 0.5 };

type Fruit = keyof typeof prices; // "apple" | "pear" | "kiwi"

function priceOf(fruit: Fruit, quantity: number): string {
  return (prices[fruit] * quantity).toFixed(2);
}

console.log(priceOf("pear", 3)); // 2.40

// @ts-expect-error: Argument of type '"mango"' is not assignable to parameter of type '"apple" | "kiwi" | "pear"'.
priceOf("mango", 1);

אותו טריק על מערך קבוע נותן union של הערכים שלו: עם const roles = ["admin", "editor"] as const, הטיפוס (typeof roles)[number] הוא "admin" | "editor". בלי as const הוא היה רק string. העמוד keyof מסביר את keyof לבדו.

ReturnType<typeof fn> ו-typeof על מחלקות

טיפוסי עזר כמו ReturnType ו-Parameters מקבלים טיפוס של פונקציה. שם של פונקציה הוא ערך, ולכן העבירו אותו קודם דרך typeof:

function createUser(name: string, admin = false) {
  return { id: name.toLowerCase(), name, admin };
}

type User = ReturnType<typeof createUser>;
// { id: string; name: string; admin: boolean }
type CreateArgs = Parameters<typeof createUser>;
// [name: string, admin?: boolean | undefined]

const args: CreateArgs = ["Grace", true];
const user: User = createUser(...args);
console.log(user); // { id: 'grace', name: 'Grace', admin: true }

כתיבת ReturnType<createUser> נכשלת עם 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749), וזה הקומפיילר שמבקש בדיוק את זה.

מחלקות הן המקרה היחיד שבו שם הוא גם ערך וגם טיפוס. User כטיפוס פירושו מופע של המחלקה; typeof User פירושו המחלקה עצמה, ה-constructor, כולל האיברים הסטטיים שלה:

class Point {
  static origin = new Point(0, 0);
  constructor(public x: number, public y: number) {}
}

const p: Point = new Point(1, 2);        // an instance
const Ctor: typeof Point = Point;        // the class (constructor + statics)
const q = new Ctor(3, 4);                // q: Point
type Instance = InstanceType<typeof Point>; // Point

typeof מול instanceof מול type guard

בחרו את הכלי הצר ביותר שמתאים. למופעים של מחלקות ראו instanceof; למבנים שמתוארים על ידי interface, פונקציית type guard היא הבדיקה היחידה שזמינה בזמן ריצה.