keyof en TypeScript: las claves de un objeto como tipo

keyof toma un tipo objeto y produce la unión de los nombres de sus propiedades. Abajo, keyof User es el tipo "id" | "name" | "email", así que una variable de ese tipo solo puede contener uno de esos tres 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

keyof solo existe en el sistema de tipos. Se borra al compilar, así que nunca comprueba nada en tiempo de ejecución. Lo que te da es la garantía en compilación de que una clave nombra una propiedad real: si renombras email en la interfaz, cada "email" tipado como keyof User pasa a ser un error.

keyof typeof: las claves de un objeto normal

keyof trabaja con tipos, no con valores. Para un objeto que escribiste como valor, primero obtén su tipo con typeof y luego toma las claves:

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

Se lee de dentro hacia fuera: typeof colors es { red: string; green: string; blue: string }, y su keyof es la unión de claves. Escribir keyof colors sin typeof falla con error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

Es la forma habitual de sacar una unión de una tabla de consulta: añades un color al objeto y el tipo Color crece con él. typeof tiene además un segundo significado en tiempo de ejecución; la página de typeof explica los dos.

Acceso tipado a propiedades con genéricos

El uso más común de keyof es como restricción genérica. K extends keyof T dice «K es una de las claves de T», y T[K] es el tipo de la propiedad en esa clave:

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

El segundo parámetro de tipo importa. Con key: keyof T y sin K, el tipo de retorno es T[keyof T], la unión de todos los tipos de las propiedades (aquí string | number | boolean), así que title.toUpperCase() fallaría con error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Capturar la clave exacta en K conserva el tipo exacto de la propiedad. T[K] es un indexed access type, que se explica en la página de indexed access types.

Indexar con un string cualquiera

Un error muy frecuente aparece cuando indexas un objeto con un string que viene de otra parte:

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

El compilador muestra:

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

A read podría llegar cualquier string, incluido "colour", y Settings no dice nada de esa clave. Hay dos soluciones: aceptar solo claves reales, o comprobar un string desconocido antes de usarlo.

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 es un type predicate: cuando la función devuelve true, TypeScript trata input como una clave dentro del if. La página de type guards explica los predicados en detalle.

keyof con index signatures: string | number

Para un tipo con index signature, keyof devuelve el tipo del índice, y una index signature de tipo string da string | number, no solo 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 convierte toda clave numérica en string, así que scores[42] y scores["42"] son la misma propiedad. TypeScript lo modela incluyendo number. La salida muestra también una regla de JavaScript: las claves que parecen enteros aparecen primero, en orden ascendente, antes que las demás claves string. Cuando una función genérica necesita solo claves string, escribe Extract<keyof T, string> o string & keyof T; Exclude y Extract tienen su propia página.

Resultados de keyof de un vistazo

Las filas de la unión y la intersección parecen al revés al principio. Un valor de un tipo unión puede ser cualquiera de los miembros, así que solo son seguras las claves presentes en los dos. Un valor de una intersección tiene todo lo de ambos, así que tiene todas las claves.

Por qué Object.keys devuelve string[]

Object.keys(obj) está tipado como string[], nunca como (keyof T)[]. El motivo es el tipado estructural: un valor puede llevar más propiedades que las de su 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 está tipado como Point y, sin embargo, tiene una clave z en tiempo de ejecución. Si Object.keys prometiera ("x" | "y")[], el código que confiara en eso fallaría con p. El cast es seguro para los objetos literales que creaste tú; para los objetos que llegan de fuera, deja las claves como string y compruébalas.

keyof en mapped types

keyof es también la forma de recorrer las claves de un tipo para construir un tipo nuevo. Así están escritos los utility types integrados Partial y 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] recorre cada clave, y T[K] lee el tipo de la propiedad en esa clave. Los mapped types tienen su propia página, con modificadores y remapeo de claves.