keyof ב-TypeScript: המפתחות של אובייקט כטיפוס, עם דוגמאות

keyof מקבל טיפוס אובייקט ומייצר את ה-union של שמות המאפיינים שלו. keyof User שלמטה הוא הטיפוס "id" | "name" | "email", ולכן משתנה מהטיפוס הזה יכול להכיל רק אחת משלוש המחרוזות האלה.

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

type UserKey = keyof User; // "id" | "name" | "email"

const key: UserKey = "name"; // OK
// @ts-expect-error: "age" is not one of the keys of User
const wrong: UserKey = "age";

function printField(user: User, field: keyof User) {
  console.log(`${field}: ${user[field]}`);
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };
printField(ada, "email"); // email: ada@example.com
printField(ada, key);     // name: Ada

keyof קיים רק במערכת הטיפוסים. הוא נמחק כשהקוד מתקמפל, ולכן הוא אף פעם לא בודק שום דבר בזמן ריצה. מה שהוא נותן לכם הוא הבטחה בזמן קומפילציה שמפתח הוא שם של מאפיין אמיתי: שנו את השם של email ב-interface, וכל "email" שהטיפוס שלו keyof User יהפוך לשגיאה.

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

keyof עובד על טיפוסים, לא על ערכים. עבור אובייקט שכתבתם כערך, קבלו קודם את הטיפוס שלו עם typeof, ואז קחו את המפתחות:

const colors = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};

type Color = keyof typeof colors; // "red" | "green" | "blue"

function hex(color: Color): string {
  return colors[color];
}

console.log(hex("green")); // #00ff00
// hex("purple") would be error TS2345:
// Argument of type '"purple"' is not assignable to parameter of type '"blue" | "green" | "red"'.

קראו את זה מבפנים החוצה: typeof colors הוא { red: string; green: string; blue: string }, ו-keyof שלו הוא ה-union של המפתחות. כתיבת keyof colors בלי typeof נכשלת עם error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

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

גישה מוטפסת למאפיינים עם גנריקס

השימוש הנפוץ ביותר ב-keyof הוא אילוץ גנרי. K extends keyof T אומר "K הוא אחד המפתחות של T", ו-T[K] הוא הטיפוס של המאפיין במפתח הזה:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const book = { title: "Dune", pages: 412, inStock: true };

const pages = getProperty(book, "pages"); // number
const title = getProperty(book, "title"); // string

console.log(pages + 1);           // 413
console.log(title.toUpperCase()); // DUNE
// getProperty(book, "author") would be error TS2345

פרמטר הטיפוס השני חשוב. עם key: keyof T ובלי K, טיפוס ההחזרה הוא T[keyof T], ה-union של כל טיפוסי המאפיינים (כאן string | number | boolean), ולכן title.toUpperCase() היה נכשל עם error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. לכידת המפתח המדויק ב-K שומרת על הטיפוס המדויק של המאפיין. T[K] הוא indexed access type, שמוסבר בעמוד על indexed access types.

גישה עם string רגיל

שגיאה נפוצה מאוד מופיעה כשניגשים לאובייקט עם string שהגיע ממקום אחר:

// This does not compile: a plain string is not a key of Settings
interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

function read(name: string) {
  return settings[name];
}

console.log(read("theme"));

הקומפיילר מדפיס:

index.ts(10,10): error TS7053: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Settings'.
  No index signature with a parameter of type 'string' was found on type 'Settings'.

כל מחרוזת יכולה להגיע ל-read, כולל "colour", ו-Settings לא אומר כלום על המפתח הזה. יש שני תיקונים: לקבל רק מפתחות אמיתיים, או לבדוק מחרוזת לא מוכרת לפני שמשתמשים בה.

interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

// Fix 1: only accept real keys
function read(name: keyof Settings) {
  return settings[name];
}
console.log(read("fontSize")); // 14

// Fix 2: narrow a string you do not control
function isSettingsKey(name: string): name is keyof Settings {
  return Object.hasOwn(settings, name);
}

for (const input of ["theme", "colour"]) {
  if (isSettingsKey(input)) {
    console.log(input, "=", settings[input]);
  } else {
    console.log(input, "is not a setting");
  }
}
// theme = dark
// colour is not a setting

name is keyof Settings הוא type predicate: כשהפונקציה מחזירה true, TypeScript מתייחס ל-input כמפתח בתוך ה-if. העמוד על type guards מסביר predicates בפירוט.

keyof עם Index Signatures: string | number

עבור טיפוס עם index signature, keyof מחזיר את טיפוס האינדקס, ו-string index signature נותן string | number, לא רק string:

type Scores = { [player: string]: number };

type ScoreKey = keyof Scores; // string | number

const scores: Scores = { ada: 3 };
scores[42] = 7; // allowed: a number key is a valid key

console.log(Object.keys(scores)); // [ '42', 'ada' ]

type OnlyStrings = Extract<keyof Scores, string>; // string
const k: OnlyStrings = "ada";
console.log(k);

JavaScript ממיר כל מפתח מספרי של מאפיין למחרוזת, ולכן scores[42] ו-scores["42"] הם אותו מאפיין. TypeScript מבטא את זה בכך שהוא כולל את number. הפלט מראה גם כלל של JavaScript: מפתחות שנראים כמו מספרים שלמים מופיעים ראשונים, בסדר עולה, לפני שאר מפתחות המחרוזת. כשפונקציה גנרית צריכה רק מפתחות מחרוזת, כתבו Extract<keyof T, string> או string & keyof T; ל-Exclude ו-Extract יש עמוד משלהם.

תוצאות keyof במבט אחד

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

למה Object.keys מחזיר string[]

ל-Object.keys(obj) יש הטיפוס string[], אף פעם לא (keyof T)[]. הסיבה היא structural typing: ערך יכול לשאת יותר מאפיינים מהטיפוס שהוצהר עליו.

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

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // allowed: extra properties are fine here

console.log(Object.keys(p)); // [ 'x', 'y', 'z' ]

// When you know the object has exactly its declared keys, cast:
const origin = { x: 0, y: 0 };
for (const key of Object.keys(origin) as (keyof typeof origin)[]) {
  console.log(key, origin[key]);
}
// x 0
// y 0

הטיפוס של p הוא Point, ובכל זאת יש לו מפתח z בזמן ריצה. אילו Object.keys היה מבטיח ("x" | "y")[], קוד שמסתמך על זה היה שגוי עבור p. ה-cast בטוח עבור object literals שיצרתם בעצמכם; עבור אובייקטים שמגיעים מבחוץ, השאירו את המפתחות כ-string ובדקו אותם.

keyof ב-Mapped Types

keyof הוא גם הדרך לעבור בלולאה על המפתחות של טיפוס כדי לבנות טיפוס חדש. כך כתובים טיפוסי העזר המובנים Partial ו-Readonly:

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

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

type UserDraft = MyPartial<User>; // { id?: number; name?: string }

[K in keyof T] עובר על כל מפתח, ו-T[K] קורא את טיפוס המאפיין במפתח הזה. ל-mapped types יש עמוד משלהם, עם modifiers ו-key remapping.