Type guard w TypeScript: jak sprawdzić typ obiektu

Type guard to sprawdzenie w czasie wykonania, które TypeScript rozumie, więc zawęża typ w sprawdzonej gałęzi. typeof, instanceof i in to wbudowane type guardy. Do wszystkiego innego piszesz funkcję, której typ zwracany to predykat typu, 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);
  }
}

isUser w czasie wykonania zwraca zwykły boolean. Typ zwracany value is User mówi kompilatorowi, czego dowodzi wynik true, i każde if (isUser(x)) zawęża potem x do User.

Wbudowane type guardy

Te sprawdzenia zawężają typ bez żadnej funkcji pomocniczej:

Wszystkie działają jako zwykły JavaScript. TypeScript dodaje zawężanie: odczytuje sprawdzenie i dopasowuje typ w każdej gałęzi. Pełną listę form znajdziesz na stronie o zawężaniu typów. Własny guard przydaje się do sprawdzeń, które nie mieszczą się w jednym wyrażeniu albo które chcesz używać wielokrotnie.

Pisanie predykatu typu

Predykat typu ma postać parameterName is Type i zastępuje boolean jako typ zwracany. Zawężanie działa w obie strony: true zawęża do Type, a false usuwa Type z unii.

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[])

Przekazanie guarda do filter daje poprawnie otypowaną tablicę. Od TypeScript 5.5 kompilator sam wnioskuje predykat z prostych funkcji strzałkowych, więc pets.filter((p) => p.kind === "cat") zwraca Cat[] bez nazwanego guarda.

Typ predykatu musi pasować do typu parametru: function f(x: string): x is number to błąd TS2677, A type predicate's type must be assignable to its parameter's type.

Kompilator ufa twojemu guardowi

TypeScript sprawdza, czy guard zwraca boolean. Nie sprawdza, czy ten boolean jest prawidłowy. Guard, który zwraca true dla złych wartości, sprawia, że typy kłamią, a program zawodzi w czasie wykonania bez żadnego błędu kompilacji.

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) rzuca w czasie wykonania TypeError: Cannot read properties of undefined (reading 'toFixed'). Kompilator uznał data.price za number, bo tak powiedział guard. Sprawdzaj każdą właściwość, na której polega reszta kodu, a guardy trzymaj małe, przetestowane i blisko typu, który opisują.

Sprawdzanie, czy obiekt ma dany typ

To pytanie stoi za większością własnych guardów: dane przychodzą jako unknown (z JSON.parse, fetch, localStorage, wiadomości) i musisz wiedzieć, czy pasują do twojego interfejsu. Przepis:

1. typeof value === "object" && value !== null (obiekt, a nie null).
2. "prop" in value dla każdej wymaganej właściwości. Na unknown operator in dodaje właściwość do typu jako unknown.
3. typeof value.prop === "..." (albo zagnieżdżony guard) dla typu każdej właściwości.
4. Array.isArray(value.items) && value.items.every(isItem) dla tablic.

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

Przy dużych albo głęboko zagnieżdżonych kształtach pisanie tego ręcznie staje się żmudne. Biblioteki schematów, takie jak Zod albo Valibot, pozwalają opisać kształt raz i dają zarówno sprawdzenie w czasie wykonania, jak i typ TypeScript.

Funkcje asercji: asserts value is Type

Funkcja asercji rzuca wyjątek, gdy sprawdzenie się nie powiedzie, a w przeciwnym razie normalnie kończy działanie. Jej typ zwracany to asserts value is Type (albo asserts condition), a wszystko po wywołaniu jest zawężone, bez potrzeby pisania 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
}

Jedna reguła często zaskakuje: funkcję asercji trzeba wywołać przez nazwę z jawnym typem. Funkcja strzałkowa w const bez adnotacji, const check = (v: unknown): asserts v is string => {...}, daje w miejscu wywołania błąd TS2775, Assertions require every name in the call target to be declared with an explicit type annotation. Użyj deklaracji function albo dodaj do stałej adnotację typu funkcji.

Guardy, asercje i rzutowania

Asercja typu (as) zmienia typ bez żadnego sprawdzenia. Na granicy, gdzie dane przychodzą z zewnątrz, guard albo funkcja asercji to bezpieczna wersja tego samego pomysłu.

Guardy oparte na this w klasach

Metoda może zawęzić obiekt, na którym jest wywoływana, przez this is Type. Przydaje się to w hierarchiach klas:

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
}