TypeScript Mapped Types: Sözdizimi, Belirleyiciler…

Q: Bir mapped type'ta +readonly, -readonly, +? ve -? ne anlama gelir?

Belirleyici ekler ya da kaldırırlar. readonly veya +readonly her özelliği readonly yapar, -readonly readonly'yi kaldırır. ? veya +? her özelliği opsiyonel yapar, -? ise onları zorunlu yapar ve tiplerinden undefined değerini de çıkarır. Required , -? ile yazılmıştır.

Q: Bir mapped type'ta anahtarları nasıl yeniden adlandırırım?

Anahtardan sonra bir as ifadesi kullanın: { [K in keyof T as get${Capitalize }]: () => T[K] } , name anahtarını getName yapar. as ifadesinde bir anahtarı never olarak eşlemek onu kaldırır; özellikleri filtrelemenin yolu budur.

Q: Partial ve Readonly nasıl implement edilmiştir?

Standart kütüphanede mapped type olarak: type Partial = { [P in keyof T]?: T[P] } ve type Readonly = { readonly [P in keyof T]: T[P] }. Pick ve Record da mapped type'tır; Omit ise Pick ile Exclude birleşimidir.

Mapped type, bir anahtar kümesi üzerinde dönerek yeni bir nesne tipi oluşturur. { [K in keyof T]: boolean }, "T tipinin her K anahtarı için, boolean tipinde K adlı bir özellik" anlamına gelir:

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

Features tipine bir anahtar ekleyin, Flags<Features> de onu ister. Mapped type'lar yalnızca derleme zamanında vardır: nesneleri tarif ederler, onları oluşturmazlar.

Sözdizimi

Bir mapped type'ın üç parçası vardır: bir anahtar değişkeni, üzerinde dönülecek bir anahtar union'ı ve anahtar değişkenini kullanabilen özellik tipi.

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

Keys herhangi bir string, number veya symbol union'ı olabilir. keyof üzerinden gelmesi gerekmez:

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

Record<Size, number> tam olarak bunu yapar; Record tek satırlık bir mapped type'tır. Özellik tipi anahtarı kullanabilir: { [K in keyof T]: T[K] } her özellik tipini bir indeksli erişimle olduğu gibi kopyalar, { [K in keyof T]: T[K] | null } ise her özelliği nullable yapar.

Belirleyiciler: +/- ile readonly ve ?

Bir mapped type, readonly ve opsiyonel (?) belirleyicilerini tüm özelliklere aynı anda ekleyebilir ya da onlardan kaldırabilir. Eklemek için başına + (hiçbir şey yazmadığınızda varsayılan budur), kaldırmak için - koyun:

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

Son satır, readonly belirleyicisinin yalnızca bir derleme zamanı kuralı olduğunu gösteriyor: atama bildirildi (ve burada @ts-expect-error ile bastırıldı), ama üretilen JavaScript onu yine de çalıştırdı. -? soru işaretini düşürmekten fazlasını yapar: özellik tipinden undefined değerini de çıkarır; bu yüzden AllRequired<Account>, { id: 1, email: undefined } değerini error TS2322: Type 'undefined' is not assignable to type 'string' ile reddeder.

Partial, Readonly, Pick ve Record Nasıl Yazılmıştır

Nesneleri yeniden biçimlendiren yerleşik yardımcı tipler mapped type'tır. Bunlar TypeScript'in kendi lib.es5.d.ts dosyasındaki tanımlardır:

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

Onları okumak iyi bir alıştırmadır: Pick yalnızca geçirdiğiniz anahtarlar üzerinde döner, Record ise herhangi bir kaynak tipi yok sayar ve her anahtara aynı değer tipini verir. Omit kendi başına bir mapped type değildir: Pick<T, Exclude<keyof T, K>> ifadesidir. Yardımcı tipler referansı hepsini listeliyor.

as ile Anahtar Yeniden Eşleme

Anahtardan sonra gelen bir as ifadesi özellik adını değiştirir. Template literal tiplerle birleştirildiğinde eski adlardan yeni adlar üretebilir:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

