Operador satisfies em TypeScript: vs anotação de tipo e as

value satisfies Type verifica em tempo de compilação se value corresponde a Type, e depois deixa em paz o tipo próprio do valor, que é mais preciso. Uma anotação substituiria esse tipo preciso por Type; o satisfies valida sem alargar.

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])

O satisfies continua fazendo a verificação: uma cor faltando, uma chave digitada errado como bleu ou um valor como true gera erro de compilação naquela linha. Ele existe desde o TypeScript 4.9 e, como toda anotação de tipo, é removido do JavaScript gerado.

O problema que o satisfies resolve

Com uma anotação de tipo, o tipo da variável é a anotação. O compilador esquece o que viu no literal. Aqui a mesma paleta é anotada em vez disso, e agora o TypeScript não sabe mais que green é uma string:

// 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());

O compilador mostra:

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

Antes do TypeScript 4.9 as opções eram: anotar e fazer narrowing à mão em todo lugar (typeof palette.green === "string"), ou dispensar a anotação e perder a verificação. O satisfies dá as duas coisas. Troque : Record<ColorName, Color> por satisfies Record<ColorName, Color> depois da chave de fechamento e o código roda.

satisfies vs anotação de tipo vs as

O mesmo objeto de configurações, escrito de três jeitos:

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

O as deixou passar o lang que faltava, e asserted.lang é undefined em tempo de execução enquanto o tipo dele diz string. Remova lang das outras duas linhas e as duas falham com TS2741, Property 'lang' is missing in type ....

Regra prática: anote quando você quer que a variável tenha o tipo declarado (um valor que você vai reatribuir, uma API pública), e use satisfies quando você quer uma verificação, mas o tipo próprio do valor é mais útil.

Pegando erros em objetos literais

O satisfies faz a verificação completa de compatibilidade, incluindo a verificação de propriedades extras, então erros de digitação em chaves são erros:

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'?

A verificação também dá ao literal um tipo contextual, como faz uma anotação. Isso importa de dois jeitos. Literais de string são mantidos como literal types quando o tipo de destino os espera: { path: "/", method: "GET" } satisfies Route tem method: "GET", enquanto o mesmo objeto sem anotação inferiria method: string. E os parâmetros de callbacks são inferidos a partir do tipo de destino:

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

As chaves de um Record continuam conhecidas

Um uso comum é uma tabela de consulta. Anotada como Record<string, T>, toda string é uma chave válida e um erro de digitação compila, retornando undefined em tempo de execução. Com satisfies, os valores continuam sendo verificados contra T, mas o tipo da variável lista exatamente as chaves que você escreveu:

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 só é útil porque as chaves sobreviveram. Com a anotação seria apenas string.

Para exigir um conjunto fixo de chaves, use satisfies com um Record sobre uma union: satisfies Record<"dev" | "prod", string> aponta um prod faltando com TS2741 e um staging desconhecido com TS2353.

as const satisfies

as const e satisfies se combinam. Escreva o as const primeiro: ele deixa o valor readonly em todos os níveis com literal types, e depois o satisfies verifica esse valor exato.

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' ]

Cada rota é verificada contra Route (um method: "PUT" seria erro), e a tupla de literal types continua disponível, então Path é uma union dos caminhos reais. Use readonly Route[] (ou ReadonlyArray<Route>) como destino, já que um array as const é readonly.

Objetos de configuração

Configuração é onde o satisfies mostra seu valor: o formato precisa estar certo, e o código em outros lugares quer os valores precisos.

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

Esqueça a entrada production, erre a grafia de logLevel ou escreva logLevel: "verbose" e o compilador aponta a linha exata. O mesmo padrão serve para arquivos *.config.ts: export default { ... } satisfies SomeConfig verifica o arquivo inteiro enquanto o objeto exportado mantém os valores literais.

Quando não usar satisfies

• A variável vai ser reatribuída. let cfg = { port: 3000 } satisfies { port: number | string } dá a cfg o tipo { port: number }, então um cfg = { port: "80" } depois falha (TS2322). Anote as variáveis que você pretende mudar.
• Você quer o tipo declarado de propósito. Para o valor de retorno de uma função ou uma constante exportada que faz parte de uma API, o tipo da anotação é o contrato, e expor o literal type exato pode tornar mudanças futuras incompatíveis.
• O valor não é um literal. O satisfies brilha em objetos e arrays literais. Em uma variável ou no resultado de uma chamada, ele é uma simples verificação de compatibilidade, que uma anotação já oferece.