TypeScript Record: Record<K, V> erklärt mit Beispielen

Record<K, V> ist ein eingebauter Utility Type für ein Objekt, dessen Schlüssel den Typ K und dessen Werte alle den Typ V haben. Mit string-Schlüsseln beschreibt er ein Wörterbuch; mit einer Union aus Literal-Schlüsseln beschreibt er ein Objekt, das genau diese Schlüssel haben muss.

// 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 existiert nur im Typsystem. Zur Laufzeit sind beide Objekte einfache JavaScript-Objekte, sie funktionieren also mit Objektliteralen, Spread, JSON.stringify und allem anderen, was ein Objekt nimmt.

Syntax und Definition

Record<Keys, Value>

Keys muss etwas sein, das ein Objektschlüssel sein kann: string, number, symbol, eine Union aus String- oder Zahl-Literalen oder ein Template Literal Type. Value kann jeder Typ sein. Die gesamte Definition in der Standardbibliothek von TypeScript ist eine Zeile, ein Mapped Type:

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

keyof any ist string | number | symbol, die Menge aller möglichen Schlüsseltypen. [P in K]: T erzeugt für jedes Mitglied von K eine Eigenschaft vom Typ T. Das erklärt beide Verhaltensweisen unten: Ein breites K wie string ergibt eine Index-Signatur (jeder Schlüssel), und ein Union-K ergibt pro Mitglied eine verpflichtende Eigenschaft.

Union-Schlüssel: Jeder Schlüssel ist verpflichtend

Sind die Schlüssel eine Union aus Literalen, muss ein Record jeden davon auflisten und keinen anderen. Damit wird der Compiler zur Checkliste:

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)

Füge Status den Wert "cancelled" hinzu, und beide Objekte kompilieren nicht mehr, bis du dem neuen Status ein Label und eine Farbe gibst. Einen Schlüssel wegzulassen oder einen hinzuzufügen, der nicht in der Union steht, ist ein Compilerfehler:

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

Dasselbe funktioniert mit einem String-Enum als Schlüsseltyp: Record<Color, string> verlangt einen Eintrag pro Enum-Member.

Record<string, T> und der fehlende Schlüssel

Mit string-Schlüsseln ist jeder Schlüssel erlaubt, und TypeScript typisiert jeden Zugriff als T, auch für einen Schlüssel, den es nicht gibt. Zur Laufzeit ergibt ein fehlender Schlüssel 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

Das ist der häufigste Fehler mit Record. Drei Wege, damit umzugehen: vor dem Lesen mit in oder Object.hasOwn prüfen, den Wert als V | undefined deklarieren oder die Compiler-Option noUncheckedIndexedAccess einschalten, die im ganzen Projekt jedem Lesezugriff über eine Index-Signatur ein | undefined hinzufügt. Ein Record mit Union-Schlüsseln hat dieses Problem nicht, weil jeder Schlüssel garantiert existiert.

Partial<Record<K, V>>: nur einige Schlüssel

Um eine Union von Schlüsseln zu verwenden, ohne alle zu verlangen, umschließe den Record mit Partial. Lesezugriffe geben dann V | undefined zurück, und das ist ehrlich:

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

Ein falsch geschriebener Schlüssel wie jp ist trotzdem ein Fehler, und das ist der Vorteil gegenüber Record<string, string>.

Über einen Record iterieren

Object.keys, Object.values und Object.entries funktionieren alle. Der Haken ist der Schlüsseltyp: Object.keys gibt string[] zurück und Object.entries gibt [string, V][] zurück, nie deine Union von Schlüsseln:

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 belässt die Schlüssel absichtlich bei string: Ein Objekt kann zur Laufzeit mehr Eigenschaften haben, als sein Typ auflistet, also wäre das Versprechen Plan[] im Allgemeinen unsicher. Für ein Objekt, das du aus einem Literal erzeugt hast, wie seats, ist der Cast sicher.

Einen Record aus Daten bauen

Records sind das übliche Ergebnis, wenn du ein Array gruppierst oder indizierst. Beginne mit einem leeren Objekt vom Record-Typ und fülle es:

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"] verwendet die Union aus dem Interface als Schlüsseltyp wieder, also verlangt byGenre einen neuen Eintrag, sobald du Book ein Genre hinzufügst.

Record<string, unknown> und Interfaces

Record<string, unknown> ist ein gängiger Typ für "irgendein Objekt mit String-Schlüsseln". Er akzeptiert Objektliterale und Werte, die mit einem type-Alias typisiert sind, aber ein Interface wird abgelehnt:

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

Interfaces lassen sich per Declaration Merging erweitern, also nimmt TypeScript nicht an, dass sie zu einer Index-Signatur passen; Type Aliases lassen sich nicht wieder öffnen, also würde ein type User = { name: string } durchgehen. Die üblichen Lösungen: stattdessen object akzeptieren (du kannst trotzdem Object.keys darauf aufrufen), die Funktion generisch machen (<T extends object>(obj: T)) oder User mit type deklarieren (die Seite interface vs type behandelt die übrigen Unterschiede).

Record vs Index-Signatur vs Map

Nimm Record mit Union-Schlüsseln, wann immer die Menge der Schlüssel bekannt ist: Nur so wird geprüft, dass jeder Schlüssel vorhanden ist. Für offene String-Schlüssel sind Record<string, V> und eine Index-Signatur austauschbar, und viele Codebasen bevorzugen Record wegen der Lesbarkeit. Greif zu einer Map, wenn Schlüssel zur Laufzeit hinzukommen und wegfallen, wenn Schlüssel keine Strings sind oder wenn du Größe und Einfügereihenfolge ohne Zusatzaufwand brauchst.