Record en TypeScript: Record<K, V> explicado con ejemplos

Record<K, V> es un utility type integrado para un objeto cuyas claves son de tipo K y cuyos valores son todos de tipo V. Con claves string describe un diccionario; con una unión de claves literales describe un objeto que tiene que tener exactamente esas claves.

// 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 solo existe en el sistema de tipos. En ejecución los dos objetos son objetos normales de JavaScript, así que funcionan con objetos literales, spread, JSON.stringify y todo lo que reciba un objeto.

Sintaxis y definición

Record<Keys, Value>

Keys tiene que ser algo que pueda ser una clave de objeto: string, number, symbol, una unión de literales string o number, o un template literal type. Value puede ser cualquier tipo. La definición completa en la librería estándar de TypeScript es una línea, un mapped type:

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

keyof any es string | number | symbol, el conjunto de todos los tipos de clave posibles. [P in K]: T crea una propiedad de tipo T por cada miembro de K. Eso explica los dos comportamientos siguientes: un K amplio como string produce una index signature (cualquier clave), y un K en unión produce una propiedad obligatoria por miembro.

Claves en unión: todas son obligatorias

Cuando las claves son una unión de literales, un Record tiene que incluirlas todas, y ninguna más. Así el compilador se convierte en una lista de comprobación:

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)

Si añades "cancelled" a Status, los dos objetos dejan de compilar hasta que le des al nuevo estado una etiqueta y un color. Omitir una clave, o añadir una que no está en la unión, es un error de compilación:

// 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 mismo funciona con un enum de strings como tipo de clave: Record<Color, string> exige una entrada por cada miembro del enum.

Record<string, T> y la clave que falta

Con claves string se permite cualquier clave, y TypeScript tipa cada lectura como T, incluso para una clave que no existe. En ejecución, una clave que falta da 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

Es el error más común con Record. Hay tres formas de tratarlo: comprobar con in o Object.hasOwn antes de leer, declarar el valor como V | undefined, o activar la opción del compilador noUncheckedIndexedAccess, que añade | undefined a toda lectura de index signature del proyecto. Un Record con claves en unión no tiene este problema, porque todas las claves existen seguro.

Partial<Record<K, V>>: solo algunas claves

Para usar una unión de claves sin exigirlas todas, envuelve el Record en Partial. Las lecturas devuelven entonces V | undefined, que es lo honesto:

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 clave mal escrita, como jp, sigue siendo un error, y esa es la ventaja frente a Record<string, string>.

Recorrer un Record

Object.keys, Object.values y Object.entries funcionan. El problema es el tipo de las claves: Object.keys devuelve string[] y Object.entries devuelve [string, V][], nunca tu unión de claves:

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 deja las claves como string a propósito: un objeto puede tener en ejecución más propiedades de las que indica su tipo, así que prometer Plan[] no sería seguro en general. Para un objeto que creaste a partir de un literal, como seats, el cast es seguro.

Construir un Record a partir de datos

Los Records son el resultado habitual de agrupar o indexar un array. Empieza con un objeto vacío del tipo Record y rellénalo:

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"] reutiliza la unión de la interfaz como tipo de clave, así que si añades un género a Book, byGenre exige una entrada nueva.

Record<string, unknown> e interfaces

Record<string, unknown> es un tipo habitual para «algún objeto con claves string». Acepta objetos literales y valores tipados con un alias type, pero rechaza una interfaz:

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

Las interfaces se pueden ampliar mediante declaration merging, así que TypeScript no da por hecho que encajen en una index signature; los type aliases no se pueden reabrir, así que un type User = { name: string } pasaría. Las soluciones habituales son aceptar object en su lugar (puedes seguir llamando a Object.keys sobre él), hacer la función genérica (<T extends object>(obj: T)), o declarar User con type (la página de interface vs type trata las demás diferencias).

Record frente a index signature y Map

Elige Record con claves en unión siempre que conozcas el conjunto de claves: es la única opción que comprueba que están todas. Para claves string abiertas, Record<string, V> y una index signature son intercambiables, y muchos proyectos prefieren Record por legibilidad. Recurre a un Map cuando las claves se añaden y se quitan en ejecución, cuando las claves no son strings, o cuando necesitas el tamaño y el orden de inserción sin trabajo extra.