TypeScript Generics: Generic Fonksiyonlar, Tipler ve Sınıflar

Generics tip parametreleridir. Generic bir fonksiyon, genellikle T olarak adlandırılan bir yer tutucu tip bildirir ve her çağrı onu doldurur; böylece giren tipler çıkan tipleri belirler. Tek bir fonksiyon sayılar, string'ler ve kendi nesneleriniz için çalışır ve her çağrı yine tamamen tiplidir.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

Fonksiyon adından sonraki <T> tip parametresini bildirir. items: T[] onu girdi için, T | undefined ise çıktı için kullanır ve ikisini birbirine bağlar. number ya da string hiç yazmadınız: TypeScript T tipini argümandan çıkardı.

Neden any ya da unknown Değil?

Generics olmadan parametreyi any ya da unknown olarak tiplerdiniz. İkisi de her diziyi kabul eder ve ikisi de girdi ile çıktı arasındaki bağlantıyı kaybeder:

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

Tip Argümanı Çıkarımı

TypeScript genellikle tip argümanlarını geçirdiğiniz değerlerden çıkarır. Bunları çağrıda açılı parantez içinde açıkça da yazabilirsiniz; argümanlarda T ile ilgili hiçbir şey yoksa ya da çıkarım istemediğiniz bir şeyi seçerse bu gereklidir.

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

İki çıkarım sonucunu bilmekte fayda var. Açık argüman olmadan pair(1, "one") bir hatadır: TypeScript ilk argümandan T = number çıkarır ve ardından Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345) bildirir. Ve hiç argümanı olmayan emptyList(), T = unknown alır ve unknown[] verir; bu nadiren istediğiniz şeydir.

Birden Fazla Tip Parametresi

Bir fonksiyon, virgülle ayırarak ihtiyaç duyduğu kadar tip parametresi bildirebilir. Her biri bağımsız olarak çıkarılır.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues üç şeyi aynı anda çıkarır: K değeri "tea" | "cake", V değeri number, R ise callback'in dönüşünden string olur. K extends string bir kısıtlamadır (constraint) ve bir sonraki sayfada anlatılır.

Generic Interface'ler ve Type Alias'lar

Tipler de parametre alabilir. O zaman tipi kullanırken argümanı yazarsınız: Box<number>, ApiResponse<User>. Yerleşik koleksiyon tiplerinin çoğu bu şekilde çalışır: Array<T>, Map<K, V>, Promise<T>, Record<K, V>.

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

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

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> ayrıca bir varsayılan tip parametresi de gösteriyor: Result<number>, Result<number, string> anlamına gelir. Opsiyonel fonksiyon parametreleri gibi, varsayılanı olan parametreler zorunlu olanlardan sonra gelmelidir.

Generic Sınıflar

Bir sınıf, adından sonra tip parametreleri alır ve her örnek bunları sabitler. Alanlar, metotlar ve constructor parametreleri bunların hepsini kullanabilir.

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

Constructor bir T alıyorsa açık argümanı yazmayabilirsiniz: new Box(5), Box<number> olarak çıkarılır. Statik üyeler bir örneğe değil sınıfın kendisine aittir, bu yüzden sınıfın tip parametresini kullanamazlar (Static members cannot reference class type parameters., TS2302).

Generic Arrow Function'lar ve Fonksiyon Tipleri

Tip parametresi listesi parametre listesinin önüne gelir. Aynı sözdizimi generic bir fonksiyon tipini de tarif eder.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

const Tip Parametreleriyle Literal Tipleri Çıkarmak

Varsayılan olarak bir generic genişletilmiş tipler çıkarır: pair("a", "b") sonucu [string, string] olur. Tam değerler önemli olduğunda (route adları, event adları, sütun listeleri) parametreyi const olarak işaretleyin (TypeScript 5.0 ve sonrası); o zaman argüman as const ile yazılmış gibi çıkarım yapar:

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

Çağıran sıradan bir dizi yazar, fonksiyon ise literal tipleri korur.

Generics Ne Zaman Kullanılmamalı

Bir tip parametresi iki şeyi birbirine bağladığında yerini hak eder: bir parametre ile dönüş tipi, iki parametre ya da bir parametre ile bir callback. T yalnızca bir kez geçiyorsa hiçbir şey eklemez ve düz bir tip daha anlaşılırdır.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

Sonuncusu yaygındır ve yanıltıcıdır: parseJson<User>(text) tip güvenli görünür ama hiçbir şeyi kontrol etmez, tıpkı JSON.parse(text) as User gibi. Bunun yerine unknown döndürün ve doğrulayın. Aşırı kullanımın diğer işaretleri: her zaman aynı argümanı alan bir tip parametresi ya da bilinen iki tipin bir union'ı ile değiştirilebilecek bir tip parametresi.

T hakkında bir şey bilmesi gereken generics için (bir length özelliği olduğu ya da K değerinin T tipinin bir anahtarı olduğu gibi), sonraki adım extends ile yazılan kısıtlamalardır.