Generic Constraint di TypeScript: extends dan keyof T

Generic constraint membatasi apa yang boleh menjadi sebuah parameter tipe. <T extends { length: number }> hanya menerima tipe yang punya length berupa angka (string, array, object buatanmu sendiri), dan karena janji itu, fungsinya boleh membaca .length.

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);

Tipe kembaliannya tetap T, bukan { length: number }: mengirim dua array angka akan menghasilkan number[], dan object-nya tetap menyimpan tag. Constraint menjelaskan syarat minimumnya; tipe dari pemanggil tetap dipertahankan.

Kenapa Constraint Dibutuhkan

Di dalam fungsi generic, T tanpa constraint bisa berupa apa saja: string, angka, null, sebuah fungsi. Jadi TypeScript hanya mengizinkan operasi yang berlaku untuk semua tipe, dan itu hampir tidak ada.

// 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"));

Compiler mencetak:

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

Solusinya adalah menyatakan apa yang kamu butuhkan: <T extends { length: number }>. Constraint mengubah "tipe apa pun" menjadi "tipe apa pun yang punya ini", dan biasanya memang itulah maksud sebuah fungsi generic.

Membatasi ke Interface

Constraint bisa berupa tipe apa pun, termasuk interface atau type alias yang sudah kamu punya. Fungsinya lalu bekerja dengan apa pun yang setidaknya punya member tersebut, dan tetap mengembalikan tipe lengkap milik pemanggil.

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

Bandingkan dengan tipe parameter biasa: function byId(items: HasId[], id: number): HasId | undefined menerima array yang sama, tetapi hasilnya hanya HasId, jadi found.name akan menjadi error. Versi generic meneruskan tipe lengkapnya.

K extends keyof T: Akses Properti yang Aman

Constraint yang paling umum menghubungkan dua parameter tipe. K extends keyof T menyatakan bahwa K harus salah satu nama properti T, dan T[K] adalah tipe properti tersebut.

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");

Key yang salah ketik atau tidak ada adalah error kompilasi, dan tipe kembaliannya mengikuti key-nya: "year" menghasilkan number, "title" menghasilkan string. Halaman keyof membahas keyof itu sendiri, termasuk perilakunya dengan index signature.

Membatasi ke Tipe Primitif

Constraint bisa berupa tipe primitif atau union dari beberapa tipe primitif. Ada efek samping yang berguna: kalau T extends string (atau number), TypeScript menyimpulkan tipe literal dari argumennya, bukan melebarkannya.

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

Tanpa constraint, createEvent("user.saved") mengembalikan { type: string }: di sini TypeScript melebarkan literal yang disimpulkannya untuk T menjadi string. Dengan T extends string, literalnya dipertahankan. Begitulah helper event dan routing yang bertipe bisa mendapatkan nama yang persis dari argumen string biasa.

Error yang Umum

Mengembalikan sesuatu yang hanya cocok dengan constraint. Fungsi yang mengembalikan T harus mengembalikan T, bukan sembarang nilai yang cocok dengan constraint-nya:

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

Kalau T adalah { id: number; name: string }, object baru itu tidak punya name, jadi bukan T. Kembalikan hasil spread dari input, return { ...item, id: 0 };, yang mempertahankan semua properti, atau deklarasikan tipe kembaliannya sebagai HasId kalau memang hanya itu yang kamu hasilkan.

Mengirim argumen tipe yang melanggar constraint. Argumen tipe yang ditulis eksplisit juga diperiksa: dengan function scale<T extends number>(x: T), pemanggilan scale<string>("2") gagal dengan Type 'string' does not satisfy the constraint 'number'. (TS2344).

Memakai constraint padahal tidak butuh generic. Kalau T hanya muncul di parameter, function print<T extends HasId>(item: T): void sama saja dengan function print(item: HasId): void ditambah sintaks ekstra. Constraint baru berarti kalau T juga muncul di tipe kembalian atau di parameter lain.

Constraint dengan Nilai Default

Parameter tipe bisa punya constraint sekaligus nilai default. Nilai default itu harus memenuhi constraint-nya.

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

Kata kunci extends yang sama juga muncul di conditional type, T extends string ? A : B, dan di sana ia adalah pengujian, bukan pembatasan; halaman conditional type membahas bentuk itu.