Inferência de tipos em TypeScript: quando anotar e quando não

Inferência de tipos é o TypeScript deduzindo um tipo que você não escreveu. Inicialize uma variável e ela assume o tipo do valor; retorne um valor de uma função e o tipo de retorno vem junto. A maior parte do código TypeScript tem bem menos anotações do que as pessoas imaginam.

let count = 0;            // number
let language = "TypeScript"; // string
let tags = ["ts", "js"];  // string[]
let user = { name: "Ada", age: 36 }; // { name: string; age: number }

function area(w: number, h: number) {
    return w * h;          // return type inferred as number
}

const size = area(3, 4);  // number
console.log(count, language, tags, user, size);

// The inferred types are enforced like written ones:
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
count = "one";

Os comentários mostram o que o editor exibe quando você passa o mouse sobre cada nome. A última linha é um erro de compilação (TS2322), mesmo que count nunca tenha sido anotado; // @ts-expect-error marca o erro como esperado para que o resto do bloco rode.

let vs const: alargamento de literais

Um const nunca muda, então o TypeScript dá a ele o tipo mais estreito: o próprio valor literal. Um let recebe o tipo mais amplo, porque pode ser reatribuído depois.

let a = "left";    // string
const b = "left";  // "left"
let c = 42;        // number
const d = 42;      // 42
const e = true;    // true

Isso importa quando uma função aceita só certos valores:

// This does not compile: `let` widened "left" to string.
function move(direction: "left" | "right") {
    console.log("moving", direction);
}

let dir = "left";
move(dir);

const fixed = "left";
move(fixed); // fine: fixed has type "left"

index.ts(7,6): error TS2345: Argument of type 'string' is not assignable to parameter of type '"left" | "right"'.

Corrija com const ou anotando a variável: let dir: "left" | "right" = "left". Os tipos literais têm sua própria página, tipos literais.

Objetos e arrays alargam seus membros

As propriedades de um objeto literal são mutáveis, então elas se alargam como let, mesmo quando o próprio objeto é const. Os elementos de arrays fazem o mesmo. as const torna tudo readonly e mantém os tipos literais.

const config = { mode: "dark", retries: 3 };
// config: { mode: string; retries: number }
config.mode = "light"; // allowed: mode is string

const frozen = { mode: "dark", retries: 3 } as const;
// frozen: { readonly mode: "dark"; readonly retries: 3 }

const sizes = ["s", "m", "l"];            // string[]
const fixedSizes = ["s", "m", "l"] as const; // readonly ["s", "m", "l"]

console.log(config.mode, frozen.mode, sizes.length, fixedSizes[0]);

Inferência do tipo de retorno

O tipo de retorno de uma função é inferido a partir das instruções return. Quando há várias, o resultado é a union de todas elas.

function parsePort(text: string) {
    if (text === "") return null;
    return Number(text);
}
// parsePort returns number | null

const port = parsePort("8080");
if (port !== null) {
    console.log(port + 1); // 8081: port is number inside the check
}

function log(message: string) {
    console.log(message);
}
// log returns void: there is no return value

log("done");

Tipos de retorno inferidos servem para a maioria das funções. Escreva o tipo de retorno explicitamente em funções exportadas ou públicas quando quiser que a assinatura seja um contrato: uma mudança dentro do corpo que retorne outro tipo passa a falhar na própria função, e não em algum ponto de chamada distante.

Tipagem contextual: callbacks recebem seus tipos

Parâmetros não são inferidos a partir de como a função é chamada. Há duas exceções. Um parâmetro com valor padrão assume o tipo desse valor (function retry(times = 3) faz de times um number). E uma função escrita onde um tipo de função já é esperado recebe os tipos dos parâmetros desse contexto, então parâmetros de callbacks não precisam de anotação.

const names = ["ada", "grace", "alan"];

// s is string: map on a string[] passes strings
const upper = names.map((s) => s.toUpperCase());

// a and b are strings, the result must be a number
const sorted = [...names].sort((a, b) => a.length - b.length);

// The variable's type gives the arrow its parameter and return types
const greet: (name: string) => string = (n) => `Hello, ${n}`;

console.log(upper, sorted, greet("Ada"));

O mesmo vale para forEach, filter, reduce, callbacks de Promise, handlers de eventos e qualquer função que você passe para um parâmetro com um tipo de função declarado.

Parâmetros precisam de anotação

Sem um valor padrão ou um contexto como esse, o TypeScript não olha para como a função é chamada para adivinhar os tipos dos parâmetros. Com strict ativado, um parâmetro sem anotação é o erro TS7006:

// This does not compile: a parameter with no type and no context.
function double(x) {
    return x * 2;
}
console.log(double(21));

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

Escreva function double(x: number) e o bloco imprime 42, com o tipo de retorno number inferido de x * 2.

Best common type

Para um array literal com valores de tipos diferentes, o TypeScript infere um array da union desses tipos. Ele não procura um tipo base comum que você não mencionou.

const mixed = [1, "two", null]; // (string | number | null)[]
const nums = [1, 2.5, -3];      // number[]

class Animal { name = "animal"; }
class Dog extends Animal { bark() { return "woof"; } }
class Cat extends Animal { meow() { return "meow"; } }

const pets = [new Dog(), new Cat()];            // (Cat | Dog)[]
const animals: Animal[] = [new Dog(), new Cat()]; // annotate to get Animal[]

console.log(mixed.length, nums, pets.length, animals[0].name);

O array vazio é o caso que merece atenção. const list = [] começa como um array "em evolução", cujo tipo cresce a cada push; uma anotação, const list: string[] = [], deixa a intenção clara desde o início.

Quando anotar

A forma mais rápida de ver o que foi inferido é passar o mouse sobre o nome no editor. Sem editor, atribua o valor a uma variável de tipo errado, como const probe: boolean = mixed;, e a mensagem de erro do compilador mostra o tipo inferido.