Respuesta.

Historia de la pregunta

En lenguajes como Java o C#, la sobrecarga de funciones y métodos es una capacidad estándar: se pueden declarar varias funciones con el mismo nombre pero con diferentes parámetros. En JavaScript esto no existe, lo que añade errores potenciales. TypeScript resuelve este problema a nivel de tipos.

Problema

En TypeScript no hay una verdadera sobrecarga (múltiples implementaciones). Se pueden declarar varias firmas de una función, pero solo implementar una función. Los errores ocurren cuando hay desincronización entre las firmas declaradas y la implementación, o por un posicionamiento incorrecto de las firmas.

Solución

TypeScript soporta la sobrecarga de funciones mediante la declaración de varias firmas seguidas de una única implementación real, compatible con todas las variantes de sobrecarga.

Ejemplo de código:

function sum(a: number, b: number): number;
function sum(a: string, b: string): string;
function sum(a: any, b: any): any {
  return a + b;
}

const a = sum(1, 2); // 3
const b = sum('foo', 'bar'); // "foobar"

Características clave:

Siempre una implementación después de todas las firmas
La implementación debe ser compatible con todas las variantes de sobrecarga
TypeScript verifica la corrección de la llamada al usar la función sobrecargada

Preguntas capciosas.

¿Se puede definir la implementación de la función antes de declarar todas las firmas de sobrecarga?

No, primero deben estar todas las firmas de sobrecarga y luego la implementación. Error:

// ¡Error! Primero las firmas, luego la implementación
function foo(a: number): number { return a } // error
function foo(a: string): string { return a } // error

¿TypeScript verifica los valores devueltos en todas las firmas de sobrecarga?

TypeScript garantiza el retorno de tipos según las firmas declaradas solo en el tiempo de compilación; no hay verificación de tipos durante la ejecución.

¿Es necesario cubrir todas las variantes de entradas en una única implementación?

La función-implementación debe manejar correctamente todas las variantes de entrada según las firmas de sobrecarga:

function parse(a: number): string;
function parse(a: string): string;
function parse(a: number | string): string {
  return String(a);
}

Errores típicos y anti-patrones

Descoordinación entre la implementación y las firmas de sobrecarga
Orden incorrecto en la declaración de firmas e implementación
Manejo implícito/ignorancia de combinaciones de tipos

Ejemplo de la vida real

Caso negativo

Se declaran varias sobrecargas de la función con diferentes tipos de entradas, pero la implementación no maneja todos los casos y lanza un error en tiempo de ejecución con entradas raras.

Ventajas:

API flexible para los usuarios de la función

Desventajas:

Los tipos se compilan, pero la operación de la función es incorrecta sin comprobaciones adicionales dentro del cuerpo

Caso positivo

Cada sobrecarga de la función se cubre con una condición sobre tipos dentro de la implementación, utilizando verificaciones de tipo (typeof/instanceof).