TypeScript Indexed Access Types: T[K], T[number] ועוד

indexed access type מחפש את הטיפוס של מאפיין בטיפוס אחר, עם אותו תחביר סוגריים מרובעים ש-JavaScript משתמש בו לגישה למאפיינים. Person["age"] הוא number, ו-Person["address"]["city"] הוא string.

type Person = {
  name: string;
  age: number;
  address: { city: string; zip: string };
};

type Age = Person["age"];                 // number
type City = Person["address"]["city"];    // string
type Address = Person["address"];         // { city: string; zip: string }

const age: Age = 36;
const home: Address = { city: "London", zip: "N1" };
const city: City = home.city;

console.log(age, city); // 36 London

היתרון הוא מקור אמת יחיד. Age אינו עותק שני של number: אם Person["age"] משתנה ל-string, כל טיפוס שנכתב כ-Person["age"] משתנה יחד איתו. indexed access types קיימים רק בזמן הקומפילציה; הם לא מייצרים JavaScript.

מפתחות מסוג union ו-T[keyof T]

האינדקס יכול להיות union של מפתחות. התוצאה היא ה-union של טיפוסי המאפיינים:

type Product = {
  id: number;
  title: string;
  inStock: boolean;
};

type IdOrTitle = Product["id" | "title"];  // number | string
type AnyValue = Product[keyof Product];    // number | string | boolean

function describe(value: AnyValue): string {
  return `${typeof value}: ${value}`;
}

const p: Product = { id: 7, title: "Lamp", inStock: false };
for (const key of ["id", "title", "inStock"] as const) {
  console.log(describe(p[key]));
}
// number: 7
// string: Lamp
// boolean: false

Product[keyof Product] היא הדרך לומר ברמת הטיפוסים "כל ערך של מאפיין ב-Product". בקשה של מפתח שלא קיים היא שגיאת קומפילציה: Product["price"] נותן error TS2339: Property 'price' does not exist on type 'Product'.

מאפיינים אופציונליים כוללים undefined

עם strictNullChecks (פועל תחת strict), הטיפוס של מאפיין אופציונלי כולל undefined, וכך גם ה-indexed access type שלו:

type Profile = { name: string; nickname?: string };

type Nick = Profile["nickname"]; // string | undefined

כדי להסיר את ה-undefined, עטפו אותו: NonNullable<Profile["nickname"]> הוא string.

טיפוסי איברי מערך עם T[number]

מערכים ממופתחים לפי מספרים, ולכן אינדקס לטיפוס מערך עם number נותן את טיפוס האיבר. זה עובד גם דרך כמה רמות:

type Order = {
  id: number;
  items: { sku: string; qty: number }[];
};

type Orders = Order[];

type OneOrder = Orders[number];             // Order
type Item = Order["items"][number];         // { sku: string; qty: number }
type Sku = Orders[number]["items"][number]["sku"]; // string

const item: Item = { sku: "A-100", qty: 2 };
const sku: Sku = item.sku;
console.log(sku, item.qty); // A-100 2

זה שימושי כשטיפוס מגיע ממקום שאין לכם שליטה עליו, כמו לקוח API שנוצר אוטומטית: ApiResponse["data"]["users"][number] נותן שם לטיפוס המשתמש בלי שמישהו ייצא אותו.

Tuples: אינדקס לפי מיקום

אפשר לעשות אינדקס לטיפוס tuple עם מיקום מסוים, עם number בשביל ה-union של כל טיפוסי האיברים, ועם "length" בשביל האורך שלו כטיפוס ליטרל:

type Entry = [string, number, boolean];

type First = Entry[0];         // string
type Second = Entry[1];        // number
type AnyElement = Entry[number]; // string | number | boolean
type Len = Entry["length"];    // 3

const len: Len = 3;
const entry: Entry = ["ada", 36, true];
const first: First = entry[0];

console.log(first, len); // ada 3
// Entry[3] is error TS2493: Tuple type 'Entry' of length '3' has no element at index '3'.

(typeof arr)[number]: union ממערך const

השימוש הנפוץ ביותר בעולם האמיתי: לשמור רשימה של ערכים מותרים כמערך (כדי שאפשר יהיה לעבור עליה בלולאה בזמן ריצה) ולגזור ממנה את טיפוס ה-union (כדי שהקומפיילר יבדוק אותה).

const ROLES = ["admin", "editor", "viewer"] as const;

type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canPublish(role: Role): boolean {
  return role !== "viewer";
}

for (const role of ROLES) {
  console.log(role, canPublish(role));
}
// admin true
// editor true
// viewer false

שני חלקים גורמים לזה לעבוד. as const הופך את המערך ל-tuple לקריאה בלבד של טיפוסי ליטרל; בלעדיו, ROLES הוא string[] ו-(typeof ROLES)[number] הוא סתם string. אחר כך typeof הופך את הערך לטיפוס, ו-[number] אוסף את האיברים שלו ל-union. הסוגריים אופציונליים (typeof ROLES[number] אומר אותו דבר), אבל הם מבהירים את סדר הפעולות.

בדיקה של מחרוזת מול המערך

ל-tuple לקריאה בלבד הזה יש הפתעה אחת. המתודה includes שלו מקבלת רק את טיפוס האיבר, ולכן אי אפשר להעביר לה מחרוזת שרירותית:

// This does not compile: includes() on the tuple only accepts a Role
const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number];

function isRole(value: string): boolean {
  return ROLES.includes(value);
}

console.log(isRole("admin"));

index.ts(6,25): error TS2345: Argument of type 'string' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

הרחיבו את המערך ל-readonly string[] לצורך הבדיקה, והפכו את הפונקציה ל-type guard כדי שבדיקה מוצלחת תצמצם את הערך:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number];

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

const input: string = "editor"; // imagine this came from a URL or a form
if (isRole(input)) {
  const role: Role = input; // narrowed to Role here
  console.log("valid role:", role);
}
console.log(isRole("owner")); // false

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

Indexed access בגנריקס: T[K]

בתוך גנרי, T[K] עם K extends keyof T הוא הטיפוס של המאפיין שמי שקורא לפונקציה בחר:

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const users = [
  { name: "Ada", age: 36 },
  { name: "Linus", age: 28 },
];

const names = pluck(users, "name"); // string[]
const ages = pluck(users, "age");   // number[]

האילוץ K extends keyof T הוא מה שהופך את T[K] לחוקי. בלעדיו, TypeScript לא יכול לדעת ש-K הוא מפתח של T ומדווח error TS2536: Type 'K' cannot be used to index type 'T'.

התחביר במבט אחד

האינדקס הוא תמיד טיפוס. Person[key], כש-key הוא משתנה const, נכשל עם שתי שגיאות: error TS2538: Type 'key' cannot be used as an index type. ו-error TS2749: 'key' refers to a value, but is being used as a type here. Did you mean 'typeof key'?.