keyof di TypeScript: Key Object sebagai Tipe, dengan Contoh

keyof menerima tipe object dan menghasilkan union dari nama-nama propertinya. keyof User di bawah adalah tipe "id" | "name" | "email", jadi variabel bertipe itu hanya bisa berisi salah satu dari ketiga string tersebut.

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 hanya ada di sistem tipe. Operator ini dihapus saat kode dikompilasi, jadi tidak pernah memeriksa apa pun saat runtime. Yang diberikannya adalah jaminan saat kompilasi bahwa sebuah key memang menunjuk ke properti yang ada: ganti nama email di interface, dan setiap "email" yang bertipe keyof User langsung menjadi error.

keyof typeof: Key dari Object Biasa

keyof bekerja pada tipe, bukan nilai. Untuk object yang kamu tulis sebagai nilai, ambil dulu tipenya dengan typeof, lalu ambil key-nya:

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

Baca dari dalam ke luar: typeof colors adalah { red: string; green: string; blue: string }, dan keyof dari tipe itu adalah union key-nya. Menulis keyof colors tanpa typeof gagal dengan error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

Inilah cara yang umum untuk menurunkan union dari sebuah tabel lookup: tambahkan warna ke object itu, dan tipe Color ikut bertambah. typeof juga punya arti kedua saat runtime; halaman typeof membahas keduanya.

Akses Properti Bertipe dengan Generic

Pemakaian keyof yang paling umum adalah sebagai generic constraint. K extends keyof T menyatakan "K adalah salah satu key dari T", dan T[K] adalah tipe properti pada key tersebut:

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

Parameter tipe kedua itu penting. Dengan key: keyof T tanpa K, tipe kembaliannya adalah T[keyof T], yaitu union dari semua tipe properti (di sini string | number | boolean), jadi title.toUpperCase() akan gagal dengan error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Menangkap key yang persis di K mempertahankan tipe properti yang persis pula. T[K] adalah indexed access type, yang dijelaskan di halaman indexed access type.

Memberi Indeks dengan string Biasa

Error yang sangat sering muncul terjadi saat kamu memberi indeks pada object dengan string yang berasal dari tempat lain:

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

Compiler mencetak:

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

String apa pun bisa sampai ke read, termasuk "colour", dan Settings tidak menyatakan apa pun tentang key itu. Ada dua cara memperbaikinya: hanya terima key yang benar-benar ada, atau periksa string yang tidak dikenal sebelum memakainya.

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 adalah type predicate: kalau fungsi itu mengembalikan true, TypeScript memperlakukan input sebagai key di dalam if. Halaman type guard menjelaskan predicate secara detail.

keyof dengan Index Signature: string | number

Untuk tipe dengan index signature, keyof mengembalikan tipe indeksnya, dan string index signature menghasilkan string | number, bukan hanya string:

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 mengubah setiap key properti berupa angka menjadi string, jadi scores[42] dan scores["42"] adalah properti yang sama. TypeScript memodelkan hal itu dengan menyertakan number. Output-nya juga menunjukkan sebuah aturan JavaScript: key yang mirip bilangan bulat ditampilkan lebih dulu, berurutan naik, sebelum key string lainnya. Kalau fungsi generic hanya butuh key berupa string, tulis Extract<keyof T, string> atau string & keyof T; Exclude dan Extract punya halamannya sendiri.

Ringkasan Hasil keyof

Baris union dan intersection awalnya terlihat terbalik. Nilai bertipe union bisa berupa member yang mana saja, jadi hanya key yang ada di keduanya yang aman. Nilai bertipe intersection punya semua yang ada di kedua tipe, jadi ia punya semua key-nya.

Kenapa Object.keys Mengembalikan string[]

Object.keys(obj) diberi tipe string[], tidak pernah (keyof T)[]. Alasannya adalah structural typing: sebuah nilai bisa membawa lebih banyak properti daripada tipe yang dideklarasikan.

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 bertipe Point, tetapi saat runtime ia punya key z. Kalau Object.keys menjanjikan ("x" | "y")[], kode yang mengandalkan janji itu akan salah untuk p. Cast tersebut aman untuk object literal yang kamu buat sendiri; untuk object yang datang dari luar, biarkan key-nya bertipe string dan periksa.

keyof di Mapped Type

keyof juga merupakan cara untuk menelusuri key sebuah tipe demi membangun tipe baru. Begitulah utility type bawaan Partial dan Readonly ditulis:

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] mengunjungi setiap key, dan T[K] membaca tipe properti pada key tersebut. Mapped type punya halamannya sendiri, lengkap dengan modifier dan key remapping.