TypeScript Generic Kısıtlamaları: extends ve keyof T

Bir generic kısıtlaması, bir tip parametresinin ne olabileceğini sınırlar. <T extends { length: number }> yalnızca sayısal bir length özelliğine sahip tipleri (string'ler, diziler, kendi nesneleriniz) kabul eder ve bu vaat sayesinde fonksiyonun .length okumasına izin verilir.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

Dönüş tipi { length: number } değil, hâlâ T tipidir: iki sayı dizisi geçirirseniz geriye number[] döner ve nesneler tag özelliklerini korur. Kısıtlama asgariyi tarif eder; çağıranın tipi korunur.

Kısıtlamalara Neden İhtiyaç Var

Generic bir fonksiyonun içinde kısıtlanmamış bir T herhangi bir şey olabilir: bir string, bir sayı, null, bir fonksiyon. Bu yüzden TypeScript yalnızca her tipte çalışan şeylere izin verir, bu da neredeyse hiçbir şeydir.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

Derleyici şunu yazdırır:

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

Çözüm neye ihtiyacınız olduğunu söylemektir: <T extends { length: number }>. Kısıtlamalar "herhangi bir tip" ifadesini "şuna sahip herhangi bir tip" ifadesine dönüştürür; generic bir fonksiyonun kastettiği de genellikle budur.

Bir Interface ile Kısıtlamak

Kısıtlama, zaten sahip olduğunuz bir interface ya da type alias dahil herhangi bir tip olabilir. Fonksiyon bu durumda en azından o üyelere sahip her şeyle çalışır ve yine de çağıranın tam tipini döndürür.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

Düz bir parametre tipiyle karşılaştırın: function byId(items: HasId[], id: number): HasId | undefined aynı dizileri kabul eder, ama sonuç yalnızca HasId olur; bu yüzden found.name bir hata olurdu. Generic sürüm tam tipi olduğu gibi aktarır.

K extends keyof T: Güvenli Özellik Erişimi

En yaygın kısıtlama iki tip parametresini birbirine bağlar. K extends keyof T, K değerinin T tipinin özellik adlarından biri olması gerektiğini söyler; T[K] ise o özelliğin tipidir.

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

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

Yanlış yazılmış ya da var olmayan bir anahtar bir derleme hatasıdır ve dönüş tipi anahtarı izler: "year" sonucu number, "title" sonucu string olur. İndeks imzalarıyla nasıl davrandığı dahil keyof operatörünün kendisi keyof sayfasında anlatılıyor.

Primitive Tiplerle Kısıtlamak

Bir kısıtlama bir primitive tip ya da onların bir union'ı olabilir. İşe yarar bir yan etkisi var: T extends string (ya da number) olduğunda TypeScript argümanın tipini genişletmek yerine onun literal tipini çıkarır.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

Kısıtlama olmadan createEvent("user.saved"), { type: string } döndürür: burada TypeScript T için çıkardığı literal'i string olarak genişletir. T extends string ile literal korunur; tipli event ve routing yardımcıları düz string argümanlarından tam adları bu şekilde elde eder.

Sık Görülen Hatalar

Yalnızca kısıtlamaya uyan bir şey döndürmek. T döndüren bir fonksiyon, kısıtlamaya uyan herhangi bir değeri değil, bir T döndürmelidir:

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

T tipi { id: number; name: string } ise yeni nesnenin name özelliği yoktur, dolayısıyla bir T değildir. Her özelliği koruyan bir spread döndürün, return { ...item, id: 0 };, ya da ürettiğiniz tek şey buysa dönüş tipini HasId olarak bildirin.

Kısıtlamayı bozan bir tip argümanı geçirmek. Açık tip argümanları da kontrol edilir: function scale<T extends number>(x: T) ile scale<string>("2") çağrısı Type 'string' does not satisfy the constraint 'number'. (TS2344) hatasıyla başarısız olur.

Generic gerekmediği halde kısıtlama yazmak. T yalnızca parametrede geçiyorsa function print<T extends HasId>(item: T): void, fazladan sözdizimiyle yazılmış function print(item: HasId): void ifadesinden ibarettir. Kısıtlamalar, T dönüş tipinde ya da başka bir parametrede de geçtiğinde önem kazanır.

Varsayılanlı Kısıtlamalar

Bir tip parametresinin hem bir kısıtlaması hem de bir varsayılanı olabilir. Varsayılan, kısıtlamayı karşılamalıdır.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

Aynı extends anahtar kelimesi koşullu tiplerde de (T extends string ? A : B) görünür; orada bir sınırlama değil bir testtir. Bu biçim koşullu tipler sayfasında anlatılıyor.