TypeScript: Interfaces

Introdução

As interfaces são uma das pedras fundamentais do Typescript. Elas descrevem formas que um objeto deve ter — um contrato que qualquer valor implemente aquela interface precisa respeitar.

Types vs Interfaces

Essa é a dúvida mais comum entre desenvolvedores TypeScript. As duas construções parecem fazer a mesma coisa na maioria dos casos, mas têm diferenças importantes.

A regra prática é:

Objetos públicos, contratos de classe → interface
Unions, primitivos, mapped types, composições → type

Ambas descrevem a forma de um objeto:

type Usuario = {
  id: number;
  nome: string;
};

interface Usuario {
  id: number;
  nome: string;
}

Na prática, para objetos simples, são intercambiáveis (trocado, substituído).

Diferença 1 — Declaration Merging

Interfaces podem ser declaradas múltiplas vezes e o TypeScript mescla automaticamente:

interface Configuracao {
  host: string;
}

interface Configuracao {
  porta: number;
}

// TypeScript mescla as duas:
// { host: string; porta: number }
const config: Configuracao = {
  host: "localhost",
  porta: 5432
};

Com type, isso gera erro:

type Configuracao = { host: string };
type Configuracao = { porta: number }; // ❌ identificador duplicado

Declaration merging é especialmente útil para estender libs externas sem modificar o código delas.

Diferença 2 — Tipos compostos

type consegue representar qualquer coisa, interface só representa objetos:

// só type consegue fazer isso:
type ID = string | number;
type Status = "ativo" | "inativo";
type Nullable<T> = T | null;
type Par<T> = [T, T];

Diferença 3 — Extends vs Intersecção

// interface usa extends
interface Animal { nome: string }
interface Cachorro extends Animal { raca: string }

// type usa &
type Animal = { nome: string }
type Cachorro = Animal & { raca: string }

Funcionalmente equivalentes, mas extends em interface gera mensagens de erro mais claras.

Declaração de Interfaces

Interface declaration é a sintaxe formal de declarar uma interface — mas vai além de propriedades simples. Interfaces suportam vários tipos de membros.

Propriedades

interface Produto {
  id: number;           // obrigatória
  descricao?: string;   // opcional
  readonly codigo: string; // somente leitura
}

readonly impede atribuição após a criação do objeto.

Métodos

interface Repositorio<T> {
  buscarPorId(id: string): Promise<T>;
  salvar(entidade: T): Promise<T>;
  deletar(id: string): Promise<void>;
  listar(): Promise<T[]>;
}

Call Signatures

interface Validador {
  (valor: string): boolean;
}

const validarCNPJ: Validador = (cnpj) => cnpj.length === 14;

Implementação em classes

interface Transmissor {
  transmitir(payload: unknown): Promise<Protocolo>;
  consultar(protocolo: string): Promise<Status>;
}

class TransmissorReinf implements Transmissor {
  async transmitir(payload: unknown): Promise<Protocolo> {
    // implementação
  }

  async consultar(protocolo: string): Promise<Status> {
    // implementação
  }
}

Se a classe não implementar algum método da interface, o TypeScript acusa erro em tempo de compilação.

Extendendo interfaces

Interfaces podem ser estendidas para criar hierarquias de contratos sem duplicar código.

Extends simples

interface EntidadeBase {
  id: string;
  criadoEm: Date;
  atualizadoEm: Date;
}

interface Tenant extends EntidadeBase {
  cnpj: string;
  razaoSocial: string;
}

interface Evento extends EntidadeBase {
  tipo: string;
  competencia: string;
}

Extends múltiplo

Uma interface pode estender várias ao mesmo tempo:

interface ComAuditoria {
  criadoPor: string;
  atualizadoPor: string;
}

interface ComSoftDelete {
  deletadoEm?: Date;
  ativo: boolean;
}

interface EntidadeCompleta extends ComAuditoria, ComSoftDelete {
  id: string;
}

// EntidadeCompleta tem tudo:
// id, criadoPor, atualizadoPor, deletadoEm, ativo

Sobrescrevendo propriedades

Você pode sobrescrever uma propriedade herdada, mas o novo tipo precisa ser compatível com o original:

interface Base {
  id: string | number;
}

interface Derivada extends Base {
  id: string; // ✅ string é subconjunto de string | number
}

interface Invalida extends Base {
  id: boolean; // ❌ boolean não é compatível com string | number
}

Caso prático — sistema fiscal

interface EntidadeBase {
  id: string;
  criadoEm: Date;
  atualizadoEm: Date;
  ativo: boolean;
}

interface EventoFiscal extends EntidadeBase {
  tenantId: string;
  competencia: string;
  status: "pendente" | "processando" | "concluido" | "erro";
}

interface EventoEFDReinf extends EventoFiscal {
  codigoEvento: string;
  cnpjContribuinte: string;
}

interface EventoEFinanceira extends EventoFiscal {
  rubrica: string;
  tipoMovimento: string;
}

Tipos Híbridos

Hybrid types são interfaces que descrevem um valor que é simultaneamente uma função e um objeto. Parece incomum, mas existe em várias libs JavaScript.

Hybrid types são raramente necessários em código novo — são mais úteis para tipar libs JavaScript existentes que foram escritas antes do TypeScript existir. Em código novo, prefira separar a função do objeto explicitamente.

Em JavaScript, funções são objetos — então uma função pode ter propriedades:

function contador() { ... }
contador.total = 0;        // função com propriedade
contador.resetar = () => { ... }; // função com método

Interfaces conseguem descrever exatamente isso.

interface Contador {
  (): number;           // call signature — é uma função
  total: number;        // propriedade
  resetar(): void;      // método
}

function criarContador(): Contador {
  let count = 0;

  const contador = function(): number {
    return ++count;
  } as Contador;

  contador.total = 0;
  contador.resetar = () => { count = 0; };

  return contador;
}

const c = criarContador();
c();          // chama como função → 1
c();          // → 2
c.total;      // acessa propriedade
c.resetar();  // chama método