Sobrecarga de Construtor em TypeScript: como fazer de forma correta e elegante

Sobrecarga de Construtor em TypeScript: do iniciante ao profissional

Imagine: você está escrevendo uma classe User que precisa ser criada a partir de diferentes fontes. De uma string JSON, de um objeto com dados, e às vezes até sem parâmetros — apenas um perfil vazio. Em JavaScript, você simplesmente verificaria os tipos dentro de um único construtor. Mas o TypeScript nos oferece uma ferramenta muito mais elegante e segura — a sobrecarga de construtor.

Este tópico é um verdadeiro sucesso no Stack Overflow. Milhares de desenvolvedores buscam a resposta para a pergunta: “Como implementar múltiplos construtores em TypeScript?”. E não é surpresa: a sobrecarga de construtor é um padrão poderoso que torna seu código flexível, legível e type-safe. Neste artigo, abordaremos tudo, desde “por que isso é necessário” até “como fazer corretamente”, com exemplos reais.

O que é sobrecarga de construtor e por que ela é necessária?

Na POO clássica, a sobrecarga de construtor (constructor overload) é a capacidade de declarar vários construtores em uma mesma classe, cada um com seu próprio conjunto de parâmetros. O TypeScript, ao contrário do JavaScript, suporta esse conceito, mas com uma característica importante: no nível de compilação. Em runtime, uma classe pode ter apenas uma implementação de construtor, mas o TypeScript permite declarar várias assinaturas (sobrecargas) e, em seguida, escrever uma implementação única que processa os argumentos.

Por que isso é necessário? Considere três cenários:

• Flexibilidade da API: sua classe pode aceitar dados em diferentes formatos (string, objeto, array).
• Compatibilidade reversa: você adiciona novos parâmetros sem quebrar o código antigo.
• Melhoria da DX (Developer Experience): a IDE sugerirá todas as opções possíveis de chamada do construtor.

Sintaxe da sobrecarga de construtor: explicação simplificada

Vamos direto ao ponto. Aqui está um exemplo clássico — a classe User, que pode ser criada de três maneiras:

class User {    public name: string;    public age: number;    public email: string;

    // Sobrecarga 1: sem parâmetros (usuário vazio)    constructor();    // Sobrecarga 2: apenas o nome    constructor(name: string);    // Sobrecarga 3: dados completos    constructor(name: string, age: number, email: string);    // Implementação — uma para todos os casos    constructor(name?: string, age?: number, email?: string) {        if (name === undefined) {            this.name = 'Guest';            this.age = 0;            this.email = '';        } else if (age === undefined) {            this.name = name;            this.age = 0;            this.email = '';        } else {            this.name = name;            this.age = age;            this.email = email ?? '';        }    }}

// Uso:const guest = new User();                // Guest, 0, ''const john = new User('John');           // John, 0, ''const jane = new User('Jane', 25, 'jane@mail.com'); // Jane, 25, jane@mail.com

Observe: três assinaturas (sobrecargas) e uma implementação. As assinaturas são as “promessas” ao compilador TypeScript, e a implementação é “como funciona de fato”. Os parâmetros na implementação devem ser opcionais (?) para cobrir todas as variações.

Erros típicos na sobrecarga de construtor

Os desenvolvedores frequentemente tropeçam em três armadilhas:

• Erro 1: Incompatibilidade de tipos. Se a assinatura promete string e a implementação recebe number — o TypeScript emitirá um erro. Todas as assinaturas devem ser compatíveis com a implementação.
• Erro 2: Ordem das sobrecargas. O TypeScript seleciona a primeira assinatura compatível. Se você tem constructor(x: string | number) e constructor(x: string), a segunda nunca