string & K orada, çünkü keyof T, number ve symbol anahtarlar içerebilir ve Capitalize yalnızca string kabul eder. Intersection, string anahtarları tutar ve gerisini atar.

never ile Anahtarları Filtrelemek

as ifadesi bir anahtar için never üretirse o anahtar kaldırılır. Bir koşullu tiple, özellikleri tiplerine göre tutabilir ya da atabilirsiniz:

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

DataOnly gibi tipler, JSON.stringify sonrasında neyin kaldığını ya da bir formun neyi düzenlediğini tarif etmek için işe yarar: metotlar olmadan alanlar.

Hangi Belirleyiciler Korunur

Bir T tipi için keyof T üzerinden yazılan bir mapped type'a homomorfik denir ve her özelliğin readonly ve ? belirleyicilerini T tipinden kopyalar. Düz bir anahtar union'ı üzerinden yazılan bir mapped type ise hiç belirleyiciyle başlamaz:

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

B tipinde email hâlâ undefined içerir, çünkü Account["email"] onu içerir; ama özelliğin kendisi artık opsiyonel değildir: { id: 1 } reddedilir. Partial<T> ve benzerlerinin keyof T üzerinden eşleme yapmasının nedeni budur: açıkça değiştirmedikleri her şeyi korurlar.

Bir diziye ya da tuple'a uygulanan generic homomorfik bir mapped type, sayısal anahtarlı bir nesne değil, bir dizi ya da tuple üretir. Readonly<string[]>, readonly string[] olur; type Box<T> = { [K in keyof T]: { value: T[K] } } ile de Box<[string, number]>, [{ value: string }, { value: number }] olur.

Mapped Type'lar ve Çalışma Zamanı Kodu

Bir mapped type yalnızca bir nesneyi tarif ettiği için, böyle bir nesne oluşturan bir fonksiyonun kendi çalışma zamanı döngüsüne ihtiyacı vardır. Tip ise onun sonucunu tarif eder:

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

Callback'ler parametre tiplerini hiçbir notasyon olmadan mapped type'tan alır (v birinde string, diğerinde number olur). Buraya tip eşleme yerine Map sınıfını aramak için geldiyseniz TypeScript'te Map sayfasına bakın.

Sıkça Sorulan Sorular

TypeScript'te mapped type nedir?

Bir anahtar union'ı üzerinde dönerek bir nesne tipi oluşturan tiptir: { [K in Keys]: SomeType }. Anahtarlar çoğunlukla keyof T olur; böylece yeni tip, type Flags<T> = { [K in keyof T]: boolean } örneğindeki gibi, T ile aynı anahtarlara ve dönüştürülmüş özellik tiplerine sahip olur.

Bir mapped type'ta +readonly, -readonly, +? ve -? ne anlama gelir?

Belirleyici ekler ya da kaldırırlar. readonly veya +readonly her özelliği readonly yapar, -readonly readonly'yi kaldırır. ? veya +? her özelliği opsiyonel yapar, -? ise onları zorunlu yapar ve tiplerinden undefined değerini de çıkarır. Required<T>, -? ile yazılmıştır.

Bir mapped type'ta anahtarları nasıl yeniden adlandırırım?

Anahtardan sonra bir as ifadesi kullanın: { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] }, name anahtarını getName yapar. as ifadesinde bir anahtarı never olarak eşlemek onu kaldırır; özellikleri filtrelemenin yolu budur.

Mapped type, TypeScript'teki Map ile aynı şey midir?

Hayır. Mapped type, derleme zamanında yapılan bir tip dönüşümüdür ve hiç kod üretmez. Map<K, V> ise JavaScript'in Map sınıfıdır, anahtar değer çiftlerinden oluşan bir çalışma zamanı koleksiyonudur. "typescript map type" aramaları çoğu zaman ikisinden birini kasteder.

Partial ve Readonly nasıl implement edilmiştir?

Standart kütüphanede mapped type olarak: type Partial<T> = { [P in keyof T]?: T[P] } ve type Readonly<T> = { readonly [P in keyof T]: T[P] }. Pick ve Record da mapped type'tır; Omit ise Pick ile Exclude birleşimidir.

İlgili kavramlar