Construtor em TypeScript: parameter properties e overloads

Um construtor no TypeScript é o método constructor da classe com parâmetros tipados. Ele não tem anotação de tipo de retorno: sempre produz uma instância da classe.

class Product {
    name: string;
    price: number;

    constructor(name: string, price: number) {
        this.name = name;
        this.price = price;
    }
}

const p = new Product("Lamp", 39);
console.log(p); // Product { name: 'Lamp', price: 39 }

// @ts-expect-error: Expected 2 arguments, but got 1.
new Product("Chair");

Escrever constructor(): Product gera o erro TS1093 (Type annotation cannot appear on a constructor declaration). Todo o resto sobre como o new funciona é JavaScript puro.

Parameter properties

O padrão acima (declarar um campo, receber um parâmetro, copiá-lo) é tão comum que o TypeScript tem uma abreviação. Coloque public, private, protected ou readonly antes de um parâmetro do construtor e ele vira um campo:

class Product {
    constructor(
        public name: string,
        private price: number,
        readonly sku: string,
    ) {}

    label(): string {
        return `${this.name} (${this.sku}): $${this.price}`;
    }
}

const lamp = new Product("Lamp", 39, "LMP-1");
console.log(lamp.label()); // Lamp (LMP-1): $39
console.log(lamp.name, lamp.sku); // Lamp LMP-1
// lamp.price is private: accessing it outside the class is a compile error

Esse é um dos poucos recursos do TypeScript que geram código. O compilador escreve as atribuições para você:

class Product {
    name;
    price;
    sku;
    constructor(name, price, sku) {
        this.name = name;
        this.price = price;
        this.sku = sku;
    }
    // ...
}

Como não se trata só de tipos apagados, as parameter properties não rodam com o type stripping nativo do Node (node file.ts falha com ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX), e a opção do compilador erasableSyntaxOnly as aponta como erro TS1294. Projetos que rodam arquivos .ts diretamente escrevem os campos à mão.

Parâmetros opcionais e com valor padrão

Os parâmetros do construtor seguem as mesmas regras dos parâmetros de função: ? torna um opcional, um valor padrão o torna opcional e o preenche, e os obrigatórios vêm primeiro.

class Logger {
    constructor(
        readonly prefix: string,
        readonly level: "info" | "debug" = "info",
        readonly color?: string,
    ) {}
}

console.log(new Logger("app"));
// Logger { prefix: 'app', level: 'info', color: undefined }
console.log(new Logger("db", "debug", "blue"));
// Logger { prefix: 'db', level: 'debug', color: 'blue' }

Parameter properties também podem ter padrões. O tipo de color dentro da classe é string | undefined, então o código que o usa precisa verificar undefined antes.

Para construtores com muitas opções, um único objeto de opções fica mais legível que uma lista longa de parâmetros posicionais: constructor(opts: { prefix: string; level?: "info" | "debug" }).

Ordem de inicialização dos campos

Os inicializadores de campo rodam antes do corpo do construtor, e as parameter properties são atribuídas no começo do corpo do construtor. Então um inicializador de campo não pode ler uma parameter property. O TypeScript pega isso:

// This does not compile: the initializer reads `size` too early.
class Grid {
    cells = this.size * this.size;

    constructor(public size: number) {}
}

console.log(new Grid(3).cells);

index.ts(3,18): error TS2729: Property 'size' is used before its initialization.
index.ts(3,30): error TS2729: Property 'size' is used before its initialization.

Em tempo de execução o inicializador veria undefined e produziria NaN. Calcule o valor no corpo do construtor:

class Grid {
    cells: number;

    constructor(public size: number) {
        this.cells = size * size;
    }
}

console.log(new Grid(3).cells); // 9

Overloads de construtor

Uma classe tem exatamente uma implementação de construtor, mas você pode listar várias overload signatures acima dela. Quem chama só vê os overloads; a implementation signature precisa ser compatível com todos eles.

