Record in TypeScript: Record<K, V> spiegato con esempi

Record<K, V> è un utility type integrato per un oggetto le cui chiavi hanno tipo K e i cui valori hanno tutti tipo V. Con chiavi string descrive un dizionario; con un'unione di chiavi letterali descrive un oggetto che deve avere esattamente quelle chiavi.

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record esiste solo nel sistema dei tipi. In fase di esecuzione entrambi gli oggetti sono normali oggetti JavaScript, quindi funzionano con oggetti letterali, spread, JSON.stringify e tutto ciò che accetta un oggetto.

Sintassi e definizione

Record<Keys, Value>

Keys deve essere qualcosa che può fare da chiave di un oggetto: string, number, symbol, un'unione di letterali stringa o numerici, o un template literal type. Value può essere qualsiasi tipo. L'intera definizione nella libreria standard di TypeScript è una riga, un mapped type:

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any è string | number | symbol, l'insieme di tutti i tipi di chiave possibili. [P in K]: T crea una proprietà di tipo T per ogni membro di K. Questo spiega entrambi i comportamenti descritti qui sotto: un K ampio come string produce una index signature (qualsiasi chiave), e un K unione produce una proprietà obbligatoria per ogni membro.

Chiavi in unione: ogni chiave è obbligatoria

Quando le chiavi sono un'unione di letterali, un Record deve elencarle tutte, e nessun'altra. Così il compilatore diventa una lista di controllo:

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

Aggiungi "cancelled" a Status ed entrambi gli oggetti smettono di compilare finché non dai al nuovo stato un'etichetta e un colore. Omettere una chiave, o aggiungerne una che non è nell'unione, è un errore di compilazione:

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

Lo stesso funziona con un enum di stringhe come tipo delle chiavi: Record<Color, string> richiede una voce per ogni membro dell'enum.

Record<string, T> e la chiave mancante

Con chiavi string, qualsiasi chiave è ammessa, e TypeScript tipizza ogni lettura come T, anche per una chiave che non c'è. In fase di esecuzione una chiave mancante dà undefined:

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

È il bug più comune con Record. Ci sono tre modi per gestirlo: controllare con in o Object.hasOwn prima di leggere, dichiarare il valore come V | undefined, oppure attivare l'opzione del compilatore noUncheckedIndexedAccess, che aggiunge | undefined a ogni lettura tramite index signature nel progetto. Un Record con chiavi in unione non ha questo problema, perché ogni chiave esiste di sicuro.

Partial<Record<K, V>>: solo alcune chiavi

Per usare un'unione di chiavi senza richiederle tutte, avvolgi il Record in Partial. Le letture restituiscono allora V | undefined, il che è onesto:

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

Una chiave scritta male come jp resta un errore, ed è questo il vantaggio rispetto a Record<string, string>.

Iterare su un Record

Object.keys, Object.values e Object.entries funzionano tutti. Il problema è il tipo delle chiavi: Object.keys restituisce string[] e Object.entries restituisce [string, V][], mai la tua unione di chiavi:

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

TypeScript tiene le chiavi come string di proposito: in fase di esecuzione un oggetto può avere più proprietà di quelle elencate dal suo tipo, quindi promettere Plan[] non sarebbe sicuro in generale. Per un oggetto che hai creato da un letterale, come seats, il cast è sicuro.

Costruire un Record dai dati

I Record sono il risultato abituale quando raggruppi o indicizzi un array. Parti da un oggetto vuoto con il tipo Record e riempilo:

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

Book["genre"] riutilizza l'unione dell'interfaccia come tipo delle chiavi, quindi aggiungere un genere a Book fa sì che byGenre richieda una nuova voce.

Record<string, unknown> e le interfacce

Record<string, unknown> è un tipo comune per "un oggetto qualsiasi con chiavi stringa". Accetta oggetti letterali e valori tipizzati con un alias type, ma un'interfaccia viene rifiutata:

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

Le interfacce si possono estendere tramite la fusione delle dichiarazioni, quindi TypeScript non presume che siano compatibili con una index signature; gli alias di tipo non si possono riaprire, quindi un type User = { name: string } passerebbe. Le soluzioni abituali sono accettare object al suo posto (puoi comunque chiamare Object.keys su di esso), rendere la funzione generica (<T extends object>(obj: T)), oppure dichiarare User con type (la pagina interface vs type tratta le altre differenze).

Record vs index signature vs Map

Scegli Record con chiavi in unione ogni volta che l'insieme delle chiavi è noto: è l'unica opzione che controlla che ogni chiave sia presente. Per chiavi stringa aperte, Record<string, V> e una index signature sono intercambiabili, e molti codebase preferiscono Record per leggibilità. Ricorri a una Map quando le chiavi vengono aggiunte e rimosse in fase di esecuzione, quando le chiavi non sono stringhe, o quando ti servono la dimensione e l'ordine di inserimento senza lavoro in più.