TypeScript Indexed Access Types: T[K], T[number] und mehr

Ein Indexed Access Type schlägt den Typ einer Eigenschaft in einem anderen Typ nach, mit derselben Klammersyntax, die JavaScript für den Eigenschaftszugriff verwendet. Person["age"] ist number, und Person["address"]["city"] ist 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

Der Vorteil ist eine einzige Quelle der Wahrheit. Age ist keine zweite Kopie von number: Ändert sich Person["age"] zu string, ändert sich jeder Typ mit, der als Person["age"] geschrieben ist. Indexed Access Types existieren nur beim Kompilieren; sie erzeugen kein JavaScript.

Union-Schlüssel und T[keyof T]

Der Index kann eine Union von Schlüsseln sein. Das Ergebnis ist die Union der Eigenschaftstypen:

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] heißt auf Typebene "irgendein Eigenschaftswert von Product". Einen Schlüssel abzufragen, den es nicht gibt, ist ein Compilerfehler: Product["price"] ergibt error TS2339: Property 'price' does not exist on type 'Product'.

Optionale Eigenschaften enthalten undefined

Mit strictNullChecks (unter strict aktiv) enthält der Typ einer optionalen Eigenschaft undefined, und ihr Indexed Access Type ebenso:

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

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

Um das undefined loszuwerden, umschließe den Typ: NonNullable<Profile["nickname"]> ist string.

Elementtypen von Arrays mit T[number]

Arrays werden mit Zahlen indiziert, also ergibt ein Array-Typ, der mit number indiziert wird, den Elementtyp. Das funktioniert auch über mehrere Ebenen:

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

Das ist nützlich, wenn ein Typ aus einer Quelle kommt, die du nicht kontrollierst, etwa einem generierten API-Client: ApiResponse["data"]["users"][number] benennt den User-Typ, ohne dass ihn jemand exportiert haben muss.

Tupel: Indizieren nach Position

Einen Tupel-Typ kannst du mit einer bestimmten Position indizieren, mit number für die Union aller Elementtypen und mit "length" für seine Länge als Literaltyp:

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]: eine Union aus einem const-Array

Der häufigste Einsatz in der Praxis: Du hältst eine Liste erlaubter Werte als Array (damit du zur Laufzeit darüber iterieren kannst) und leitest daraus den Union-Typ ab (damit der Compiler ihn prüft).

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

Zwei Teile sorgen dafür, dass es funktioniert. as const macht das Array zu einem readonly-Tupel aus Literaltypen; ohne das ist ROLES ein string[] und (typeof ROLES)[number] nur string. Dann macht typeof aus dem Wert einen Typ, und [number] sammelt seine Elemente in einer Union. Die Klammern sind optional (typeof ROLES[number] bedeutet dasselbe), machen aber die Reihenfolge der Operationen deutlich.

Einen String gegen das Array prüfen

Dieses readonly-Tupel hat eine Überraschung parat. Seine Methode includes akzeptiert nur den Elementtyp, also kannst du ihr keinen beliebigen String übergeben:

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

Erweitere das Array für die Prüfung auf readonly string[] und mach aus der Funktion einen Type Guard, damit eine erfolgreiche Prüfung den Wert eingrenzt:

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

Mit diesem Muster hast du eine Liste für beide Aufgaben: Die Laufzeitprüfung nutzt das Array, und der Typ wird daraus abgeleitet, also können beide nicht auseinanderlaufen.

Indexed Access in Generics: T[K]

Innerhalb eines Generics ist T[K] mit K extends keyof T der Typ der Eigenschaft, die der Aufrufer gewählt hat:

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

Erst der Constraint K extends keyof T macht T[K] zulässig. Ohne ihn kann TypeScript nicht wissen, dass K ein Schlüssel von T ist, und meldet error TS2536: Type 'K' cannot be used to index type 'T'.

Syntax im Überblick

Der Index ist immer ein Typ. Person[key], wobei key eine const-Variable ist, scheitert mit zwei Fehlern: error TS2538: Type 'key' cannot be used as an index type. und error TS2749: 'key' refers to a value, but is being used as a type here. Did you mean 'typeof key'?.