Poucas questões sobre TypeScript causam tanto debate quanto Interface TypeScript versus tipo. Muitos artigos listam diferenças que costumavam ser importantes em versões mais antigas, mas agora estão desatualizadas. Então, em vez de repetir afirmações, nós as testamos.

Escrevemos um arquivo exercitando cada diferença e o verificamos com TypeScript 5.6.3 em modo estrito. Os erros do compilador citados abaixo vêm dessa execução. O comportamento pode mudar entre as versões, portanto, verifique a versão TypeScript que seu projeto usa. Se você é novo na linguagem, comece com nosso tutorial TypeScript para iniciantes.

A resposta curta

Um interface descreve a forma de um objeto e pode ser estendido ou reaberto. Um type alias dá um nome a qualquer tipo, incluindo objetos, uniões, tuplas e tipos de função. Onde ambos podem funcionar, a diferença é principalmente o estilo.

Onde eles são iguais

Estas duas declarações descrevem formas idênticas:

interface User {
  id: number;
  name: string;
  email?: string;
}

type UserAlias = {
  id: number;
  name: string;
  email?: string;
};

const a: User = { id: 1, name: "Asha" };
const b: UserAlias = a;   // no error

O TypeScript usa tipagem estrutural, o que significa que compara formas em vez de nomes. É por isso que um User pode ser atribuído a um UserAlias sem reclamação. Ambos suportam propriedades opcionais, readonly propriedades, métodos e assinaturas de índice.

Interface vs tipo lado a lado

O que só o tipo pode fazer

Muitos tipos úteis não são formas de objetos e apenas um alias de tipo pode nomeá-los:

type Status = "pending" | "paid" | "shipped";   // union
type Point = [number, number];                    // tuple
type Handler = (event: string) => void;           // function type
type Keys = keyof User;                           // computed type
type ReadonlyUser = Readonly<User>;               // utility type

Os tipos de união estão entre os recursos mais valiosos do TypeScript, porque o compilador rejeita qualquer valor fora da lista:

let s: Status = "paid";
s = "refunded";

// error TS2322: Type '"refunded"' is not assignable to type 'Status'.

Isso detecta erros de digitação e valores desatualizados em tempo de compilação, antes que cheguem à produção.

Mesclagem de declarações

Se você declarar uma interface com o mesmo nome duas vezes, o TypeScript as mesclará em uma:

interface Settings {
  theme: string;
}
interface Settings {
  language: string;
}

const settings: Settings = { theme: "dark", language: "en" };   // no error

Tente a mesma coisa com um alias de tipo e o compilador recusa:

type Config = { theme: string };
type Config = { language: string };

// error TS2300: Duplicate identifier 'Config'.

Mesclar é como as bibliotecas permitem estender seus tipos. Por exemplo, você pode adicionar uma propriedade personalizada à interface global Window ou ao objeto de solicitação de uma estrutura, sem modificar a biblioteca. Isso é genuinamente útil.

O outro lado é que a fusão pode acontecer por acidente. Se dois arquivos em um projeto declaram uma interface com o mesmo nome no mesmo escopo, eles se combinam silenciosamente, o que pode ser confuso. Um alias de tipo torna essa colisão um erro.

estende vs interseções

Ambos permitem desenvolver um tipo existente:

interface Admin extends User {
  permissions: string[];
}

type AdminAlias = UserAlias & { permissions: string[] };

Para propriedades compatíveis, o resultado é o mesmo. A diferença aparece com um conflito. Quando uma interface tenta alterar o tipo de uma propriedade de forma incompatível, o compilador reporta isso imediatamente:

interface Base { id: number }
interface Broken extends Base { id: string }

// error TS2430: Interface 'Broken' incorrectly extends interface 'Base'.
//   Types of property 'id' are incompatible.
//     Type 'string' is not assignable to type 'number'.

Um cruzamento não reclama quando é declarado. Em vez disso, a propriedade conflitante se torna never, um tipo que nenhum valor pode ter. O erro só aparece mais tarde, quando você tenta utilizá-lo:

type Mixed = { id: number } & { id: string };
const m: Mixed = { id: 1 };

