Что такое оператор `satisfies` в TypeScript?

Оператор satisfies в TypeScript

Оператор satisfies появился в TypeScript 4.9 и решает классическую проблему: как одновременно получить проверку типа и сохранить точный выведенный тип.

Проблема без satisfies

При явной аннотации типа TypeScript расширяет тип переменной до указанного, теряя точную информацию:

type Colors = 'red' | 'green' | 'blue';
type Palette = Record<Colors, string | [number, number, number]>;

// Явная аннотация — тип каждого значения становится string | [number, number, number]
const palette: Palette = {
  red: [255, 0, 0],
  green: '#00ff00',
  blue: [0, 0, 255],
};

// Ошибка: TypeScript не знает, что red — это массив, а не строка
const redChannel = palette.red.toUpperCase(); // нет ошибки, но упадёт в рантайме

Решение с satisfies

const palette = {
  red: [255, 0, 0],
  green: '#00ff00',
  blue: [0, 0, 255],
} satisfies Palette;

// TypeScript знает точный тип каждого поля
const redChannel = palette.red[0];          // OK — number
const greenUpper = palette.green.toUpperCase(); // OK — string

// Но проверка типа всё равно работает
const wrong = {
  red: [255, 0, 0],
  green: '#00ff00',
  // Ошибка: отсутствует обязательное поле blue
} satisfies Palette;

Ключевые отличия от аннотации типа

Практические сценарии

1. Конфигурационные объекты:

type Config = {
  port: number;
  host: string;
  flags: Record<string, boolean>;
};

const config = {
  port: 3000,
  host: 'localhost',
  flags: { debug: true, verbose: false },
} satisfies Config;

// TypeScript точно знает тип flags.debug — boolean, не unknown
const isDebug: boolean = config.flags.debug;

2. Сужение union-типов в значениях:

type Route = {
  path: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
};

const routes = [
  { path: '/users', method: 'GET' },
  { path: '/users', method: 'POST' },
] satisfies Route[];

// method выведен как 'GET' | 'POST', а не просто string

Важный нюанс

satisfies — это операция проверки на этапе компиляции, она не влияет на рантайм-поведение и не генерирует никакого JavaScript-кода. Это чисто статический инструмент TypeScript.