Type guard trong TypeScript: kiểm tra kiểu của đối tượng

Type guard là một phép kiểm tra lúc chạy mà TypeScript hiểu được, nhờ đó nó thu hẹp kiểu bên trong nhánh đã kiểm tra. typeof, instanceof và in là các guard dựng sẵn; với mọi trường hợp khác, bạn viết một hàm có kiểu trả về là type predicate, value is Type.

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

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

Lúc chạy, isUser trả về một boolean bình thường. Kiểu trả về value is User cho trình biên dịch biết kết quả true chứng minh được điều gì, và sau đó mọi if (isUser(x)) đều thu hẹp x thành User.

Các type guard dựng sẵn

Những phép kiểm tra này thu hẹp kiểu mà không cần hàm hỗ trợ nào:

Tất cả đều chạy như JavaScript bình thường. Điều TypeScript thêm vào là việc thu hẹp kiểu: nó đọc phép kiểm tra và điều chỉnh kiểu trong từng nhánh. Danh sách đầy đủ các dạng nằm ở trang thu hẹp kiểu. Guard tự viết dành cho những phép kiểm tra không gói gọn trong một biểu thức, hoặc những phép bạn muốn dùng lại.

Viết một type predicate

Type predicate có dạng parameterName is Type và thay cho boolean ở vị trí kiểu trả về. Việc thu hẹp hoạt động theo cả hai chiều: true thu hẹp thành Type, còn false loại Type khỏi union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Truyền một guard cho filter sẽ cho ra một mảng có kiểu chính xác. Từ TypeScript 5.5, trình biên dịch còn tự suy ra predicate từ những arrow function đơn giản, nên pets.filter((p) => p.kind === "cat") trả về Cat[] mà không cần một guard có tên.

Kiểu của predicate phải khớp với kiểu của tham số: function f(x: string): x is number là lỗi TS2677, A type predicate's type must be assignable to its parameter's type.

Trình biên dịch tin guard của bạn

TypeScript kiểm tra rằng guard trả về một boolean. Nó không kiểm tra boolean đó có đúng không. Một guard trả về true cho giá trị sai sẽ khiến kiểu nói dối, và chương trình hỏng lúc chạy mà không có lỗi biên dịch nào.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) ném lỗi TypeError: Cannot read properties of undefined (reading 'toFixed') lúc chạy. Trình biên dịch chấp nhận data.price là number vì guard đã nói vậy. Hãy kiểm tra mọi thuộc tính mà phần code còn lại dựa vào, và giữ guard ngắn gọn, có test và đặt gần kiểu mà nó mô tả.

Kiểm tra một đối tượng có thuộc một kiểu không

Đây là câu hỏi đứng sau phần lớn các guard tự viết: dữ liệu đến dưới dạng unknown (từ JSON.parse, fetch, localStorage, một message) và bạn cần biết nó có khớp với interface của mình không. Công thức:

1. typeof value === "object" && value !== null (là đối tượng, không phải null).
2. "prop" in value cho từng thuộc tính bắt buộc. Trên unknown, in thêm thuộc tính đó vào kiểu với kiểu unknown.
3. typeof value.prop === "..." (hoặc một guard lồng nhau) cho kiểu của từng thuộc tính.
4. Array.isArray(value.items) && value.items.every(isItem) cho mảng.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Với những cấu trúc lớn hoặc lồng sâu, viết tay các phép này rất mất công. Các thư viện schema như Zod hay Valibot cho bạn mô tả cấu trúc một lần và nhận về cả phép kiểm tra lúc chạy lẫn kiểu TypeScript.

Hàm assertion: asserts value is Type

Hàm assertion ném lỗi nếu kiểm tra thất bại, và trả về bình thường nếu thành công. Kiểu trả về của nó là asserts value is Type (hoặc asserts condition), và mọi thứ sau lời gọi đều được thu hẹp kiểu mà không cần if.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

Có một quy tắc hay làm người ta vấp: hàm assertion phải được gọi qua một tên có kiểu tường minh. Một arrow function gán vào const mà không có chú thích kiểu, const check = (v: unknown): asserts v is string => {...}, gây lỗi TS2775 tại nơi gọi, Assertions require every name in the call target to be declared with an explicit type annotation. Hãy dùng khai báo function, hoặc chú thích hằng số đó bằng một kiểu hàm.

Guard, assertion và ép kiểu

Một type assertion (as) đổi kiểu mà không kiểm tra gì. Ở ranh giới nơi dữ liệu đến từ bên ngoài, guard hoặc hàm assertion là phiên bản an toàn của cùng ý tưởng đó.

Guard dựa trên this trong class

Một phương thức có thể thu hẹp kiểu của chính đối tượng gọi nó bằng this is Type. Cách này rất tiện trong hệ thống phân cấp class:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}