as em TypeScript: type assertions e casting explicados

value as Type é uma type assertion: diz ao TypeScript para tratar value como Type. As pessoas chamam de cast, mas é só uma instrução ao compilador. Ela é apagada da saída JavaScript, não converte nada e não verifica nada em tempo de execução.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

Esse é o uso típico: você sabe mais sobre um valor do que o compilador consegue saber (aqui, o formato de um JSON) e diz isso a ele. Se você estiver errado, nada avisa. As próximas seções mostram o que isso significa e quando uma verificação em tempo de execução é a escolha melhor.

as e a sintaxe com sinais de menor e maior

Existem duas grafias para a mesma assertion:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

A forma com sinais de menor e maior não é permitida em arquivos .tsx, em que <string> seria lido como uma tag JSX. Use as em todo lugar e a questão nem aparece. As assertions têm precedência baixa, então envolva-as em parênteses quando continuar a expressão: (value as string).length.

Assertions não convertem valores

Esta é a parte que causa bugs de verdade. Uma assertion muda o que o compilador acredita sobre um valor, não o valor em si:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

O compilador acredita que asserted é um number, então asserted + 1 passa na verificação como aritmética. Em tempo de execução ele continua sendo a string "42", e o JavaScript concatena. Para mudar o tipo de um valor, converta-o: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). A página sobre converter string para number compara as funções de conversão.

O que o compilador permite

O as não é ilimitado. O TypeScript permite x as T quando um tipo pode ser atribuído ao outro: ampliar ("a" as string, dog as Animal) e estreitar (animal as Dog, unknown as User) são aceitos. Quando os tipos não se sobrepõem de jeito nenhum, ele recusa:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

O compilador mostra index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. A própria mensagem indica a válvula de escape: input as unknown as number. Essa assertion dupla compila, e é tão errada em tempo de execução quanto o exemplo acima. Quando você sentir necessidade dela, a correção certa normalmente é uma conversão (Number(input)) ou um tipo diferente.

A regra de sobreposição é frouxa para objetos. Um objeto literal que tem algumas das propriedades é aceito, e é assim que o as deixa passar em silêncio objetos incompletos:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

Uma anotação (const draft: User = { name: "Ada" }) ou satisfies User apontaria o email faltando (TS2741). Use as em um objeto literal só quando você realmente pretende completá-lo depois, e prefira montar o objeto completo.

as const é diferente

as const parece uma assertion, mas faz o contrário de afrouxar: torna um literal o mais estreito possível. Strings continuam literal types, arrays viram tuplas readonly e propriedades de objeto viram readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

Ele é seguro, porque descreve o literal exatamente, em vez de afirmar algo que o compilador não enxerga. (O sizes as readonly string[] dentro de isSize é uma assertion de ampliação, também segura: deixa o includes aceitar qualquer string.) Veja literal types para mais detalhes.

Quando um type guard é a ferramenta melhor

O as é uma afirmação; um type guard é uma verificação. Em uma fronteira em que os dados vêm de fora do seu código (JSON, fetch, localStorage, entrada do usuário, uma mensagem), a afirmação pode ser falsa, e uma assertion transforma um erro claro na fronteira em um erro confuso em outro lugar.

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

Um guia aproximado para as ferramentas que se parecem:

Sobram dois bons usos para o as: estreitar algo que o compilador não consegue acompanhar (uma entrada de Map que você definiu duas linhas antes, um valor de uma biblioteca sem tipos) e código de teste que monta fixtures parciais. Mantenha-os pequenos e perto do lugar em que você sabe que a afirmação é verdadeira.