keyof в TypeScript: ключи объекта как тип, с примерами

keyof принимает объектный тип и даёт объединение имён его свойств. keyof User ниже это тип "id" | "name" | "email", поэтому переменная этого типа может хранить только одну из этих трёх строк.

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 существует только в системе типов. Он стирается при компиляции кода, поэтому ничего не проверяет во время выполнения. Зато он даёт гарантию времени компиляции, что ключ называет настоящее свойство: переименуйте email в интерфейсе, и каждая строка "email" с типом keyof User станет ошибкой.

keyof typeof: ключи обычного объекта

keyof работает с типами, а не со значениями. Для объекта, записанного как значение, сначала получите его тип через typeof, а затем возьмите ключи:

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

Читайте изнутри наружу: typeof colors это { red: string; green: string; blue: string }, а keyof от него это объединение ключей. Запись keyof colors без typeof завершается ошибкой error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

Это обычный способ получить объединение из таблицы соответствий: добавьте цвет в объект, и тип Color вырастет вместе с ним. У typeof есть и второе значение, времени выполнения; страница о typeof описывает оба.

Типизированный доступ к свойствам через дженерики

Чаще всего keyof используют в ограничении дженерика. K extends keyof T говорит «K это один из ключей T», а T[K] это тип свойства по этому ключу:

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

Второй параметр типа важен. С key: keyof T и без K типом возврата будет T[keyof T], объединение всех типов свойств (здесь string | number | boolean), поэтому title.toUpperCase() завершился бы ошибкой error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Сохранение точного ключа в K сохраняет точный тип свойства. T[K] это тип доступа по индексу, описанный на странице о типах доступа по индексу.

Индексация обычным string

Очень распространённая ошибка появляется, когда объект индексируют строкой string, пришедшей откуда-то ещё:

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

Компилятор выводит:

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

В read может попасть любая строка, включая "colour", а Settings ничего не говорит о таком ключе. Есть два исправления: принимать только настоящие ключи или проверять неизвестную строку перед использованием.

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 это предикат типа: когда функция возвращает true, TypeScript считает input ключом внутри if. Предикаты подробно объясняет страница о защитниках типов.

keyof с сигнатурами индекса: string | number

Для типа с сигнатурой индекса keyof возвращает тип индекса, а строковая сигнатура индекса даёт string | number, а не только 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 преобразует каждый числовой ключ свойства в строку, поэтому scores[42] и scores["42"] это одно и то же свойство. TypeScript моделирует это, включая number. Вывод показывает ещё одно правило JavaScript: целочисленные ключи перечисляются первыми, по возрастанию, раньше остальных строковых ключей. Когда обобщённой функции нужны только строковые ключи, пишите Extract<keyof T, string> или string & keyof T; у Exclude и Extract есть отдельная страница.

Результаты keyof коротко

Строки про объединение и пересечение поначалу кажутся перевёрнутыми. Значение типа объединения может оказаться любым членом, поэтому безопасны только ключи, которые есть в обоих. У значения типа пересечения есть всё от обоих, поэтому у него все ключи.

Почему Object.keys возвращает string[]

Object.keys(obj) типизирован как string[], а не (keyof T)[]. Причина в структурной типизации: у значения может быть больше свойств, чем в его объявленном типе.

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 имеет тип Point, но во время выполнения у него есть ключ z. Если бы Object.keys обещал ("x" | "y")[], код, полагающийся на это, был бы неверен для p. Приведение безопасно для объектных литералов, которые вы создали сами; для объектов, приходящих извне, оставляйте ключи как string и проверяйте их.

keyof в сопоставленных типах

keyof это ещё и способ пройти по ключам типа, чтобы построить новый тип. Так написаны встроенные служебные типы Partial и 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] посещает каждый ключ, а T[K] читает тип свойства по этому ключу. У сопоставленных типов есть отдельная страница с модификаторами и переназначением ключей.