keyof w TypeScript: klucze obiektu jako typ, z przykładami

keyof bierze typ obiektowy i tworzy unię nazw jego właściwości. Poniżej keyof User to typ "id" | "name" | "email", więc zmienna tego typu może przechowywać tylko jeden z tych trzech stringów.

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 istnieje tylko w systemie typów. Jest usuwany podczas kompilacji, więc nigdy niczego nie sprawdza w czasie działania. Daje za to gwarancję w czasie kompilacji, że klucz nazywa prawdziwą właściwość: zmień nazwę email w interfejsie, a każde "email" otypowane jako keyof User stanie się błędem.

keyof typeof: klucze zwykłego obiektu

keyof działa na typach, a nie na wartościach. Dla obiektu zapisanego jako wartość najpierw pobierz jego typ przez typeof, a potem weź klucze:

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

Czytaj to od środka: typeof colors to { red: string; green: string; blue: string }, a keyof z tego to unia kluczy. Zapis keyof colors bez typeof kończy się błędem error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

To typowy sposób na wyprowadzenie unii z tablicy wyszukiwania: dodajesz kolor do obiektu, a typ Color rośnie razem z nim. typeof ma też drugie znaczenie, w czasie działania; strona o typeof opisuje oba.

Typowany dostęp do właściwości z generykami

Najczęściej keyof występuje jako ograniczenie generyczne. K extends keyof T mówi „K jest jednym z kluczy T”, a T[K] to typ właściwości pod tym kluczem:

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

Drugi parametr typu ma znaczenie. Przy key: keyof T bez K typ zwracany to T[keyof T], czyli unia typów wszystkich właściwości (tutaj string | number | boolean), więc title.toUpperCase() kończyłoby się błędem error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Przechwycenie dokładnego klucza w K zachowuje dokładny typ właściwości. T[K] to indexed access type, opisany na stronie o indexed access types.

Indeksowanie zwykłym stringiem

Bardzo częsty błąd pojawia się przy indeksowaniu obiektu stringiem, który przyszedł skądinąd:

// 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"));

Kompilator wypisuje:

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

Do read może trafić dowolny string, także "colour", a Settings nic o takim kluczu nie mówi. Są dwa rozwiązania: przyjmować tylko prawdziwe klucze albo sprawdzać nieznany string przed użyciem.

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 to predykat typu: gdy funkcja zwraca true, TypeScript traktuje input wewnątrz if jako klucz. Predykaty szczegółowo wyjaśnia strona o type guards.

keyof z sygnaturami indeksu: string | number

Dla typu z sygnaturą indeksu keyof zwraca typ indeksu, a sygnatura indeksu typu string daje string | number, a nie samo 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 zamienia każdy liczbowy klucz właściwości na string, więc scores[42] i scores["42"] to ta sama właściwość. TypeScript odwzorowuje to, dodając number. Wynik pokazuje też regułę JavaScriptu: klucze wyglądające jak liczby całkowite są wypisywane jako pierwsze, rosnąco, przed pozostałymi kluczami typu string. Gdy funkcja generyczna potrzebuje tylko kluczy typu string, napisz Extract<keyof T, string> albo string & keyof T; Exclude i Extract mają własną stronę.

Wyniki keyof w skrócie

Wiersze z unią i przecięciem na początku wyglądają na odwrócone. Wartość typu unii może być dowolnym z elementów, więc bezpieczne są tylko klucze obecne w obu. Wartość przecięcia ma wszystko z obu stron, więc ma wszystkie klucze.

Dlaczego Object.keys zwraca string[]

Object.keys(obj) ma typ string[], nigdy (keyof T)[]. Powodem jest typowanie strukturalne: wartość może mieć więcej właściwości niż jej zadeklarowany 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 ma typ Point, a mimo to w czasie działania ma klucz z. Gdyby Object.keys obiecywało ("x" | "y")[], kod na tym polegający byłby dla p błędny. Rzutowanie jest bezpieczne dla literałów obiektowych tworzonych samodzielnie; dla obiektów przychodzących z zewnątrz zostaw klucze jako string i je sprawdzaj.

keyof w mapped types

keyof pozwala też przejść po kluczach typu, żeby zbudować nowy typ. Tak są napisane wbudowane utility types Partial i Readonly:

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] odwiedza każdy klucz, a T[K] odczytuje typ właściwości pod tym kluczem. Mapped types mają własną stronę, z modyfikatorami i przemapowywaniem kluczy.