Variables

As regras de const, let e valor que não muda depois de atribuído vêm do JavaScript e continuam as mesmas. O que o TypeScript acrescenta é a decisão de tipo: quando anotar, quando deixar a type inference (inferência de tipo, o compilador deduzindo o tipo a partir do valor) trabalhar sozinha, e como usar as const, satisfies e unknown para o contrato não abrir buraco.

Inferência é o compilador descobrir o tipo sozinho, olhando para o valor que você atribuiu. Quando você escreve const userName = "Alice", ninguém disse ao TypeScript que userName é uma string. Ele leu o valor "Alice", concluiu que só pode ser uma string, e passou a tratar a variável assim daí em diante. A partir desse momento userName.toUpperCase() é aceito, e userName * 2 é acusado como erro, exatamente como se o tipo estivesse escrito na declaração.

Isso vale para o resto da linguagem, e não só para variáveis. O retorno de uma função é inferido a partir do que ela devolve; o tipo de um item dentro de um map é inferido a partir do array; o tipo de um objeto é inferido campo a campo. Escrever tipo à mão é a exceção, reservada para os casos em que não existe valor de onde inferir, ou em que o tipo inferido é mais amplo do que se quer.

Vale saber o limite da inferência: ela olha o valor daquele momento, e nada mais. Um array vazio não tem elemento de onde tirar o tipo, uma variável declarada sem valor não tem valor nenhum, e uma resposta que chegou pela rede é um unknown que o compilador não tem como adivinhar. Nesses três casos a anotação deixa de ser redundância e vira a única fonte de informação.

O TypeScript deriva o tipo a partir do valor atribuído. Escrever const userName: string = "Alice" repete no tipo o que o valor já mostra, e o leitor passa por duas informações para receber uma. A anotação vale quando ela acrescenta algo que o valor não diz.

const userName: string = "Alice";
const isActive: boolean = true;
const MAX_RETRIES: number = 3;
const orders: Order[] = [];

const userName = "Alice";
const isActive = true;
const MAX_RETRIES = 3;
const orders: Order[] = []; // anotação necessária: array vazio não tem tipo inferível

A inferência precisa de um valor inicial para funcionar. Sem ele, o compilador não tem de onde tirar o tipo: uma variável declarada vazia vira any, e um array vazio vira never[], que não aceita nenhum elemento depois. Nos dois casos a anotação é o que informa o tipo.

let currentUser; // any: sem tipo, sem proteção
const results = []; // never[]: TypeScript não sabe o tipo dos elementos

let currentUser: User | null = null;
const results: Order[] = [];

any desliga a checagem de tipos naquela variável, e o efeito atravessa tudo que sai dela: data.user.name compila mesmo quando a resposta não tem user, e o erro só aparece em runtime, no navegador do usuário. unknown diz a mesma coisa (o valor chegou de fora e não se sabe o que é) sem abrir mão da checagem: para usar o valor, é preciso primeiro provar ao compilador o que ele é.

async function fetchExternalData(): Promise<any> {
  const response = await fetch(apiUrl);
  return response.json(); // qualquer coisa pode sair daqui sem aviso
}

const data = await fetchExternalData();
data.user.name; // TypeScript aceita, mas pode explodir em runtime

async function fetchExternalData(): Promise<unknown> {
  const response = await fetch(apiUrl);
  return response.json();
}

const raw = await fetchExternalData();
if (!isApiResponse(raw)) throw new ValidationError({ message: "Unexpected response shape." });

const data = raw; // narrowado para ApiResponse: seguro usar

Sem as const, o compilador vê pending: "pending" e infere string, porque supõe que o campo pode receber outra string depois. O tipo aceita qualquer string, e a restrição que o objeto parecia declarar não existe. Com as const, cada valor vira o literal exato ("pending", e não string), e o objeto inteiro passa a ser somente leitura. É o que permite derivar dele um union type com os valores válidos, o padrão que substitui o enum.

const ORDER_STATUS = {
  pending: "pending",
  approved: "approved",
  cancelled: "cancelled",
};
// tipo inferido: { pending: string; approved: string; cancelled: string }
// ORDER_STATUS.pending é string: qualquer string passa

function updateStatus(status: string) { /* ... */ } // sem restrição real

const ORDER_STATUS = {
  pending: "pending",
  approved: "approved",
  cancelled: "cancelled",
} as const;

type OrderStatus = typeof ORDER_STATUS[keyof typeof ORDER_STATUS];
// OrderStatus = "pending" | "approved" | "cancelled"

function updateStatus(status: OrderStatus) { /* ... */ } // só aceita os valores válidos

Anotar const createOrder: RouteConfig faz o compilador tratar o objeto como um RouteConfig qualquer, e createOrder.method volta a ser o union inteiro ("GET" | "POST" | "PUT" | "DELETE"). A informação de que ali dentro o método é "POST" se perde na anotação.

satisfies faz a mesma conferência (o objeto cumpre o contrato? falta campo? sobra campo?) e mantém o tipo que foi inferido do valor. createOrder.method continua sendo "POST".

interface RouteConfig {
  path: string;
  method: "GET" | "POST" | "PUT" | "DELETE";
}

const createOrder: RouteConfig = {
  path: "/orders",
  method: "POST",
};

createOrder.method; // tipo: "GET" | "POST" | "PUT" | "DELETE", perde a especificidade

const createOrder = {
  path: "/orders",
  method: "POST",
} satisfies RouteConfig;

createOrder.method; // tipo: "POST", literal preservado

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.