keyof in TypeScript: ottenere le chiavi di un oggetto come tipo

keyof prende un tipo oggetto e produce l'unione dei nomi delle sue proprietà. Qui sotto keyof User è il tipo "id" | "name" | "email", quindi una variabile di quel tipo può contenere solo una di queste tre stringhe.

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 esiste solo nel sistema dei tipi. Viene cancellato quando il codice viene compilato, quindi non controlla mai niente a runtime. Ciò che ti dà è la garanzia, in fase di compilazione, che una chiave indichi una proprietà reale: rinomina email nell'interfaccia e ogni "email" tipizzato come keyof User diventa un errore.

keyof typeof: le chiavi di un oggetto semplice

keyof funziona sui tipi, non sui valori. Per un oggetto che hai scritto come valore, prima ottieni il suo tipo con typeof, poi prendi le chiavi:

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

Leggilo dall'interno verso l'esterno: typeof colors è { red: string; green: string; blue: string }, e il keyof di quel tipo è l'unione delle chiavi. Scrivere keyof colors senza typeof fallisce con error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

È il modo abituale di ricavare un'unione da una tabella di lookup: aggiungi un colore all'oggetto e il tipo Color cresce con esso. typeof ha anche un secondo significato, a runtime; la pagina su typeof li spiega entrambi.

Accesso tipizzato alle proprietà con i generics

L'uso più comune di keyof è come vincolo generico. K extends keyof T dice "K è una delle chiavi di T", e T[K] è il tipo della proprietà a quella chiave:

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

Il secondo parametro di tipo è importante. Con key: keyof T e senza K, il tipo di ritorno è T[keyof T], l'unione di tutti i tipi delle proprietà (qui string | number | boolean), quindi title.toUpperCase() fallirebbe con error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Catturare la chiave esatta in K mantiene il tipo esatto della proprietà. T[K] è un indexed access type, descritto nella pagina sugli indexed access types.

Indicizzare con una semplice string

Un errore molto comune compare quando indicizzi un oggetto con una string arrivata da altrove:

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

Il compilatore stampa:

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 potrebbe arrivare qualsiasi stringa, compreso "colour", e Settings non dice niente su quella chiave. Due soluzioni: accettare solo chiavi reali, o controllare una stringa sconosciuta prima di usarla.

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 è un type predicate: quando la funzione restituisce true, TypeScript tratta input come una chiave dentro l'if. La pagina sui type guard spiega i predicati nel dettaglio.

keyof con le index signature: string | number

Per un tipo con una index signature, keyof restituisce il tipo dell'indice, e una index signature di tipo stringa dà string | number, non 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 converte ogni chiave numerica di una proprietà in stringa, quindi scores[42] e scores["42"] sono la stessa proprietà. TypeScript lo modella includendo number. L'output mostra anche una regola di JavaScript: le chiavi che sembrano interi vengono elencate per prime, in ordine crescente, prima delle altre chiavi stringa. Quando una funzione generica ha bisogno solo di chiavi stringa, scrivi Extract<keyof T, string> o string & keyof T; Exclude ed Extract hanno una pagina tutta loro.

I risultati di keyof in sintesi

Le righe di unione e intersezione all'inizio sembrano al contrario. Un valore di un tipo unione potrebbe essere l'uno o l'altro membro, quindi sono sicure solo le chiavi presenti in entrambi. Un valore di un'intersezione ha tutto di entrambi, quindi ha tutte le chiavi.

Perché Object.keys restituisce string[]

Object.keys(obj) è tipizzato come string[], mai (keyof T)[]. Il motivo è la tipizzazione strutturale: un valore può portare più proprietà di quelle del suo tipo dichiarato.

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 è tipizzato Point, eppure a runtime ha una chiave z. Se Object.keys promettesse ("x" | "y")[], il codice che ci fa affidamento sarebbe sbagliato per p. Il cast è sicuro per gli oggetti letterali che hai creato tu; per gli oggetti che arrivano dall'esterno, tieni le chiavi come string e controllale.

keyof nei mapped types

keyof è anche il modo per iterare sulle chiavi di un tipo e costruirne uno nuovo. È così che sono scritti gli utility types integrati Partial e 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] visita ogni chiave, e T[K] legge il tipo della proprietà a quella chiave. I mapped types hanno una pagina tutta loro, con modificatori e rimappatura delle chiavi.