any vs unknown em TypeScript: diferenças e quando usar

any e unknown aceitam qualquer valor. A diferença está no que você pode fazer com o valor depois: any deixa fazer qualquer coisa e não verifica nada, enquanto unknown não deixa fazer quase nada até você provar o que o valor é.

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

Sem a linha @ts-expect-error, u.toUpperCase() é o erro de compilação TS18046. A verificação com typeof estreita u para string, e dentro desse bloco todos os métodos de string ficam disponíveis.

any vs unknown em resumo

Em termos de teoria de tipos, unknown é o top type: todo tipo pode ser atribuído a ele, e ele só pode ser atribuído a unknown e any. O any é uma válvula de escape atribuível nos dois sentidos, a tudo exceto never.

any desliga a verificação de tipos

Um valor com tipo any recebe confiança cega. O compilador aceita erros de digitação, tipos errados e propriedades que faltam, e os erros aparecem em tempo de execução.

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

A saída mostra o problema: uma variável anotada como number guarda uma string, e a última linha lança Cannot read properties of undefined (reading 'city'). O any também se espalha. user.name é any, então qualquer valor calculado a partir dele é any, e um único valor sem tipo pode desligar a verificação longe de onde entrou.

unknown obriga a verificar antes

Com unknown, o compilador recusa toda operação até o código fazer o narrowing do valor. O narrowing usa verificações comuns de JavaScript, e dentro de cada ramo o valor tem o tipo verificado.

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

A verificação value === null precisa vir antes da verificação de objeto porque typeof null é "object". Depois de "id" in value, o TypeScript sabe que o objeto tem uma propriedade id, com tipo unknown, já que nada diz o que ela guarda. String() a transforma em texto de forma explícita; para usá-la como número, você a verificaria antes com typeof.

Você também pode pular a verificação com uma assertion, value as string, e o compilador aceita. Isso é uma promessa sem nenhuma verificação em tempo de execução por trás, então prefira uma verificação de verdade; veja type assertions.

Validando JSON com unknown

JSON.parse é declarado como retornando any, então o resultado dele desliga a verificação em silêncio. Anote o resultado como unknown e escreva um type guard que verifica o formato antes que o resto do código confie nele.

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

A primeira entrada imprime dark at 14px, a segunda é rejeitada porque falta fontSize. Com any, a segunda entrada teria passado como um Settings com fontSize undefined. Para schemas grandes, uma biblioteca de validação faz o mesmo trabalho e deriva o tipo para você.

noImplicitAny

O any não vem só de alguém escrevê-lo. Um parâmetro sem anotação e sem contexto para inferir também seria any. A opção noImplicitAny, que o strict liga, aponta isso como erro:

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

A correção é uma anotação, function double(x: number). Escrever x: any explicitamente também compila, e é essa a ideia: o any fica visível no código e pode ser procurado e revisado.

Por onde o any ainda entra

Mesmo com strict, estes casos produzem any sem que a palavra apareça no seu código:

A variável do catch é unknown com strict porque qualquer coisa pode ser lançada, não só objetos Error. Faça o narrowing com e instanceof Error antes de ler e.message.

Quando o any é aceitável

O any não é proibido, mas cada um é um ponto que o compilador deixa de proteger. Usos razoáveis:

• Migrar uma base de código JavaScript, em que o any marca o que ainda não foi tipado.
• Código que o sistema de tipos não consegue expressar bem, mantido pequeno e atrás de uma assinatura de função tipada.
• Código de teste que passa dados inválidos de propósito.

Para todo o resto, unknown cobre o mesmo caso de "não sei esse tipo" mantendo as verificações. Muitos times impõem isso com a regra de lint @typescript-eslint/no-explicit-any. Um tipo relacionado, Record<string, unknown>, é a escolha usual para "algum objeto com valores desconhecidos".