keyof trong TypeScript: lấy khóa của đối tượng thành kiểu

keyof nhận một kiểu đối tượng và tạo ra union các tên thuộc tính của nó. keyof User dưới đây là kiểu "id" | "name" | "email", nên một biến có kiểu đó chỉ giữ được một trong ba chuỗi ấy.

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 chỉ tồn tại trong hệ thống kiểu. Nó bị xóa khi code được biên dịch, nên không bao giờ kiểm tra gì lúc chạy. Thứ nó mang lại là sự đảm bảo lúc biên dịch rằng một khóa là tên của một thuộc tính có thật: đổi tên email trong interface, và mọi "email" có kiểu keyof User đều thành lỗi.

keyof typeof: khóa của một đối tượng thường

keyof hoạt động trên kiểu, không phải giá trị. Với một đối tượng bạn viết dưới dạng giá trị, trước hết lấy kiểu của nó bằng typeof, rồi mới lấy các khóa:

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

Đọc từ trong ra ngoài: typeof colors là { red: string; green: string; blue: string }, và keyof của kiểu đó là union các khóa. Viết keyof colors mà không có typeof sẽ báo error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

Đây là cách thông dụng để suy ra một union từ bảng tra cứu: thêm một màu vào đối tượng và kiểu Color tự lớn theo. typeof còn có ý nghĩa thứ hai lúc chạy; trang typeof trình bày cả hai.

Truy cập thuộc tính có kiểu bằng generic

Cách dùng keyof phổ biến nhất là làm ràng buộc generic. K extends keyof T nghĩa là "K là một trong các khóa của T", và T[K] là kiểu của thuộc tính tại khóa đó:

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

Type parameter thứ hai rất quan trọng. Với key: keyof T và không có K, kiểu trả về là T[keyof T], tức union của mọi kiểu thuộc tính (ở đây là string | number | boolean), nên title.toUpperCase() sẽ báo error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. Giữ đúng khóa trong K giúp giữ đúng kiểu thuộc tính. T[K] là một indexed access type, được mô tả ở trang indexed access types.

Truy cập bằng một string thông thường

Một lỗi rất hay gặp xuất hiện khi bạn truy cập đối tượng bằng một string đến từ nơi khác:

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

Trình biên dịch in ra:

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

Bất kỳ chuỗi nào cũng có thể được truyền vào read, kể cả "colour", và Settings không nói gì về khóa đó. Có hai cách sửa: chỉ nhận các khóa có thật, hoặc kiểm tra chuỗi chưa rõ trước khi dùng.

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 là một type predicate: khi hàm trả về true, TypeScript coi input là một khóa bên trong khối if. Trang type guard giải thích chi tiết về predicate.

keyof với index signature: string | number

Với kiểu có index signature, keyof trả về kiểu của chỉ số, và string index signature cho ra string | number, không chỉ 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 chuyển mọi khóa thuộc tính dạng số thành chuỗi, nên scores[42] và scores["42"] là cùng một thuộc tính. TypeScript mô hình hóa điều đó bằng cách thêm number. Đầu ra còn cho thấy một quy tắc của JavaScript: các khóa dạng số nguyên được liệt kê trước, theo thứ tự tăng dần, rồi mới đến các khóa chuỗi khác. Khi một hàm generic chỉ cần khóa dạng chuỗi, hãy viết Extract<keyof T, string> hoặc string & keyof T; Exclude và Extract có trang riêng.

Tóm tắt kết quả của keyof

Hai dòng union và intersection thoạt nhìn có vẻ ngược. Một giá trị kiểu union có thể là bất kỳ thành viên nào, nên chỉ những khóa có ở cả hai mới an toàn. Một giá trị kiểu intersection có mọi thứ của cả hai, nên nó có tất cả các khóa.

Vì sao Object.keys trả về string[]

Object.keys(obj) có kiểu string[], không bao giờ là (keyof T)[]. Lý do là structural typing: một giá trị có thể mang nhiều thuộc tính hơn kiểu đã khai báo.

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 có kiểu Point, nhưng lúc chạy nó có khóa z. Nếu Object.keys hứa trả về ("x" | "y")[], code dựa vào điều đó sẽ sai với p. Phép ép kiểu an toàn với các object literal do chính bạn tạo; với đối tượng đến từ bên ngoài, hãy giữ khóa là string và kiểm tra chúng.

keyof trong mapped type

keyof cũng là cách để lặp qua các khóa của một kiểu nhằm tạo kiểu mới. Các utility type có sẵn như Partial và Readonly được viết theo cách này:

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] duyệt từng khóa, và T[K] đọc kiểu thuộc tính tại khóa đó. Mapped type có trang riêng, kèm modifier và cách đổi tên khóa.