O Operador satisfies (TS 4.9+): Validação Flexível sem Perder a Inferência de Tipos
Lançado no TypeScript 4.9, o operador satisfies solucionou um dos dilemas mais antigos e frustrantes da linguagem: como validar que um objeto segue rigorosamente um contrato sem apagar a inferência precisa dos seus tipos literais e propriedades específicas.
📑 Índice do Conteúdo
1. O Dilema Histórico: Validação vs. Inferência de Tipos
Antes do TypeScript 4.9, desenvolvedores de grandes projetos enfrentavam uma encruzilhada desconfortável sempre que precisavam modelar objetos de configuração flexíveis, temas ou mapas de rotas:
- Opção 1: Anotar o tipo explicitamente (
const tema: Tema = { ... }): O compilador valida que você não errou nenhuma propriedade obrigatória, mas alarga (widens) todos os tipos específicos para o tipo genérico do contrato. Você perde os tipos exatos e não consegue usar métodos nativos sem fazer type guards chatos. - Opção 2: Não anotar o tipo e deixar o TS inferir: O TypeScript mantém os tipos literais específicos de cada propriedade, mas você perde completamente a validação contra erros de digitação (typos) e chaves faltantes.
Veja o problema clássico acontecendo em uma paleta de cores de Design System:
type Cor = string | [r: number, g: number, b: number];
type NomeCor = "primaria" | "secundaria" | "fundo";
// CENÁRIO 1: Anotando o tipo explicitamente
const paletaAnotada: Record<NomeCor, Cor> = {
primaria: "#10b981",
secundaria: [16, 185, 129],
fundo: "#0f172a"
};
// ❌ ERRO DE COMPILAÇÃO:
// O compilador diz que "paletaAnotada.primaria" é string | [number, number, number].
// Logo, você NÃO pode chamar .toUpperCase() diretamente!
// paletaAnotada.primaria.toUpperCase(); // TS2339: Property 'toUpperCase' does not exist on type...
2. A Revolução do Operador satisfies
O operador satisfies permite perguntar ao compilador: “Este objeto atende ao contrato especificado à direita?”. Se a resposta for sim, o TypeScript valida a estrutura, mas preserva intacta a inferência exata e mais específica do valor atribuído à esquerda:
// CENÁRIO 2: Utilizando o operador satisfies do TypeScript 4.9+
const paletaPerfeita = {
primaria: "#10b981",
secundaria: [16, 185, 129],
fundo: "#0f172a"
} satisfies Record<NomeCor, Cor>;
// ✅ 1. O TypeScript sabe com 100% de precisão que "primaria" é uma STRING:
console.log(paletaPerfeita.primaria.toUpperCase()); // ___WZW_STR_0___ - Métodos de string liberados!
// ✅ 2. O TypeScript sabe que "secundaria" é um ARRAY de números:
const [r, g, b] = paletaPerfeita.secundaria; // Desestruturação de tupla permitida!
// ✅ 3. Validação estrita em ação: erros de digitação continuam sendo BARRADOS!
/*
const paletaInvalida = {
primaria: "#10b981",
secundaria: [16, 185, 129],
fundo: "#0f172a",
corInexistente: "#ffffff" // ❌ TS2353: Object literal may only specify known properties...
} satisfies Record<NomeCor, Cor>;
*/
3. Comparativo Definitivo: : Tipo vs. as Tipo vs. satisfies Tipo
Para nunca mais ter dúvidas sobre qual ferramenta utilizar em cada contexto, compare o comportamento das três abordagens:
| Critério | Anotação (: Tipo) |
Asserção (as Tipo) |
Operador (satisfies Tipo) |
|---|---|---|---|
| Validação do Contrato | ✅ Sim (Estrita) | ❌ Não (Bypassa checagens) | ✅ Sim (Estrita) |
| Inferência Específica | ❌ Perdida (Alargada para o tipo) | ❌ Forçada ao tipo assinalado | ✅ Preservada 100% |
| Detecção de Typos | ✅ Sim | ❌ Não | ✅ Sim |
| Segurança de Tipos | Alta | Baixa (Risco de mentir) | Máxima |
4. A Combinação Suprema: as const satisfies Contrato
E se você quiser unir o melhor de todos os mundos: congelamento profundo e imutabilidade total (as const) combinado com validação rigorosa de schema (satisfies)?
Essa combinação se tornou o padrão ouro da indústria para arquivos de configuração e dicionários estáticos:
interface ConfiguracaoRotas {
[rota: string]: {
titulo: string;
requerAutenticacao: boolean;
cargosPermitidos?: readonly ("admin" | "editor" | "aluno")[];
};
}
// Congelamento imutável + Validação de contrato sem perda de literais:
const MAPA_ROTAS = {
"/painel": {
titulo: "Painel de Controle",
requerAutenticacao: true,
cargosPermitidos: ["admin", "editor"]
},
"/perfil": {
titulo: "Meu Perfil",
requerAutenticacao: true
},
"/cursos": {
titulo: "Web Academy",
requerAutenticacao: false
}
} as const satisfies ConfiguracaoRotas;
// Benefício 1: O tipo de cada chave é um literal estrito imutável:
// MAPA_ROTAS["/painel"].titulo tem tipo literal "Painel de Controle" (não string genérico!)
// Benefício 2: Proteção total contra mutações acidentais:
// ❌ TS2540: Cannot assign to 'requerAutenticacao' because it is a read-only property.
// MAPA_ROTAS["/perfil"].requerAutenticacao = false;
5. Caso Prático de API: DTOs e Tipagem Segura de Respostas
Outro cenário clássico é a criação de payloads de resposta de APIs em que diferentes códigos HTTP retornam estruturas complementares, mas você quer autocompletar exato sem perder o tipo do status:
type RespostaApi = {
sucesso: boolean;
dados?: unknown;
erro?: string;
};
// Validando que os objetos cumprem RespostaApi sem perder os tipos reais dos dados:
const respostaUsuario = {
sucesso: true,
dados: {
id: "usr_99",
nome: "Fabiana",
permissoes: ["leitura", "gravacao"]
}
} satisfies RespostaApi;
// ✅ O IntelliSense sabe exatamente que "dados.nome" e "dados.permissoes" existem!
console.log(respostaUsuario.dados.nome);
respostaUsuario.dados.permissoes.map(p => console.log(p));
as Tipo para contornar uma perda de inferência após declarar const x: Tipo = ..., pare imediatamente! Substitua a anotação tradicional por satisfies Tipo. Você manterá 100% da validação de segurança e nunca mais precisará fazer casting forçado.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE