TypeScript Record Tipi: Örneklerle Record<K, V>

Record<K, V>, anahtarları K tipinde ve değerlerinin hepsi V tipinde olan bir nesne için yerleşik bir utility type'tır. string anahtarlarla bir sözlüğü tanımlar; literal anahtarlardan oluşan bir union ile tam olarak bu anahtarlara sahip olması gereken bir nesneyi tanımlar.

// 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 yalnızca tip sisteminde vardır. Çalışma zamanında iki nesne de düz JavaScript nesneleridir; bu yüzden nesne literal'leri, spread, JSON.stringify ve nesne alan diğer her şeyle çalışırlar.

Sözdizimi ve Tanım

Record<Keys, Value>

Keys bir nesne anahtarı olabilecek bir şey olmalıdır: string, number, symbol, string ya da number literal'lerinden oluşan bir union veya bir template literal tipi. Value herhangi bir tip olabilir. TypeScript'in standart kütüphanesindeki tanımın tamamı tek satırlık bir mapped type'tır:

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

keyof any, olası tüm anahtar tiplerinin kümesi olan string | number | symbol tipidir. [P in K]: T, K tipinin her üyesi için T tipinde bir özellik oluşturur. Bu, aşağıdaki iki davranışı da açıklar: string gibi geniş bir K bir index signature üretir (herhangi bir anahtar), bir union K ise her üye için bir zorunlu özellik üretir.

Union Anahtarlar: Her Anahtar Zorunludur

Anahtarlar literal'lerden oluşan bir union olduğunda, bir Record her birini listelemelidir ve başka hiçbirini değil. Bu, derleyiciyi bir kontrol listesine dönüştürür:

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)

Status tipine "cancelled" ekleyin; yeni duruma bir etiket ve bir renk verene kadar iki nesne de derlenmez. Bir anahtarı atlamak ya da union'da olmayan bir anahtar eklemek derleme hatasıdır:

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

Aynısı anahtar tipi olarak bir string enum ile de çalışır: Record<Color, string> her enum üyesi için bir girdi ister.

Record<string, T> ve Eksik Anahtar

string anahtarlarla her anahtara izin verilir ve TypeScript her okumayı, orada olmayan bir anahtar için bile, T olarak tipler. Çalışma zamanında eksik bir anahtar undefined verir:

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

Bu en yaygın Record hatasıdır. Bunu ele almanın üç yolu var: okumadan önce in ya da Object.hasOwn ile kontrol edin, değeri V | undefined olarak bildirin ya da projedeki her index signature okumasına | undefined ekleyen noUncheckedIndexedAccess derleyici seçeneğini açın. Union anahtarlı bir Record'da bu sorun yoktur, çünkü her anahtarın var olması garantidir.

Partial<Record<K, V>>: Yalnızca Bazı Anahtarlar

Anahtarlar için bir union kullanıp hepsini zorunlu kılmamak için Record'u Partial ile sarın. Okumalar o zaman V | undefined döndürür, bu da dürüst bir tiptir:

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

jp gibi yanlış yazılmış bir anahtar yine hatadır; Record<string, string> tipine göre avantajı budur.

Bir Record Üzerinde Döngü

Object.keys, Object.values ve Object.entries hepsi çalışır. Sorun anahtar tipindedir: Object.keys string[], Object.entries de [string, V][] döndürür; asla sizin anahtar union'ınızı döndürmez:

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 anahtarları bilerek string olarak tutar: bir nesnenin çalışma zamanında tipinin listelediğinden daha fazla özelliği olabilir, dolayısıyla genel olarak Plan[] sözü vermek güvensiz olurdu. seats gibi bir literal'den oluşturduğunuz bir nesne için cast güvenlidir.

Veriden Bir Record Oluşturmak

Record'lar bir diziyi gruplamanın ya da indekslemenin olağan sonucudur. Record tipinde boş bir nesneyle başlayın ve onu doldurun:

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"], interface'teki union'ı anahtar tipi olarak yeniden kullanır; böylece Book tipine bir tür eklemek, byGenre nesnesinin yeni bir girdi istemesine yol açar.

Record<string, unknown> ve Interface'ler

Record<string, unknown>, "string anahtarlı bir nesne" için yaygın bir tiptir. Nesne literal'lerini ve bir type alias ile tiplenmiş değerleri kabul eder, ancak bir interface reddedilir:

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

Interface'ler declaration merging ile genişletilebilir, bu yüzden TypeScript onların bir index signature'a uyduğunu varsaymaz; type alias'lar yeniden açılamaz, dolayısıyla bir type User = { name: string } geçerdi. Olağan çözümler şunlardır: bunun yerine object kabul edin (üzerinde yine Object.keys çağırabilirsiniz), fonksiyonu generic yapın (<T extends object>(obj: T)) ya da User tipini type ile bildirin (diğer farkları interface ve type sayfası ele alır).

Record, Index Signature ve Map

Anahtar kümesi bilindiğinde union anahtarlı Record seçin: her anahtarın var olduğunu kontrol eden tek seçenek budur. Serbest string anahtarlar için Record<string, V> ve bir index signature birbirinin yerine kullanılabilir; birçok kod tabanı okunabilirlik için Record tercih eder. Anahtarlar çalışma zamanında eklenip siliniyorsa, anahtarlar string değilse ya da boyuta ve ekleme sırasına ek iş yapmadan ihtiyacınız varsa bir Map kullanın.