keyof em TypeScript: as chaves de um objeto como tipo

O keyof recebe um tipo de objeto e produz a union dos nomes das propriedades dele. keyof User abaixo é o tipo "id" | "name" | "email", então uma variável desse tipo só pode guardar uma dessas três strings.

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

O keyof existe só no sistema de tipos. Ele é apagado quando o código compila, então nunca verifica nada em tempo de execução. O que ele dá é uma garantia em tempo de compilação de que uma chave nomeia uma propriedade real: renomeie email na interface e todo "email" tipado como keyof User vira um erro.

keyof typeof: as chaves de um objeto simples

O keyof funciona com tipos, não com valores. Para um objeto que você escreveu como valor, obtenha primeiro o tipo dele com typeof e depois pegue as chaves:

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

Leia de dentro para fora: typeof colors é { red: string; green: string; blue: string }, e o keyof disso é a union das chaves. Escrever keyof colors sem typeof falha com error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

Esse é o jeito usual de derivar uma union a partir de uma tabela de consulta: adicione uma cor ao objeto e o tipo Color cresce junto. O typeof também tem um segundo significado, de tempo de execução; a página sobre typeof trata dos dois.

Acesso tipado a propriedades com generics

O uso mais comum do keyof é em uma restrição de generic. K extends keyof T diz "K é uma das chaves de T", e T[K] é o tipo da propriedade nessa chave:

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

O segundo type parameter importa. Com key: keyof T e sem K, o tipo de retorno é T[keyof T], a union de todos os tipos de propriedade (string | number | boolean aqui), então title.toUpperCase() falharia com error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Capturar a chave exata em K mantém o tipo exato da propriedade. T[K] é um indexed access type, descrito na página sobre indexed access types.

Indexando com uma string simples

Um erro muito comum aparece quando você indexa um objeto com uma string que veio de outro lugar:

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

O compilador mostra:

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

Qualquer string poderia chegar em read, inclusive "colour", e Settings não diz nada sobre essa chave. Duas soluções: aceitar só chaves reais, ou verificar uma string desconhecida antes de usá-la.

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 é um type predicate: quando a função retorna true, o TypeScript trata input como uma chave dentro do if. A página sobre type guards explica os predicates em detalhe.

keyof com index signatures: string | number

Para um tipo com index signature, o keyof retorna o tipo do índice, e uma index signature de string dá string | number, e não só 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);

O JavaScript converte toda chave numérica de propriedade em string, então scores[42] e scores["42"] são a mesma propriedade. O TypeScript modela isso incluindo number. A saída também mostra uma regra do JavaScript: chaves que parecem inteiros são listadas primeiro, em ordem crescente, antes das outras chaves string. Quando uma função genérica precisa só das chaves string, escreva Extract<keyof T, string> ou string & keyof T; Exclude e Extract têm uma página própria.

Resultados do keyof em resumo

As linhas de union e intersection parecem invertidas à primeira vista. Um valor de um union type pode ser qualquer um dos membros, então só as chaves presentes nos dois são seguras. Um valor de uma intersection tem tudo dos dois, então tem todas as chaves.

Por que Object.keys retorna string[]

Object.keys(obj) é tipado como string[], nunca (keyof T)[]. O motivo é a tipagem estrutural: um valor pode ter mais propriedades do que o tipo declarado.

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 tem o tipo Point, mas tem uma chave z em tempo de execução. Se Object.keys prometesse ("x" | "y")[], código que dependesse disso estaria errado para p. O cast é seguro para objetos literais que você mesmo criou; para objetos que chegam de fora, mantenha as chaves como string e verifique-as.

keyof em mapped types

O keyof também é como você percorre as chaves de um tipo para montar um tipo novo. É assim que os utility types nativos Partial e Readonly são escritos:

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] visita cada chave, e T[K] lê o tipo da propriedade nessa chave. Mapped types têm uma página própria com modificadores e remapeamento de chaves.