re:re:actable
Урок 023 минуты чтения

Type guard: встроенные проверки и функции-предикаты value is T

На этой странице
Кратко

Type guard — проверка, после которой TypeScript сужает тип. Встроенные guards — typeof, instanceof, in, Array.isArray, сравнения. Пользовательский type guard — функция, возвращающая предикат value is T: если она вернула true, в этой ветке значение считается типом T. TypeScript не проверяет правильность тела такой функции — ошибка в реализации даст ложное сужение.

Вопрос

Что такое type guard? Как написать свою type guard function и чем она отличается от функции, возвращающей boolean?

Встроенные type guards

function handle(value: string | number | Date | string[]) {
  if (typeof value === "number") value.toFixed(2);
  else if (value instanceof Date) value.toISOString();
  else if (Array.isArray(value)) value.join(", ");
  else value.toUpperCase();
}
 
type Cat = { meow(): void };
type Dog = { bark(): void };
 
function speak(pet: Cat | Dog) {
  if ("meow" in pet) pet.meow();
  else pet.bark();
}

Пользовательский type guard

type User = { id: number; name: string };
 
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    typeof value.id === "number" &&
    "name" in value &&
    typeof value.name === "string"
  );
}
 
const data: unknown = await response.json();
if (isUser(data)) {
  data.name; // User
}

Предикат или boolean

function isStringBool(x: unknown): boolean {
  return typeof x === "string";
}
 
function isString(x: unknown): x is string {
  return typeof x === "string";
}
 
const v: unknown = "a";
if (isStringBool(v)) v.toUpperCase(); // ошибка: v всё еще unknown
if (isString(v)) v.toUpperCase();     // OK

С TS 5.5 TypeScript сам выводит предикат для простых функций вроде (x) => typeof x === "string".

Фильтрация массивов

const items: (User | null)[] = [anna, null, ivan];
 
const users = items.filter((item): item is User => item !== null); // User[]
 
const isDefined = <T,>(value: T): value is NonNullable<T> => value != null;
const ids = [1, undefined, 3].filter(isDefined); // number[]

Guards для discriminated union и ошибок

type Shape = { kind: "circle"; r: number } | { kind: "square"; size: number };
 
const isCircle = (s: Shape): s is Extract<Shape, { kind: "circle" }> => s.kind === "circle";
 
function isApiError(error: unknown): error is { status: number; message: string } {
  return typeof error === "object" && error !== null && "status" in error;
}

Опасность ложного guard

function isAdmin(user: User): user is User & { role: "admin" } {
  return true; // компилятор поверит — и пропустит не-админов
}

Для данных извне надежнее схемы валидации: UserSchema.safeParse(data) из Zod проверяет структуру и дает тип.

Что важно помнить

  • Предикат x is T должен ссылаться на параметр функции.
  • Если guard вернул false, в ветке else тип сужается до «исключения» T из исходного union.
  • Методы класса тоже могут быть guards: isLoaded(): this is LoadedState.
  • Не путайте type guard (x is T) и assertion function (asserts x is T): вторая бросает ошибку вместо возврата false.

Мини-шпаргалка

  • Встроенные: typeof, instanceof, in, Array.isArray, ===.
  • Свой guard: function isX(v: unknown): v is X.
  • Предикат сужает тип, boolean — нет.
  • filter((x): x is T => ...) — сужение массива.
  • TS не проверяет корректность guard — для внешних данных используйте схемы.

Документация

TypeScript Handbook: Using type predicates, TypeScript 5.5: Inferred Type Predicates.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам