Sobrecarga de funciones en TypeScript: overload signatures

La sobrecarga de funciones en TypeScript consiste en escribir varias firmas de llamada para una función, seguidas de una única implementación. Cada firma puede combinar distintos tipos de parámetros con un tipo de retorno distinto, y quien llama obtiene el preciso.

// Overload signatures: what callers see
function parse(input: string): number;
function parse(input: string[]): number[];
// Implementation: one body that handles every case
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

const one = parse("42");          // one: number
const many = parse(["1", "2.5"]); // many: number[]

console.log(one + 1);             // 43
console.log(many.map((n) => n * 2)); // [ 2, 5 ]

Sin las sobrecargas, parse devolvería number | number[] en todas las llamadas, y one + 1 sería un error hasta que estrecharas tú mismo el resultado.

Firmas de sobrecarga y la implementación

Una función sobrecargada tiene dos partes:

1. Firmas de sobrecarga: declaraciones sin cuerpo, una por cada forma de llamada admitida. Son las únicas firmas que puede usar quien llama.
2. La firma de implementación: la última declaración, la que tiene cuerpo. Sus parámetros deben aceptar todo lo que aceptan las sobrecargas, y su tipo de retorno debe cubrir el tipo de retorno de cada sobrecarga. Desde fuera es invisible.

Los tipos solo existen en tiempo de compilación, así que en tiempo de ejecución hay una sola función de JavaScript. La implementación tiene que inspeccionar sus argumentos (typeof, Array.isArray, arguments.length...) para decidir qué hacer. El compilador comprueba que las sobrecargas y la implementación concuerdan:

function format(value: string): string;
function format(value: number): number {
  return value;
}
// error TS2394: This overload signature is not compatible with its implementation signature.

La solución es ampliar la implementación: function format(value: string | number): string | number.

La firma de implementación no se puede llamar

Esta es la regla que más sorprende. Una llamada tiene que encajar por sí sola con una de las firmas de sobrecarga; TypeScript no las combina.

// This does not compile: no single overload takes string | string[].
function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

function readInput(multi: boolean): string | string[] {
  return multi ? ["1", "2"] : "3";
}

console.log(parse(readInput(true)));

El compilador muestra:

index.ts(12,19): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string | string[]' is not assignable to parameter of type 'string[]'.
      Type 'string' is not assignable to type 'string[]'.

La implementación acepta string | string[], pero quien llama no la ve. Añade una tercera sobrecarga que reciba la unión y devuelva la unión, y la llamada compila e imprime [ 1, 2 ]:

function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

Distinto número de parámetros

Las sobrecargas también describen llamadas con distinta aridad. Aquí se puede construir una fecha a partir de un timestamp o de año, mes y día, pero no a partir de dos números:

function makeDate(timestamp: number): Date;
function makeDate(year: number, month: number, day: number): Date;
function makeDate(a: number, month?: number, day?: number): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(Date.UTC(a, month - 1, day));
  }
  return new Date(a);
}

console.log(makeDate(0).toISOString());          // 1970-01-01T00:00:00.000Z
console.log(makeDate(2024, 3, 15).toISOString()); // 2024-03-15T00:00:00.000Z

// @ts-expect-error: No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
makeDate(2024, 3);

Una sola firma con dos parámetros opcionales aceptaría makeDate(2024, 3) y construiría sin avisar una fecha equivocada. Las sobrecargas lo convierten en un error de compilación (TS2575).

El orden importa

TypeScript prueba las sobrecargas de arriba abajo y elige la primera que encaja. Pon primero las firmas más específicas. Una sobrecarga amplia al principio de la lista se queda con las llamadas pensadas para las que vienen después:

function describe(value: unknown): string;   // matches everything
function describe(value: string): "text";    // never chosen
function describe(value: unknown): string {
  return typeof value === "string" ? "text" : "other";
}

const d = describe("hi"); // d: string, not "text"

Intercambia las dos primeras firmas y describe("hi") pasa a tener el tipo "text".

¿Sobrecargas o un parámetro unión?

Las sobrecargas compensan sus líneas de más cuando el tipo de retorno depende de los tipos de los argumentos. Cuando no es así, una sola firma con un parámetro unión es más corta, más fácil de leer y acepta argumentos unión que las sobrecargas rechazarían.

// Overloads that add nothing: the return type is always number
function lengthOfA(x: string): number;
function lengthOfA(x: unknown[]): number;
function lengthOfA(x: string | unknown[]): number {
  return x.length;
}

// Better: one signature
function lengthOf(x: string | unknown[]): number {
  return x.length;
}

function pick(useList: boolean): string | number[] {
  return useList ? [1, 2, 3] : "abc";
}

const input = pick(true);
console.log(lengthOf(input)); // 3 (lengthOfA(input) would be TS2769)
console.log(lengthOfA("abcd")); // 4

Un genérico con un conditional type puede expresar algunos conjuntos de sobrecargas como una sola firma, pero para dos o tres casos las sobrecargas suelen leerse mejor.

Métodos y constructores sobrecargados

Los métodos usan el mismo patrón dentro de una clase: firmas de sobrecarga y después el método con cuerpo. Los constructores se pueden sobrecargar igual.

class Money {
  readonly cents: number;

  constructor(cents: number);
  constructor(amount: string);
  constructor(value: number | string) {
    this.cents = typeof value === "number" ? value : Math.round(parseFloat(value) * 100);
  }

  add(other: Money): Money;
  add(cents: number): Money;
  add(value: Money | number): Money {
    const extra = typeof value === "number" ? value : value.cents;
    return new Money(this.cents + extra);
  }
}

const price = new Money("19.99");
console.log(price.add(1).cents);               // 2000
console.log(price.add(new Money(1)).cents);    // 2000

Las interfaces y los tipos objeto también pueden declarar sobrecargas, como varias firmas de llamada o varias firmas de método con el mismo nombre. Muchas funciones integradas se declaran así: pasa el cursor por reduce sobre un array en un editor y verás "+2 overloads".