TypeScript keyof: Objektschlüssel als Typ, mit Beispielen

keyof nimmt einen Objekttyp und erzeugt die Union seiner Eigenschaftsnamen. keyof User ist unten der Typ "id" | "name" | "email", also kann eine Variable dieses Typs nur einen dieser drei Strings enthalten.

interface User {
  id: number;
  name: string;
  email: string;
}

type UserKey = keyof User; // "id" | "name" | "email"

const key: UserKey = "name"; // OK
// @ts-expect-error: "age" is not one of the keys of User
const wrong: UserKey = "age";

function printField(user: User, field: keyof User) {
  console.log(`${field}: ${user[field]}`);
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };
printField(ada, "email"); // email: ada@example.com
printField(ada, key);     // name: Ada

keyof existiert nur im Typsystem. Beim Kompilieren wird es entfernt, es prüft also zur Laufzeit nie etwas. Was es dir gibt, ist eine Garantie beim Kompilieren, dass ein Schlüssel eine echte Eigenschaft benennt: Benenne email im Interface um, und jedes "email", das als keyof User typisiert ist, wird zum Fehler.

keyof typeof: Schlüssel eines einfachen Objekts

keyof arbeitet mit Typen, nicht mit Werten. Für ein Objekt, das du als Wert geschrieben hast, holst du zuerst mit typeof seinen Typ und nimmst dann die Schlüssel:

const colors = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};

type Color = keyof typeof colors; // "red" | "green" | "blue"

function hex(color: Color): string {
  return colors[color];
}

console.log(hex("green")); // #00ff00
// hex("purple") would be error TS2345:
// Argument of type '"purple"' is not assignable to parameter of type '"blue" | "green" | "red"'.

Lies es von innen nach außen: typeof colors ist { red: string; green: string; blue: string }, und keyof davon ist die Union der Schlüssel. keyof colors ohne typeof scheitert mit error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

So leitest du üblicherweise eine Union aus einer Nachschlagetabelle ab: Füge dem Objekt eine Farbe hinzu, und der Typ Color wächst mit. typeof hat auch eine zweite Bedeutung zur Laufzeit; die typeof-Seite behandelt beide.

Typisierter Eigenschaftszugriff mit Generics

Am häufigsten wird keyof als generischer Constraint verwendet. K extends keyof T heißt "K ist einer der Schlüssel von T", und T[K] ist der Typ der Eigenschaft unter diesem Schlüssel:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const book = { title: "Dune", pages: 412, inStock: true };

const pages = getProperty(book, "pages"); // number
const title = getProperty(book, "title"); // string

console.log(pages + 1);           // 413
console.log(title.toUpperCase()); // DUNE
// getProperty(book, "author") would be error TS2345

Der zweite Typparameter ist wichtig. Mit key: keyof T und ohne K ist der Rückgabetyp T[keyof T], die Union aller Eigenschaftstypen (hier string | number | boolean), und title.toUpperCase() würde mit error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean' scheitern. Hältst du den genauen Schlüssel in K fest, bleibt der genaue Eigenschaftstyp erhalten. T[K] ist ein Indexed Access Type, beschrieben auf der Seite zu Indexed Access Types.

Indizieren mit einem einfachen string

Ein sehr häufiger Fehler tritt auf, wenn du ein Objekt mit einem string indizierst, der von woanders kommt:

// This does not compile: a plain string is not a key of Settings
interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

function read(name: string) {
  return settings[name];
}

console.log(read("theme"));

Der Compiler gibt aus:

index.ts(10,10): error TS7053: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Settings'.
  No index signature with a parameter of type 'string' was found on type 'Settings'.

Jeder beliebige String könnte bei read ankommen, auch "colour", und Settings sagt über diesen Schlüssel nichts. Zwei Lösungen: nur echte Schlüssel akzeptieren, oder einen unbekannten String prüfen, bevor du ihn verwendest.

interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

// Fix 1: only accept real keys
function read(name: keyof Settings) {
  return settings[name];
}
console.log(read("fontSize")); // 14

// Fix 2: narrow a string you do not control
function isSettingsKey(name: string): name is keyof Settings {
  return Object.hasOwn(settings, name);
}

for (const input of ["theme", "colour"]) {
  if (isSettingsKey(input)) {
    console.log(input, "=", settings[input]);
  } else {
    console.log(input, "is not a setting");
  }
}
// theme = dark
// colour is not a setting

name is keyof Settings ist ein Type Predicate: Wenn die Funktion true zurückgibt, behandelt TypeScript input innerhalb des if als Schlüssel. Die Seite zu Type Guards erklärt Predicates im Detail.

keyof mit Index-Signaturen: string | number

Bei einem Typ mit Index-Signatur gibt keyof den Indextyp zurück, und eine String-Index-Signatur ergibt string | number, nicht nur string:

type Scores = { [player: string]: number };

type ScoreKey = keyof Scores; // string | number

const scores: Scores = { ada: 3 };
scores[42] = 7; // allowed: a number key is a valid key

console.log(Object.keys(scores)); // [ '42', 'ada' ]

type OnlyStrings = Extract<keyof Scores, string>; // string
const k: OnlyStrings = "ada";
console.log(k);

JavaScript wandelt jeden numerischen Eigenschaftsschlüssel in einen String um, also sind scores[42] und scores["42"] dieselbe Eigenschaft. TypeScript bildet das ab, indem es number einschließt. Die Ausgabe zeigt außerdem eine Regel von JavaScript: Ganzzahlartige Schlüssel werden zuerst aufgelistet, aufsteigend sortiert, vor den übrigen String-Schlüsseln. Wenn eine generische Funktion nur String-Schlüssel braucht, schreibe Extract<keyof T, string> oder string & keyof T; Exclude und Extract haben eine eigene Seite.

Ergebnisse von keyof im Überblick

Die Zeilen zu Union und Intersection wirken zuerst verkehrt herum. Ein Wert eines Union-Typs könnte jedes der Mitglieder sein, also sind nur Schlüssel sicher, die in beiden vorkommen. Ein Wert einer Intersection hat alles von beiden, also hat er alle Schlüssel.

Warum Object.keys string[] zurückgibt

Object.keys(obj) ist als string[] typisiert, nie als (keyof T)[]. Der Grund ist die strukturelle Typisierung: Ein Wert kann mehr Eigenschaften tragen als sein deklarierter Typ.

interface Point {
  x: number;
  y: number;
}

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // allowed: extra properties are fine here

console.log(Object.keys(p)); // [ 'x', 'y', 'z' ]

// When you know the object has exactly its declared keys, cast:
const origin = { x: 0, y: 0 };
for (const key of Object.keys(origin) as (keyof typeof origin)[]) {
  console.log(key, origin[key]);
}
// x 0
// y 0

p ist als Point typisiert, hat aber zur Laufzeit einen Schlüssel z. Würde Object.keys ein ("x" | "y")[] versprechen, wäre Code, der sich darauf verlässt, für p falsch. Der Cast ist sicher für Objektliterale, die du selbst erzeugt hast; bei Objekten, die von außen kommen, behältst du die Schlüssel als string und prüfst sie.

keyof in Mapped Types

Mit keyof durchläufst du auch die Schlüssel eines Typs, um einen neuen Typ zu bauen. So sind die eingebauten Utility Types Partial und Readonly geschrieben:

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

interface User {
  id: number;
  name: string;
}

type UserDraft = MyPartial<User>; // { id?: number; name?: string }

[K in keyof T] besucht jeden Schlüssel, und T[K] liest den Eigenschaftstyp unter diesem Schlüssel. Mapped Types haben eine eigene Seite mit Modifikatoren und Key Remapping.