Boas práticas em TypeScript: 8 regras com antes e depois

As regras abaixo são as que mais evitam bugs em código TypeScript real. Cada uma mostra primeiro a versão comum e depois a melhor, em código que você pode rodar. A primeira regra é a mais importante: pare de usar any.

Use unknown em vez de any

any desliga a verificação de tipos para um valor e para tudo o que é calculado a partir dele. unknown também aceita qualquer valor, mas você precisa verificá-lo antes de usar, o que coloca a verificação no ponto onde os dados entram no seu programa:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

As fronteiras são os lugares onde os tipos deixam de ser garantidos: JSON.parse, respostas de fetch, localStorage, entradas de formulário, variáveis de ambiente e mensagens de outros processos. Valide ali com um type guard ou uma biblioteca de schema, e o resto do código pode confiar nos seus tipos.

Mantenha o strict ativado

strict é o padrão no TypeScript 7; não o desative. Adicione as verificações que ele deixa de fora e que mais pegam bugs:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess faz arr[i] e record[key] incluírem undefined, que é o que eles retornam para um índice inexistente. noImplicitOverride obriga um método de subclasse a dizer override, e noFallthroughCasesInSwitch rejeita um case que continua no seguinte.

Deixe a inferência trabalhar

Anote o que o TypeScript não tem como saber: parâmetros de funções e os tipos de retorno de funções usadas por outros módulos. Deixe variáveis locais e parâmetros de callbacks para a inferência. Uma anotação desnecessária não é só ruído; ela pode deixar um tipo mais amplo que o valor:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Sem o comentário @ts-expect-error, setStatus(annotated) é o erro TS2345. O const inferido mantém o tipo literal "active", então é aceito. Passe o mouse sobre uma variável no editor para ver o que foi inferido antes de adicionar um tipo.

Prefira union types a enums

Uma union de literais de string dá autocomplete e verificações exaustivas sem código gerado. Quando você também precisa da lista de valores em tempo de execução, derive o tipo de um array as const:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Um enum Role { Admin, Viewer } vira na compilação um objeto com reverse mapping, e um parâmetro de enum numérico aceita qualquer variável number, mesmo uma com um valor que o enum não lista. Enums também não rodam com o type stripping do Node (TypeScript enum is not supported in strip-only mode). As vantagens e desvantagens estão comparadas na página de enums.

Verifique objetos de configuração com satisfies

Anotar um objeto com um tipo amplo como Record<string, Route> verifica os valores, mas esquece as chaves. satisfies verifica a mesma coisa e mantém o tipo exato:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Use uma anotação quando a variável deve ter exatamente o tipo declarado (um parâmetro de função, um valor que você vai reatribuir). Use satisfies para tabelas de consulta, mapas de rotas, tokens de tema e outros objetos constantes.

Modele estado com discriminated unions

Um único objeto com campos opcionais permite estados que não podem acontecer: loading: true junto com um error, ou data ausente depois do sucesso. Uma union de objetos com uma tag compartilhada só permite os estados reais, e cada ramo enxerga só os seus próprios campos:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

A linha com never é a verificação exaustiva. Quando alguém adiciona um estado e esquece de tratá-lo, o build quebra nessa linha:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

O erro é index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Ele diz qual case não foi tratado. Adicione case "cancelled": e compila.

Evite ! e as

A non-null assertion x! e a type assertion x as T mandam o compilador parar de verificar. Nenhuma das duas muda o valor em tempo de execução, então uma assertion errada vira uma quebra mais tarde, longe da causa:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Troque ! por ?., ??, um return antecipado ou um erro lançado com uma mensagem útil. Troque as por um type guard que de fato testa o valor. A única assertion sempre segura é as const, porque ela só deixa um tipo mais estreito e somente leitura. Uma boa configuração de lint (as regras no-non-null-assertion e no-explicit-any do typescript-eslint) aponta o resto.

Torne os dados readonly

Marque propriedades e arrays como readonly quando o código não deve alterá-los. Aí o compilador rejeita push, sort e atribuições, e as funções retornam novos valores em vez de modificar suas entradas:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly só é verificado em tempo de compilação e só um nível abaixo: ele não congela o objeto em tempo de execução. Mesmo assim, isso basta para pegar a modificação acidental de estado compartilhado, que é a causa da maioria desses bugs.