// error TS2322: Type 'number' is not assignable to type 'never'.

Esse erro posterior é mais confuso, pois aponta para longe do erro real. Esta é uma razão prática para preferir extends ao construir tipos de objetos.

Aulas e implementos

Uma classe pode prometer corresponder a uma forma usando implements, e isso funciona com uma interface ou um alias de tipo de objeto:

class Account implements User {
  constructor(public id: number, public name: string) {}
}

Isto compilado sem erros. Observe que implements apenas verifica se a classe corresponde. Ele não adiciona nenhuma propriedade ou código. Uma classe não pode implementar um tipo de união, pois não existe uma forma única para corresponder.

Somente leitura e tipos de utilitários

Tipos de utilitários como Readonly, Partial, Pick e Omit funcionam com interfaces e aliases. O resultado é um novo tipo, que normalmente é nomeado com um alias de tipo:

const r: ReadonlyUser = { id: 3, name: "Dev" };
r.name = "Chitra";

// error TS2540: Cannot assign to 'name' because it is a read-only property.

Lembre-se de que readonly é apenas uma verificação em tempo de compilação. Em tempo de execução, o objeto é JavaScript comum e ainda pode ser alterado por código que ignora os tipos.

Desempenho do compilador

A orientação de desempenho da própria equipe do TypeScript sugere preferir interfaces que usam extends em vez de interseções grandes, porque o compilador pode armazenar em cache os relacionamentos de interface com mais eficiência. Em projetos pequenos e médios é improvável que você note alguma diferença. Pode ser importante em bases de código muito grandes com tipos profundamente compostos. Nós mesmos não medimos isso.

Qual você deve usar?

Uma regra amplamente utilizada, de acordo com as orientações do manual TypeScript, é:

• Use interface para formas de objetos, especialmente APIs públicas e qualquer coisa que as classes implementem ou outras possam estender.
• Use type para uniões, tuplas, tipos de função e tipos mapeados ou computados.

Algumas equipes simplesmente usam type em todos os lugares, e isso também funciona bem. O que mais importa é a consistência, então escolha uma convenção, escreva-a em seu guia de estilo e deixe um linter aplicá-la. A regra consistent-type-definitions do ESLint do typescript-eslint pode fazer isso.

Erros comuns

• Debate sem fim. Ambos são bons para objetos, então estabeleça a regra uma vez e siga em frente.
• Mesclagem acidental. A reutilização de um nome de interface no mesmo escopo combina-os silenciosamente.
• Interseções conflitantes. Eles criam never tipos com erros confusos posteriormente.
• Tipos confiáveis ​​em tempo de execução. Eles são apagados, então valide os dados externos.
• Usar any para silenciar erros. Desativa a verificação. Prefira unknown e restrinja-o.

Alternando entre eles em uma base de código existente

Alterar interface para type, ou o inverso, geralmente é seguro para formas de objetos simples, porque o TypeScript compara os tipos por sua estrutura, não por seus nomes. Algumas coisas ainda precisam ser verificadas antes de você mudar:

• A conversão de uma interface em um alias de tipo remove a mesclagem de declarações, portanto, qualquer segunda declaração com o mesmo nome se torna um erro de identificador duplicado.
• A conversão de um alias de tipo em uma interface funciona apenas para formas de objetos. Uniões, tuplas e tipos mapeados devem permanecer como aliases de tipo.
• Mensagens de erro e atualizações do editor podem exibir o tipo de maneira diferente, o que pode surpreender os colegas de equipe, mas não altera o comportamento.

Faça a mudança em uma solicitação pull focada, execute o compilador no modo estrito e seu conjunto de testes e evite misturá-lo com o trabalho de recursos para que os revisores possam ver que nada mais mudou.

Considerações finais

A questão interface versus tipo tem uma resposta calma: eles se sobrepõem aos objetos, cada um tem algumas habilidades únicas e a consistência é mais importante do que a escolha. Use interfaces para formas e tipos para todo o resto, a menos que sua equipe prefira o contrário. Para ver as diferenças você mesmo, copie os exemplos acima em um arquivo e execute tsc --noEmit --strict nele.

Perguntas frequentes

Continue aprendendo