Sobrecarga de funções em TypeScript: overload signatures

Sobrecarga de funções no TypeScript significa escrever várias call signatures para uma função, seguidas de uma única implementação. Cada assinatura pode combinar tipos de parâmetro diferentes com um tipo de retorno diferente, e quem chama recebe o tipo 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 ]

Sem os overloads, parse retornaria number | number[] em toda chamada, e one + 1 seria um erro até você mesmo fazer o narrowing do resultado.

Overload signatures e a implementação

Uma função sobrecarregada tem duas partes:

1. Overload signatures: declarações sem corpo, uma por formato de chamada suportado. São as únicas assinaturas que quem chama pode usar.
2. A implementation signature: a última declaração, com o corpo. Os parâmetros dela precisam aceitar tudo o que os overloads aceitam, e o tipo de retorno precisa cobrir o tipo de retorno de cada overload. Ela é invisível de fora.

Os tipos existem só em tempo de compilação, então em tempo de execução há uma única função JavaScript. A implementação precisa inspecionar os argumentos (typeof, Array.isArray, arguments.length...) para decidir o que fazer. O compilador verifica que os overloads e a implementação concordam:

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

A solução é ampliar a implementação: function format(value: string | number): string | number.

A implementation signature não pode ser chamada

Essa é a regra que mais surpreende. Uma chamada precisa corresponder sozinha a uma das overload signatures; o TypeScript não as 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)));

O compilador mostra:

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[]'.

A implementação aceita string | string[], mas quem chama não a enxerga. Adicione um terceiro overload que recebe a union e retorna a union, e a chamada 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);
}

Quantidades diferentes de parâmetros

Overloads também descrevem chamadas com aridades diferentes. Aqui uma data pode ser criada a partir de um timestamp ou de ano, mês e dia, mas não a partir de dois 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);

Uma única assinatura com dois parâmetros opcionais aceitaria makeDate(2024, 3) e criaria em silêncio a data errada. Os overloads transformam isso em um erro de compilação (TS2575).

A ordem importa

O TypeScript testa os overloads de cima para baixo e escolhe o primeiro que corresponde. Coloque as assinaturas mais específicas primeiro. Um overload amplo no começo da lista engole as chamadas destinadas aos que vêm depois:

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"

Troque as duas primeiras assinaturas de lugar e describe("hi") passa a ter o tipo "text".

Overloads ou um parâmetro union?

Os overloads valem as linhas extras quando o tipo de retorno depende dos tipos dos argumentos. Quando não depende, uma única assinatura com um parâmetro union é mais curta, mais fácil de ler e aceita argumentos union que os overloads rejeitariam.

// 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

Um generic com um conditional type consegue expressar alguns conjuntos de overloads como uma única assinatura, mas para dois ou três casos os overloads costumam ser mais fáceis de ler.

Métodos e construtores sobrecarregados

Métodos usam o mesmo padrão dentro de uma classe: overload signatures e depois o método com corpo. Construtores podem ser sobrecarregados do mesmo jeito.

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

Interfaces e tipos de objeto também podem declarar overloads, como várias call signatures ou várias method signatures com o mesmo nome. Muitas funções nativas são declaradas assim: passe o mouse sobre reduce em um array no editor e ele mostra "+2 overloads".