Оператор satisfies

Три инструмента на одном значении

Когда вы ловите себя на выборе между безопасностью типов и их точностью — остановитесь. Вопрос, который стоит задать: нужно ли, чтобы целевой тип протекал внутрь и управлял выводом, или достаточно проверки снаружи, оставляющей выведенный тип нетронутым?

Прогоните один и тот же объект через каждый инструмент и смотрите, что станет с его типом.

type Routes = Record<string, `/${string}`>;

// 1) Аннотация — валидирует, но РАСШИРЯЕТ до аннотированного типа
const a: Routes = { home: "/", profile: "/u/:id" };
a.home;
// ^? `/${string}`   — литерал "/" потерян; a.home теперь просто «строка пути»
// a.dashboard;      // нет ошибки — ключи Record<string, ...>, полнота не проверяется

// 2) as — хранит тип, который вы утверждаете, но НЕ делает реальной проверки
const b = { home: "/", dashboard: "oops" } as Routes;
//                     ^^^^^^^^ опечатка + невалидный путь, но `as` это заглушает
b.home;
// ^? `/${string}`   — тоже расширен, и баг проскользнул

// 3) satisfies — валидирует И сохраняет точный выведенный тип
const c = { home: "/", profile: "/u/:id" } satisfies Routes;
c.home;
// ^? "/"            — точный литерал сохранён
c.profile;
// ^? "/u/:id"
// const d = { home: "x" } satisfies Routes;
// Error: Type 'string' is not assignable to type `/${string}` — невалидный путь пойман

Аннотация расширяет: тип переменной становится Routes, поэтому a.home забывает, что был "/". Каст лжёт: as делает проверку присваиваемости лишь в одну сторону и подавляет ошибки лишних свойств и значений — dashboard: "oops" проходит. satisfies валидирует, не расширяя: значение проверяется против Routes, но переменная сохраняет свой выведенный тип { home: "/"; profile: "/u/:id" }, так что каждый литерал выживает.

И проверка полноты, и точные типы по каждому ключу

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

type Color = "red" | "green" | "blue";

const palette = {
  red: [255, 0, 0],
  green: [0, 255, 0],
  blue: [0, 0, 255],
} satisfies Record<Color, [number, number, number]>;

// Полнота: уберите ключ — и получите ошибку
// const p2 = { red: [255,0,0], green: [0,255,0] } satisfies Record<Color, [number,number,number]>;
// Error: Property 'blue' is missing.

palette.red;
// ^? [number, number, number]   — сохранён как кортеж, а не number[]
palette.red[0].toFixed(2);
// ok — элемент — `number`, доступен, потому что тип-кортеж выжил
const keys = Object.keys(palette);
// у значения по-прежнему точные ключи, поэтому нижестоящий код может на них опираться

С простой аннотацией const palette: Record<Color, ...> palette.red был бы расширен, и вы потеряли бы точность кортеж-против-массива и точный набор ключей. satisfies сохраняет оба: ограничение валидирует полноту и форму значений; выведенный тип хранит литералы и кортежи.

Ловушка: satisfies не даёт контекстный тип

Единственное место, где satisfies не может заменить аннотацию, — контекстная типизация. Аннотация на переменной протекает своим типом внутрь, давая неаннотированным параметрам функций их типы. satisfies проверяет только наружу, после того как значение уже выведено, поэтому он не засевает параметры.

type Handlers = { onClick: (e: MouseEvent) => void };

// Аннотация: тип протекает внутрь, поэтому `e` типизирован контекстно
const h1: Handlers = {
  onClick: (e) => { e.clientX; },   // e: MouseEvent — выведен из аннотации
};

// satisfies: проверка ПОСЛЕ вывода, поэтому `e` не получает контекстного типа
const h2 = {
  onClick: (e) => { e.clientX; },
  //         ^ Error: Parameter 'e' implicitly has an 'any' type.
} satisfies Handlers;

В h2 параметр стрелки e выводится до того, как satisfies запускает свою проверку, поэтому контекстно типизировать его нечем — при noImplicitAny это ошибка; вы должны сами аннотировать e: MouseEvent. Правило: берите аннотацию, когда нужно, чтобы целевой тип управлял выводом параметров колбэков; берите satisfies, когда хотите валидировать значение, сохранив его точный выведенный тип. Они дополняют друг друга, а не взаимозаменяемы.