أنواع الوصول المفهرس في TypeScript: T[K] وT[number]

نوع الوصول المفهرس يبحث عن نوع خاصية في نوع آخر، بصيغة الأقواس المربعة نفسها التي تستخدمها 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"]. أنواع الوصول المفهرس تعمل وقت الترجمة فقط؛ ولا تولّد أي 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، وكذلك نوع الوصول المفهرس إليها:

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

يعطيك هذا النمط قائمة واحدة للمهمتين: يستخدم الفحص وقت التشغيل المصفوفة، والنوع مشتق منها، فلا يمكن أن يتباعدا.

الوصول المفهرس في الـ Generics: T[K]

داخل generic يكون 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'?.