Indexed access types w TypeScript: T[K], T[number] i więcej

Indexed access type odczytuje typ właściwości z innego typu, tą samą składnią nawiasów kwadratowych, której JavaScript używa do dostępu do właściwości. Person["age"] to number, a Person["address"]["city"] to 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

Zaletą jest jedno źródło prawdy. Age nie jest drugą kopią number: jeśli Person["age"] zmieni się na string, każdy typ zapisany jako Person["age"] zmieni się razem z nim. Indexed access types istnieją tylko w czasie kompilacji; nie generują żadnego JavaScriptu.

Klucze w unii i T[keyof T]

Indeks może być unią kluczy. Wynikiem jest unia typów właściwości:

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] to sposób, by na poziomie typów powiedzieć „dowolna wartość właściwości Product”. Pytanie o nieistniejący klucz to błąd kompilacji: Product["price"] daje error TS2339: Property 'price' does not exist on type 'Product'.

Właściwości opcjonalne zawierają undefined

Przy strictNullChecks (włączonym w strict) typ właściwości opcjonalnej zawiera undefined, podobnie jak jej indexed access type:

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

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

Aby pozbyć się undefined, opakuj go: NonNullable<Profile["nickname"]> to string.

Typy elementów tablicy przez T[number]

Tablice są indeksowane liczbami, więc zaindeksowanie typu tablicy przez number daje typ elementu. Działa to też przez kilka poziomów:

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

Przydaje się to, gdy typ pochodzi z miejsca, nad którym nie masz kontroli, na przykład z wygenerowanego klienta API: ApiResponse["data"]["users"][number] nazywa typ użytkownika, choć nikt go nie wyeksportował.

Krotki: indeks według pozycji

Typ krotki można zaindeksować konkretną pozycją, przez number dla unii typów wszystkich elementów i przez "length" dla jej długości jako typu literalnego:

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]: unia z tablicy const

Najczęstsze praktyczne zastosowanie: trzymaj listę dozwolonych wartości jako tablicę (aby móc po niej iterować w czasie wykonania) i wyprowadź z niej typ unii (aby kompilator go sprawdzał).

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

Działa to dzięki dwóm elementom. as const zamienia tablicę w krotkę tylko do odczytu z typami literalnymi; bez tego ROLES to string[], a (typeof ROLES)[number] to po prostu string. Następnie typeof zamienia wartość w typ, a [number] zbiera jego elementy w unię. Nawiasy są opcjonalne (typeof ROLES[number] znaczy to samo), ale wyjaśniają kolejność operacji.

Sprawdzanie napisu względem tablicy

Ta krotka tylko do odczytu ma jedną niespodziankę. Jej metoda includes przyjmuje tylko typ elementu, więc nie da się przekazać do niej dowolnego napisu:

// 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"'.

Na czas sprawdzenia poszerz tablicę do readonly string[] i zamień funkcję w strażnika typu, aby udane sprawdzenie zawężało wartość:

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

Ten wzorzec daje jedną listę do obu zadań: sprawdzenie w czasie wykonania używa tablicy, a typ jest z niej wyprowadzony, więc nie mogą się rozjechać.

Dostęp indeksowany w generykach: T[K]

Wewnątrz generyka T[K] z K extends keyof T to typ właściwości, którą wybrał wywołujący:

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[]

To ograniczenie K extends keyof T sprawia, że T[K] jest poprawne. Bez niego TypeScript nie może wiedzieć, że K jest kluczem T, i zgłasza error TS2536: Type 'K' cannot be used to index type 'T'.

Składnia w skrócie

Indeks jest zawsze typem. Person[key], gdzie key jest zmienną const, kończy się dwoma błędami: error TS2538: Type 'key' cannot be used as an index type. oraz error TS2749: 'key' refers to a value, but is being used as a type here. Did you mean 'typeof key'?.