Защитники типов в TypeScript: как проверить тип объекта

Защитник типа это проверка во время выполнения, которую понимает TypeScript, поэтому внутри проверенной ветки он сужает тип. typeof, instanceof и in это встроенные защитники; для всего остального вы пишете функцию, возвращаемый тип которой это предикат типа, 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 возвращает обычный boolean. Возвращаемый тип value is User сообщает компилятору, что доказывает результат true, и каждое if (isUser(x)) затем сужает x до User.

Встроенные защитники типов

Эти проверки сужают тип без всяких вспомогательных функций:

Все они выполняются как обычный JavaScript. TypeScript добавляет сужение: читает проверку и подстраивает тип в каждой ветке. Полный список форм на странице сужение типов. Собственный защитник нужен для проверок, которые не умещаются в одно выражение или которые хочется переиспользовать.

Как написать предикат типа

Предикат типа имеет вид parameterName is Type и заменяет boolean в качестве возвращаемого типа. Сужение работает в обе стороны: true сужает до Type, а false убирает Type из объединения.

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

Если передать защитник в filter, получится правильно типизированный массив. Начиная с TypeScript 5.5 компилятор выводит предикат и из простых стрелочных функций, поэтому pets.filter((p) => p.kind === "cat") возвращает Cat[] без именованного защитника.

Тип предиката должен подходить к типу параметра: function f(x: string): x is number даёт ошибку TS2677, A type predicate's type must be assignable to its parameter's type.

Компилятор доверяет вашему защитнику

TypeScript проверяет, что защитник возвращает boolean. Он не проверяет, что этот boolean верен. Защитник, который возвращает true для неправильных значений, заставляет типы лгать, и программа падает во время выполнения без всякой ошибки компиляции.

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) бросает TypeError: Cannot read properties of undefined (reading 'toFixed') во время выполнения. Компилятор принял data.price как number, потому что так сказал защитник. Проверяйте каждое свойство, на которое опирается остальной код, и держите защитники маленькими, протестированными и рядом с типом, который они описывают.

Как проверить, что объект относится к типу

Это вопрос, который стоит за большинством собственных защитников: данные приходят как unknown (из JSON.parse, fetch, localStorage, сообщения), и нужно узнать, соответствуют ли они вашему интерфейсу. Рецепт:

1. typeof value === "object" && value !== null (объект, а не null).
2. "prop" in value для каждого обязательного свойства. Для unknown оператор in добавляет свойство в тип как unknown.
3. typeof value.prop === "..." (или вложенный защитник) для типа каждого свойства.
4. Array.isArray(value.items) && value.items.every(isItem) для массивов.

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

Для больших или глубоко вложенных форм писать такое вручную утомительно. Библиотеки схем вроде Zod или Valibot позволяют описать форму один раз и дают и проверку во время выполнения, и тип TypeScript.

Функции утверждения: asserts value is Type

Функция утверждения бросает исключение, если проверка не прошла, и обычно возвращает управление в остальных случаях. Её возвращаемый тип asserts value is Type (или asserts condition), и всё, что идёт после вызова, сужено без всякого 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
}

Одно правило часто сбивает с толку: функцию утверждения нужно вызывать через имя с явным типом. Стрелочная функция в const без аннотации, const check = (v: unknown): asserts v is string => {...}, даёт в месте вызова ошибку TS2775, Assertions require every name in the call target to be declared with an explicit type annotation. Используйте объявление function или аннотируйте константу типом функции.

Защитники, утверждения и приведения

Утверждение типа (as) меняет тип, ничего не проверяя. На границе, где данные приходят извне, защитник или функция утверждения это безопасный вариант той же идеи.

Защитники на основе this в классах

Метод может сужать объект, на котором он вызван, через this is Type. Это удобно в иерархиях классов:

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
}