Overloaded Constructor

A TypeScript overloaded constructor is a mechanism that permits a class to be instantiated using multiple, distinct parameter configurations. Because JavaScript runtime environments only support a single constructor function per class, TypeScript achieves overloading at the type level by separating the constructor declarations (overload signatures) from the actual logic (implementation signature).

Architecture of an Overloaded Constructor

An overloaded constructor consists of two distinct parts:

1. Overload Signatures: One or more declarations defining the exact parameter types and counts permitted during instantiation. These contain no implementation body.
2. Implementation Signature: A single constructor containing the execution logic. Its parameter list must be broad enough to encompass all preceding overload signatures using union types, optional parameters, or rest parameters.

class Point {
    // 1. Overload Signatures
    constructor(x: number);
    constructor(x: number, y: number);
    constructor(coordinates: string);

    // 2. Implementation Signature
    constructor(xOrCoords: number | string, y?: number) {
        if (typeof xOrCoords === "string") {
            // Type narrowing for the string overload
            const parsed = xOrCoords.split(',');
            this.x = parseInt(parsed[0], 10);
            this.y = parseInt(parsed[1], 10);
        } else {
            // Type narrowing for the number overloads
            this.x = xOrCoords;
            this.y = y ?? 0; 
        }
    }

    x: number;
    y: number;
}

Technical Constraints and Behavior

• Implementation Invisibility: The implementation signature is strictly for internal resolution and is not directly callable. If a developer attempts to instantiate the class using arguments that match the implementation signature but do not match any overload signature, the TypeScript compiler will throw an error.
• Type Compatibility: Every parameter in the implementation signature must be compatible with the corresponding parameters in all overload signatures. If an overload signature specifies fewer arguments than the implementation signature, the trailing parameters in the implementation must be marked as optional (?).
• Type Narrowing Requirement: Because the implementation signature receives a union of all possible types defined in the overloads, the constructor body must utilize type guards (e.g., typeof, instanceof, or truthiness checks) to narrow the types and execute the correct initialization logic.
• Return Type: Unlike standard function overloads where return types can vary, constructor overloads implicitly return an instance of the class. Explicit return type annotations are not permitted on constructor signatures.

Master TypeScript with Deep Grasping Methodology!

Learn More