Оператор satisfies в TypeScript: против аннотации и as

value satisfies Type во время компиляции проверяет, что value соответствует Type, а затем оставляет собственный, более точный тип значения в покое. Аннотация заменила бы этот точный тип на Type; satisfies проверяет без расширения.

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

satisfies всё равно выполняет проверку: пропущенный цвет, ключ с опечаткой вроде bleu или значение вроде true дают ошибку компиляции на этой строке. Он существует начиная с TypeScript 4.9 и, как любая аннотация типа, удаляется из сгенерированного JavaScript.

Какую проблему решает satisfies

С аннотацией типа тип переменной и есть аннотация. Компилятор забывает, что видел в литерале. Здесь та же палитра аннотирована, и TypeScript больше не знает, что green это строка:

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

Компилятор сообщает:

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

До TypeScript 4.9 выбор был такой: аннотировать и везде сужать вручную (typeof palette.green === "string") или отказаться от аннотации и потерять проверку. satisfies даёт и то, и другое. Замените : Record<ColorName, Color> на satisfies Record<ColorName, Color> после закрывающей скобки, и код запустится.

satisfies, аннотация типа и as

Один и тот же объект настроек, записанный тремя способами:

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

as пропустил отсутствующий lang, и asserted.lang во время выполнения равен undefined, хотя тип говорит string. Уберите lang из двух других строк, и обе упадут с TS2741, Property 'lang' is missing in type ....

Простое правило: аннотируйте, когда хотите, чтобы переменная имела объявленный тип (значение, которое будет переприсваиваться, публичный API), и используйте satisfies, когда нужна проверка, но собственный тип значения полезнее.

Ловля ошибок в объектных литералах

satisfies выполняет полную проверку присваиваемости, включая проверку лишних свойств, поэтому опечатки в ключах дают ошибки:

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

Проверка также даёт литералу контекстный тип, как это делает аннотация. Это важно в двух отношениях. Строковые литералы сохраняются как литеральные типы, когда их ожидает целевой тип: у { path: "/", method: "GET" } satisfies Route будет method: "GET", тогда как тот же объект без аннотации вывел бы method: string. А параметры колбэков выводятся из целевого типа:

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

Ключи Record остаются известными

Частое применение это таблица поиска. С аннотацией Record<string, T> любая строка считается допустимым ключом, и опечатка компилируется, возвращая undefined во время выполнения. С satisfies значения по-прежнему проверяются по T, но тип переменной перечисляет ровно те ключи, которые вы написали:

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints полезен только потому, что ключи сохранились. С аннотацией это был бы просто string.

Чтобы потребовать фиксированный набор ключей, используйте satisfies с Record по объединению: satisfies Record<"dev" | "prod", string> сообщает об отсутствующем prod ошибкой TS2741, а о неизвестном staging ошибкой TS2353.

as const satisfies

as const и satisfies сочетаются. Пишите as const первым: он делает значение глубоко readonly с литеральными типами, а затем satisfies проверяет это точное значение.

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

Каждый маршрут проверяется по Route (method: "PUT" дал бы ошибку), а кортеж литеральных типов остаётся доступен, поэтому Path это объединение реальных путей. В качестве цели используйте readonly Route[] (или ReadonlyArray<Route>), потому что массив с as const доступен только для чтения.

Объекты конфигурации

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

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

Забудьте запись production, сделайте опечатку в logLevel или напишите logLevel: "verbose", и компилятор укажет точную строку. Тот же приём подходит для файлов *.config.ts: export default { ... } satisfies SomeConfig проверяет весь файл, а экспортируемый объект сохраняет свои литеральные значения.

Когда не стоит использовать satisfies

• Переменная будет переприсваиваться. let cfg = { port: 3000 } satisfies { port: number | string } даёт cfg тип { port: number }, поэтому последующее cfg = { port: "80" } падает (TS2322). Переменные, которые вы собираетесь менять, аннотируйте.
• Вам нужен именно объявленный тип. Для возвращаемого значения функции или экспортируемой константы, которая входит в API, тип аннотации и есть контракт, а утечка точного литерального типа может сделать последующие изменения ломающими.
• Значение не литерал. satisfies раскрывается на объектных и массивных литералах. Для переменной или результата вызова это обычная проверка присваиваемости, которую уже даёт аннотация.