Record en TypeScript : Record<K, V> expliqué avec exemples

Record<K, V> est un utility type intégré qui décrit un objet dont les clés ont le type K et dont toutes les valeurs ont le type V. Avec des clés string, il décrit un dictionnaire ; avec une union de clés littérales, il décrit un objet qui doit avoir exactement ces clés.

// 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 n'existe que dans le système de types. À l'exécution, les deux objets sont des objets JavaScript ordinaires : ils fonctionnent avec les littéraux objets, le spread, JSON.stringify et tout ce qui accepte un objet.

Syntaxe et définition

Record<Keys, Value>

Keys doit pouvoir servir de clé d'objet : string, number, symbol, une union de littéraux string ou number, ou un template literal type. Value peut être n'importe quel type. Toute la définition dans la bibliothèque standard de TypeScript tient en une ligne, un mapped type :

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

keyof any vaut string | number | symbol, l'ensemble de tous les types de clés possibles. [P in K]: T crée une propriété de type T pour chaque membre de K. Cela explique les deux comportements ci-dessous : un K large comme string produit une signature d'index (n'importe quelle clé), et une union K produit une propriété obligatoire par membre.

Clés union : chaque clé est obligatoire

Quand les clés sont une union de littéraux, un Record doit toutes les lister, et aucune autre. Le compilateur devient alors une checklist :

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)

Ajoutez "cancelled" à Status et les deux objets cessent de compiler tant que vous n'avez pas donné un libellé et une couleur au nouveau statut. Oublier une clé, ou en ajouter une qui n'est pas dans l'union, est une erreur de compilation :

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

Cela fonctionne aussi avec un enum string comme type de clé : Record<Color, string> exige une entrée par membre de l'enum.

Record<string, T> et la clé absente

Avec des clés string, toute clé est autorisée, et TypeScript type chaque accès comme T, même pour une clé qui n'existe pas. À l'exécution, une clé absente donne 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

C'est le bug le plus courant avec Record. Trois façons de le gérer : vérifier avec in ou Object.hasOwn avant de lire, déclarer la valeur comme V | undefined, ou activer l'option de compilation noUncheckedIndexedAccess, qui ajoute | undefined à chaque lecture via une signature d'index dans le projet. Un Record à clés union n'a pas ce problème, car chaque clé est garantie d'exister.

Partial<Record<K, V>> : seulement certaines clés

Pour utiliser une union de clés sans toutes les exiger, enveloppez le Record dans Partial. Les lectures renvoient alors V | undefined, ce qui est honnête :

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

Une clé mal orthographiée comme jp reste une erreur, ce qui est l'avantage par rapport à Record<string, string>.

Parcourir un Record

Object.keys, Object.values et Object.entries fonctionnent tous. Le piège est le type des clés : Object.keys renvoie string[] et Object.entries renvoie [string, V][], jamais votre union de clés :

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 garde volontairement les clés en string : un objet peut avoir plus de propriétés à l'exécution que son type n'en liste, donc promettre Plan[] serait dangereux dans le cas général. Pour un objet que vous avez créé à partir d'un littéral, comme seats, le cast est sûr.

Construire un Record à partir de données

Les Records sont le résultat habituel d'un regroupement ou d'une indexation de tableau. Partez d'un objet vide typé Record et remplissez-le :

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"] réutilise l'union de l'interface comme type de clé, donc ajouter un genre à Book oblige byGenre à avoir une nouvelle entrée.

Record<string, unknown> et les interfaces

Record<string, unknown> est un type courant pour « un objet quelconque avec des clés string ». Il accepte les littéraux objets et les valeurs typées avec un alias type, mais une interface est refusée :

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

Les interfaces peuvent être étendues par fusion de déclarations, donc TypeScript ne suppose pas qu'elles correspondent à une signature d'index ; les alias de type ne peuvent pas être rouverts, si bien qu'un type User = { name: string } passerait. Les solutions habituelles : accepter object à la place (vous pouvez toujours appeler Object.keys dessus), rendre la fonction générique (<T extends object>(obj: T)), ou déclarer User avec type (la page interface vs type couvre les autres différences).

Record vs signature d'index vs Map

Choisissez Record avec des clés union dès que l'ensemble des clés est connu : c'est la seule option qui vérifie que chaque clé est présente. Pour des clés string ouvertes, Record<string, V> et une signature d'index sont interchangeables, et beaucoup de projets préfèrent Record pour la lisibilité. Passez à une Map quand des clés sont ajoutées et retirées à l'exécution, quand les clés ne sont pas des chaînes, ou quand vous avez besoin de la taille et de l'ordre d'insertion sans effort supplémentaire.