class Color {
    r: number;
    g: number;
    b: number;

    constructor(hex: string);
    constructor(r: number, g: number, b: number);
    constructor(a: string | number, g = 0, b = 0) {
        if (typeof a === "string") {
            const n = parseInt(a.replace("#", ""), 16);
            this.r = (n >> 16) & 255;
            this.g = (n >> 8) & 255;
            this.b = n & 255;
        } else {
            this.r = a;
            this.g = g;
            this.b = b;
        }
    }
}

console.log(new Color("#ff8800")); // Color { r: 255, g: 136, b: 0 }
console.log(new Color(10, 20, 30)); // Color { r: 10, g: 20, b: 30 }
// new Color(10, 20) is an error: no overload takes 2 arguments

Overloads ficam difíceis de ler a partir de dois ou três formatos. Métodos estáticos de fábrica com nomes descritivos (Color.fromHex("#ff8800"), Color.fromRgb(10, 20, 30)) costumam ser mais claros e não precisam de narrowing dentro de um único corpo.

Chamando super em uma subclasse

Uma classe derivada que declara o próprio construtor precisa chamar super(...) com os argumentos do pai, e precisa fazer isso antes de usar o this. Esquecer a chamada gera o erro TS2377 (Constructors for derived classes must contain a 'super' call), e usar o this antes gera o TS17009 ('super' must be called before accessing 'this' in the constructor of a derived class). As duas regras espelham regras de tempo de execução do JavaScript.

class Animal {
    constructor(public name: string) {}
}

class Dog extends Animal {
    tricks: string[];

    constructor(name: string, ...tricks: string[]) {
        super(name); // must come first
        this.tricks = tricks;
    }
}

const rex = new Dog("Rex", "sit", "roll");
console.log(rex); // Dog { name: 'Rex', tricks: [ 'sit', 'roll' ] }

Uma subclasse que não declara construtor herda o do pai, com os mesmos tipos de parâmetro. Mais sobre subclasses em herança.

Construtores privados e configuração assíncrona

Um construtor private só pode ser chamado de dentro da classe. Fora dela, new gera o erro TS2673. É assim que você obriga quem chama a passar por uma fábrica, para um singleton ou para uma configuração que precisa ser assíncrona (construtores não podem ser async).

class Connection {
    private constructor(readonly url: string, readonly version: number) {}

    static async open(url: string): Promise<Connection> {
        const version = await Promise.resolve(3); // stands in for a real handshake
        return new Connection(url, version);
    }
}

async function main() {
    const conn = await Connection.open("db://local");
    console.log(conn.url, conn.version); // db://local 3
}
main();

Aqui o private é só uma regra de tempo de compilação. O JavaScript gerado tem um construtor comum, então código JavaScript puro ainda conseguiria chamar new Connection(...).

Tipos de construtor

Para aceitar uma classe como valor, tipe o parâmetro com uma construct signature: new (...args) => Instance. typeof MyClass também funciona, mas amarra o parâmetro à assinatura de construtor e aos membros estáticos daquela classe específica.

class Circle {
    constructor(public r: number) {}
}
class Square {
    constructor(public r: number) {}
}

type ShapeCtor<T> = new (size: number) => T;

function makeAll<T>(ctor: ShapeCtor<T>, sizes: number[]): T[] {
    return sizes.map((s) => new ctor(s));
}

console.log(makeAll(Circle, [1, 2])); // [ Circle { r: 1 }, Circle { r: 2 } ]
console.log(makeAll(Square, [5]));    // [ Square { r: 5 } ]

type CircleArgs = ConstructorParameters<typeof Circle>; // [r: number]
const args: CircleArgs = [7];
console.log(new Circle(...args)); // Circle { r: 7 }

ConstructorParameters e InstanceType extraem a tupla de parâmetros e o tipo da instância de um tipo de construtor; eles são tratados junto com os outros helpers de função em ReturnType e Parameters.