Полное руководство по оператору satisfies в TypeScript 5.5 — практические советы для максимальной типобезопасности

Вводная часть

• Оператор satisfies позволяет проверить тип без его изменения
• Отличие от явных аннотаций типов: satisfies сохраняет более точный выведенный тип
• Идеален для объектов-конфигураций, палитр цветов, словарей и роутов
• TypeScript 5.5 расширяет возможности satisfies с улучшенным выводом типов

---

Что такое оператор satisfies?

Оператор satisfies, введённый в TypeScript 4.9, позволяет проверить, соответствует ли значение определённому типу, не сужая при этом тип самого значения.

Проблема, которую он решает

Представьте, что у вас есть палитра цветов:

` ypescript // Без satisfies const palette: Record = { red: [255, 0, 0], green: "#00ff00", blue: [0, 0, 255], };

// TypeScript думает, что palette.red — это string | number[] // Метод .map() недоступен без дополнительной проверки! palette.red.map(v => v * 2); // Ошибка: Property 'map' does not exist on type 'string | number[]' `

` ypescript // С satisfies const palette = { red: [255, 0, 0], green: "#00ff00", blue: [0, 0, 255], } satisfies Record;

// TypeScript знает, что palette.red — это number[] palette.red.map(v => v * 2); // Работает! palette.green.toUpperCase(); // Тоже работает — TypeScript знает, что это string `

---

Синтаксис и базовые примеры

Базовый синтаксис

ypescript const value = expression satisfies Type;

Ключевое различие:

• const value: Type = expression — тип alue становится Type
• const value = expression satisfies Type — тип alue остаётся выведенным, но проверяется на соответствие Type

Пример 1: Конфигурация роутов

` ypescript type Route = { path: string; component: string; exact?: boolean; };

// С явной аннотацией — теряем точность const routes: Route[] = [ { path: "/", component: "Home", exact: true }, { path: "/about", component: "About" }, ];

// С satisfies — сохраняем и типобезопасность, и точность const routes = [ { path: "/", component: "Home", exact: true }, { path: "/about", component: "About" }, ] satisfies Route[];

// TypeScript знает, что routes[0].exact — это boolean (а не boolean | undefined) const isExact: boolean = routes[0].exact; // Работает без ошибок! `

Пример 2: Словарь переводов

` ypescript type TranslationDict = { [key: string]: string | { text: string; count: number }; };

const translations = { hello: "Привет", items: { text: "предметов", count: 5 }, goodbye: "До свидания", } satisfies TranslationDict;

// TypeScript точно знает типы: translations.hello.toUpperCase(); // Работает: TypeScript знает, что это string translations.items.count; // Работает: TypeScript знает структуру объекта `

---

Улучшения в TypeScript 5.5

Улучшенный вывод типов для satisfies

TypeScript 5.5 улучшил работу satisfies с условными типами и дженериками:

` ypescript // TypeScript 5.5: работает более предсказуемо с дженериками function createConfig(config: T satisfies { debug?: boolean }): T { return config; }

const result = createConfig({ debug: true, apiUrl: "https://api.example.com", timeout: 3000, });

// result сохраняет точный тип { debug: boolean; apiUrl: string; timeout: number } result.apiUrl.startsWith("https"); // TypeScript знает, что apiUrl — это string `

satisfies с as const

Мощная комбинация для создания точных типов только для чтения:

` ypescript const CONFIG = { theme: "dark", language: "ru", features: { analytics: true, darkMode: true, }, } as const satisfies { theme: "light" | "dark"; language: string; features: Record; };

// CONFIG.theme — это "dark" (не просто string) // Изменение CONFIG.theme вызовет ошибку компиляции `

---

Практические сценарии применения

Сценарий 1: Конфигурация ESLint/Prettier

` ypescript import type { Linter } from "eslint";

const eslintConfig = { env: { browser: true, es2021: true, node: true, }, extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"], rules: { "no-console": "warn", "@typescript-eslint/explicit-function-return-type": "off", eqeqeq: ["error", "always"], }, } satisfies Linter.Config;

// Все поля проверены, но тип остаётся точным eslintConfig.rules["no-console"]; // TypeScript знает, что это "warn" `

Сценарий 2: Определение цветов темы

` ypescript type ColorScale = { 50: string; 100: string; 500: string; 900: string; };

const colors = { primary: { 50: "#eff6ff", 100: "#dbeafe", 500: "#3b82f6", 900: "#1e3a8a", }, secondary: { 50: "#f5f3ff", 100: "#ede9fe", 500: "#8b5cf6", 900: "#4c1d95", }, } satisfies Record;

// TypeScript знает структуру каждого цвета const primaryLight: string = colors.primary[50]; // Работает! `

Сценарий 3: API-эндпоинты

` ypescript type ApiEndpoint = { method: "GET" | "POST" | "PUT" | "DELETE"; path: string; auth: boolean; };

const endpoints = { getUsers: { method: "GET", path: "/users", auth: true }, createUser: { method: "POST", path: "/users", auth: true }, publicHealth: { method: "GET", path: "/health", auth: false }, } satisfies Record;

// Точные типы сохранены: endpoints.getUsers.method; // "GET" (не просто string) endpoints.publicHealth.auth; // false (не просто boolean) `

---

satisfies vs другие подходы

Сравнение с явной аннотацией типа

` ypescript type Config = { host: string; port: number };

// Явная аннотация: теряем точность const config1: Config = { host: "localhost", port: 3000 }; // config1.port — это number, а не 3000

// satisfies: сохраняем точность const config2 = { host: "localhost", port: 3000 } satisfies Config; // config2.port — это 3000 (литеральный тип) `

Сравнение с as

` ypescript // as: принудительное приведение типа, обходит проверки const bad = {} as Config; // Нет проверки! TypeScript не видит ошибок

// satisfies: строгая проверка без потери информации const good = {} satisfies Config; // Ошибка: отсутствуют обязательные поля `

---

Вопросы и ответы

В чём разница между satisfies и явной аннотацией типа?

Явная аннотация (const x: Type) расширяет тип до Type, теряя точность. satisfies проверяет соответствие, но сохраняет более узкий выведенный тип.

Можно ли использовать satisfies с дженериками?

Да! TypeScript 5.5 улучшил поддержку satisfies с дженериками, делая её более предсказуемой.

Когда использовать satisfies, а когда — явную аннотацию?

Используйте satisfies, когда хотите проверить структуру, но сохранить точные литеральные типы. Используйте явную аннотацию, когда намеренно хотите расширить тип.

Работает ли satisfies со строгим режимом TypeScript?

Да, satisfies работает независимо от режима строгости, но наибольшую пользу приносит именно в строгом режиме.

Поддерживают ли IDE оператор satisfies?

VS Code с TypeScript 4.9+ полностью поддерживает автодополнение и проверку типов для satisfies.

Влияет ли satisfies на производительность сборки?

satisfies — это чисто компиляторная конструкция и не влияет на производительность во время выполнения. На скорость сборки влияет минимально.

---

Итог

Оператор satisfies в TypeScript — мощный инструмент для балансирования между строгостью типов и гибкостью кода. Вместо выбора между «точный тип» и «проверка соответствия» satisfies даёт оба преимущества одновременно.

TypeScript 5.5 продолжает улучшать работу satisfies с дженериками и условными типами, делая его ещё более полезным в реальных проектах. Если вы ещё не используете satisfies в своём коде, пришло время начать.