Overloaded Method

Method overloading in TypeScript is a compile-time polymorphism feature that allows a single method to be declared with multiple distinct call signatures, backed by a single, unified implementation. It enables the type system to enforce specific parameter combinations and accurately infer return types based on the provided arguments.

Anatomy of an Overloaded Method

An overloaded method consists of two distinct parts:

1. Overload Signatures (Declarations): One or more method declarations without a body. These define the exact parameter types, arity, and return types exposed to the caller.
2. Implementation Signature: A single method definition containing the actual logic. This signature must be structurally compatible with all preceding overload signatures but is strictly hidden from the caller.

class DataProcessor {
    // 1. Overload Signatures
    process(input: string): string[];
    process(input: number, format: boolean): string;
    
    // 2. Implementation Signature
    process(input: string | number, format?: boolean): string[] | string {
        if (typeof input === "string") {
            return input.split("");
        }
        return format ? input.toFixed(2) : input.toString();
    }
}

const processor = new DataProcessor();
processor.process("test");        // Resolves to the first signature
processor.process(100, true);     // Resolves to the second signature
// processor.process(100);        // Error: No overload expects 1 argument for a number

Technical Constraints and Rules

To successfully implement method overloading, the TypeScript compiler enforces several strict rules:

• Implementation Invisibility: The implementation signature cannot be called directly. If an overload signature dictates that a method takes either one string or two numbers, passing one number will result in a compiler error, even if the implementation signature technically accepts it via an optional parameter.
• Type Compatibility: The parameter types and return type of the implementation signature must be a superset of all overload signatures. This is typically achieved using union types (|), optional parameters (?), or, in broader cases, unknown or any.
• Arity Accommodation: If the overload signatures have varying numbers of parameters (different arity), the implementation signature must account for the maximum possible arguments using optional parameters or rest parameters (...args).
• Sequential Resolution: The TypeScript compiler resolves overloads by evaluating the signatures from top to bottom. It selects the first signature where the provided arguments satisfy the parameter types. Consequently, more specific signatures must be declared above broader or more generic signatures to prevent premature matching.

Master TypeScript with Deep Grasping Methodology!

Learn More