Типы доступа по индексу в 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.

Объединения ключей и T[keyof T]

Индекс может быть объединением ключей. Результатом будет объединение типов свойств:

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] называет тип пользователя, хотя никто его не экспортировал.

Кортежи: индекс по позиции

Тип кортежа можно индексировать конкретной позицией, через number для объединения всех типов элементов и через "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]: объединение из const-массива

Самое частое применение на практике: хранить список допустимых значений в массиве (чтобы по нему можно было пройти во время выполнения) и выводить из него тип объединения (чтобы его проверял компилятор).

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 делает массив readonly-кортежем литеральных типов; без этого ROLES имеет тип string[], а (typeof ROLES)[number] это просто string. Затем typeof превращает значение в тип, а [number] собирает его элементы в объединение. Скобки необязательны (typeof ROLES[number] означает то же самое), но делают порядок операций понятным.

Проверка строки по массиву

У этого readonly-кортежа есть один сюрприз. Его метод 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[] и превратите функцию в защитник типа, чтобы успешная проверка сужала значение:

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

Этот приём даёт один список для обеих задач: проверка во время выполнения использует массив, а тип выводится из него, поэтому они не могут разойтись.

Доступ по индексу в дженериках: 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'?.