TypeScript keyof: Nesne Anahtarlarını Tip Olarak Almak, Örneklerle

keyof bir nesne tipi alır ve özellik adlarının union'ını üretir. Aşağıdaki keyof User, "id" | "name" | "email" tipidir; bu yüzden o tipteki bir değişken yalnızca bu üç string'den birini tutabilir.

interface User {
  id: number;
  name: string;
  email: string;
}

type UserKey = keyof User; // "id" | "name" | "email"

const key: UserKey = "name"; // OK
// @ts-expect-error: "age" is not one of the keys of User
const wrong: UserKey = "age";

function printField(user: User, field: keyof User) {
  console.log(`${field}: ${user[field]}`);
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };
printField(ada, "email"); // email: ada@example.com
printField(ada, key);     // name: Ada

keyof yalnızca tip sisteminde vardır. Kod derlendiğinde silinir, dolayısıyla çalışma zamanında hiçbir şeyi kontrol etmez. Size verdiği şey, bir anahtarın gerçek bir özelliği adlandırdığına dair derleme zamanı garantisidir: interface'teki email adını değiştirin, keyof User olarak tiplenmiş her "email" bir hataya dönüşür.

keyof typeof: Düz Bir Nesnenin Anahtarları

keyof değerler üzerinde değil tipler üzerinde çalışır. Değer olarak yazdığınız bir nesne için önce typeof ile tipini alın, ardından anahtarlarını çıkarın:

const colors = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};

type Color = keyof typeof colors; // "red" | "green" | "blue"

function hex(color: Color): string {
  return colors[color];
}

console.log(hex("green")); // #00ff00
// hex("purple") would be error TS2345:
// Argument of type '"purple"' is not assignable to parameter of type '"blue" | "green" | "red"'.

İçten dışa doğru okuyun: typeof colors, { red: string; green: string; blue: string } tipidir ve onun keyof sonucu anahtar union'ıdır. typeof olmadan keyof colors yazmak error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'? ile başarısız olur.

Bir arama tablosundan union türetmenin olağan yolu budur: nesneye bir renk ekleyin, Color tipi de onunla birlikte büyür. typeof operatörünün ikinci bir, çalışma zamanı anlamı da vardır; typeof sayfası ikisini de anlatıyor.

Generics ile Tipli Özellik Erişimi

keyof operatörünün en yaygın kullanımı bir generic kısıtlamasıdır. K extends keyof T "K, T'nin anahtarlarından biridir" der ve T[K] o anahtardaki özelliğin tipidir:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const book = { title: "Dune", pages: 412, inStock: true };

const pages = getProperty(book, "pages"); // number
const title = getProperty(book, "title"); // string

console.log(pages + 1);           // 413
console.log(title.toUpperCase()); // DUNE
// getProperty(book, "author") would be error TS2345

İkinci tip parametresi önemlidir. K olmadan yalnızca key: keyof T kullanılırsa dönüş tipi T[keyof T], yani tüm özellik tiplerinin union'ı olur (burada string | number | boolean); bu yüzden title.toUpperCase(), error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean' ile başarısız olurdu. Tam anahtarı K içinde yakalamak, tam özellik tipini korur. T[K] bir indeksli erişim tipidir ve indeksli erişim tipleri sayfasında anlatılır.

Düz Bir string ile İndekslemek

Bir nesneyi başka bir yerden gelen bir string ile indekslediğinizde çok yaygın bir hata ortaya çıkar:

// This does not compile: a plain string is not a key of Settings
interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

function read(name: string) {
  return settings[name];
}

console.log(read("theme"));

Derleyici şunu yazdırır:

index.ts(10,10): error TS7053: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Settings'.
  No index signature with a parameter of type 'string' was found on type 'Settings'.

read fonksiyonuna "colour" dahil herhangi bir string ulaşabilir ve Settings bu anahtar hakkında hiçbir şey söylemez. İki çözüm var: yalnızca gerçek anahtarları kabul edin ya da bilinmeyen bir string'i kullanmadan önce kontrol edin.

interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

// Fix 1: only accept real keys
function read(name: keyof Settings) {
  return settings[name];
}
console.log(read("fontSize")); // 14

// Fix 2: narrow a string you do not control
function isSettingsKey(name: string): name is keyof Settings {
  return Object.hasOwn(settings, name);
}

for (const input of ["theme", "colour"]) {
  if (isSettingsKey(input)) {
    console.log(input, "=", settings[input]);
  } else {
    console.log(input, "is not a setting");
  }
}
// theme = dark
// colour is not a setting

name is keyof Settings bir tip yüklemidir (type predicate): fonksiyon true döndürdüğünde TypeScript if içindeki input değerini bir anahtar olarak ele alır. Yüklemler type guard'lar sayfasında ayrıntılı olarak anlatılıyor.

İndeks İmzalarıyla keyof: string | number

İndeks imzası olan bir tip için keyof indeks tipini döndürür ve bir string indeks imzası yalnızca string değil, string | number verir:

type Scores = { [player: string]: number };

type ScoreKey = keyof Scores; // string | number

const scores: Scores = { ada: 3 };
scores[42] = 7; // allowed: a number key is a valid key

console.log(Object.keys(scores)); // [ '42', 'ada' ]

type OnlyStrings = Extract<keyof Scores, string>; // string
const k: OnlyStrings = "ada";
console.log(k);

JavaScript her sayısal özellik anahtarını string'e çevirir, bu yüzden scores[42] ve scores["42"] aynı özelliktir. TypeScript bunu number tipini ekleyerek modeller. Çıktı ayrıca bir JavaScript kuralını da gösteriyor: tam sayıya benzeyen anahtarlar diğer string anahtarlardan önce, artan sırayla listelenir. Generic bir fonksiyonun yalnızca string anahtarlara ihtiyacı olduğunda Extract<keyof T, string> ya da string & keyof T yazın; Exclude ve Extract için ayrı bir sayfa var.

Bir Bakışta keyof Sonuçları

Union ve intersection satırları ilk bakışta ters görünür. Bir union tipindeki değer üyelerden herhangi biri olabilir, bu yüzden yalnızca her ikisinde de bulunan anahtarlar güvenlidir. Bir intersection değeri ise ikisindeki her şeye sahiptir, dolayısıyla tüm anahtarlara sahiptir.

Object.keys Neden string[] Döndürür

Object.keys(obj) her zaman string[] olarak tiplenir, asla (keyof T)[] olarak değil. Nedeni yapısal tiplemedir: bir değer, bildirilen tipinden daha fazla özellik taşıyabilir.

interface Point {
  x: number;
  y: number;
}

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // allowed: extra properties are fine here

console.log(Object.keys(p)); // [ 'x', 'y', 'z' ]

// When you know the object has exactly its declared keys, cast:
const origin = { x: 0, y: 0 };
for (const key of Object.keys(origin) as (keyof typeof origin)[]) {
  console.log(key, origin[key]);
}
// x 0
// y 0

p değeri Point olarak tiplenmiştir, ama çalışma zamanında bir z anahtarı vardır. Object.keys, ("x" | "y")[] vaat etseydi, buna güvenen kod p için yanlış olurdu. Cast, kendiniz oluşturduğunuz nesne literalleri için güvenlidir; dışarıdan gelen nesneler için anahtarları string olarak tutun ve kontrol edin.

Mapped Type'larda keyof

keyof aynı zamanda yeni bir tip oluşturmak için bir tipin anahtarları üzerinde dolaşmanın yoludur. Yerleşik Partial ve Readonly yardımcı tipleri bu şekilde yazılmıştır:

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

interface User {
  id: number;
  name: string;
}

type UserDraft = MyPartial<User>; // { id?: number; name?: string }

[K in keyof T] her anahtarı ziyaret eder, T[K] ise o anahtardaki özellik tipini okur. Mapped type'ların belirleyicileri ve anahtar yeniden eşlemeyi anlatan ayrı bir sayfası var.