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.