Formatar TypeScript

O código formatado

Aplicar o formatador ao TypeScript minificado acima produz:

type ApiResponse<T> = {
  data: T;
  status: number;
  message: string;
  meta: {
    page: number;
    total: number;
    hasNext: boolean;
  };
};

interface User {
  id: number;
  name: string;
  email: string;
  role: "admin" | "user" | "guest";
  preferences: {
    theme: "light" | "dark";
    language: string;
  };
}

async function fetchUsers(
  page: number = 1,
): Promise<ApiResponse<User[]>> {
  const response = await fetch(`/api/users?page=${page}`);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  return response.json();
}

function filterByRole<T extends User>(
  users: T[],
  role: T["role"],
): T[] {
  return users.filter((u) => u.role === role);
}

export type { ApiResponse, User };
export { fetchUsers, filterByRole };

Cada tipo ganha a sua própria declaração. Interfaces têm uma propriedade por linha. Parâmetros de tipos genéricos são quebrados em várias linhas quando passam da largura de impressão. Membros de union types se alinham verticalmente para facilitar a leitura.

Por que formatar TypeScript importa

Código TypeScript é mais denso que JavaScript por causa das type annotations. TypeScript sem formatação, com generics aninhados, union types e mapped types, fica ilegível mais rápido que o JavaScript equivalente. A formatação facilita várias coisas:

Revisão de tipos. Ao revisar a assinatura de uma função, você precisa ver cada parâmetro e seu tipo na sua própria linha. Uma parede de type annotations em uma linha só deixa impossível conferir tipos individuais sem analisar a string manualmente.

Refatoração. Ao renomear um tipo ou mudar uma restrição de generics, o código formatado deixa a mudança visível no diff. Em TypeScript minificado, a mesma mudança gera um diff que ocupa a linha inteira.

Documentação. TypeScript bem formatado serve como documentação. Uma definição de interface bem formatada comunica o formato de uma estrutura de dados com mais clareza que qualquer comentário.

Formatação específica de TypeScript

O Prettier lida com construções específicas de TypeScript com as mesmas regras do código JavaScript:

Type annotations: quebradas em várias linhas quando passam da largura de impressão. Tipos de parâmetros de função, tipos de retorno e restrições de generics seguem as mesmas regras de quebra de linha.

Interfaces e type aliases: uma propriedade por linha. Membros de union types podem se alinhar verticalmente quando são curtos o bastante. Discriminated unions são formatadas para deixar a propriedade discriminante bem visível.

Generics: parâmetros de tipo são quebrados em várias linhas quando são longos. Generics multilinha indentam cada parâmetro de tipo na sua própria linha.

Enums: membros formatados um por linha. Const enums seguem as mesmas regras.

Prettier vs. ESLint para TypeScript

O Prettier formata código. O ESLint encontra bugs e impõe boas práticas. Eles têm propósitos diferentes e se complementam. Uma configuração comum:

1. Use o Prettier para toda a formatação (ponto e vírgula, aspas, indentação, quebras de linha)
2. Use @typescript-eslint para lint com noção de tipos (no-unused-vars, no-explicit-any, prefer-optional-chain)
3. Desative regras do ESLint que conflitam com o Prettier (indent, semi, quotes)
4. Rode o Prettier primeiro e depois o ESLint, para o ESLint corrigir problemas que o Prettier não cobre

Essa separação garante formatação consistente com o Prettier e checagens de qualidade com o ESLint, sem uma ferramenta brigar com a outra.