Overloading di funzioni in TypeScript: le overload signatures

L'overloading di funzioni in TypeScript consiste nello scrivere più firme di chiamata per una funzione, seguite da un'unica implementazione. Ogni firma può abbinare tipi di parametro diversi a un tipo di ritorno diverso, e chi chiama ottiene quello 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 ]

Senza gli overload, parse restituirebbe number | number[] per ogni chiamata e one + 1 sarebbe un errore finché non restringi tu il risultato.

Overload signatures e implementazione

Una funzione con overload ha due parti:

1. Overload signatures: dichiarazioni senza corpo, una per ogni forma di chiamata supportata. Sono le uniche firme che chi chiama può usare.
2. La firma di implementazione: l'ultima dichiarazione, quella con il corpo. I suoi parametri devono accettare tutto ciò che accettano gli overload, e il suo tipo di ritorno deve coprire il tipo di ritorno di ogni overload. Dall'esterno è invisibile.

I tipi esistono solo in fase di compilazione, quindi a runtime c'è una sola funzione JavaScript. L'implementazione deve esaminare i suoi argomenti (typeof, Array.isArray, arguments.length...) per decidere cosa fare. Il compilatore controlla che overload e implementazione siano d'accordo:

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 soluzione è allargare l'implementazione: function format(value: string | number): string | number.

La firma di implementazione non si può chiamare

È la regola che sorprende di più. Una chiamata deve corrispondere da sola a una delle overload signatures; TypeScript non le 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)));

Il compilatore stampa:

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

L'implementazione accetta string | string[], ma chi chiama non la vede. Aggiungi un terzo overload che prende l'unione e restituisce l'unione, e la chiamata compila e stampa [ 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);
}

Numeri diversi di parametri

Gli overload descrivono anche chiamate con un numero diverso di argomenti. Qui una data si può costruire da un timestamp oppure da anno, mese e giorno, ma non da due numeri:

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 due parametri facoltativi accetterebbe makeDate(2024, 3) e costruirebbe in silenzio la data sbagliata. Gli overload lo trasformano in un errore di compilazione (TS2575).

L'ordine conta

TypeScript prova gli overload dall'alto verso il basso e sceglie il primo che corrisponde. Metti prima le firme più specifiche. Un overload generico all'inizio della lista si prende le chiamate destinate a quelli successivi:

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"

Scambia le prime due firme e describe("hi") avrà tipo "text".

Overload o parametro unione?

Gli overload valgono le righe in più quando il tipo di ritorno dipende dai tipi degli argomenti. Quando non è così, una sola firma con un parametro unione è più corta, più leggibile e accetta argomenti unione che gli overload rifiuterebbero.

// 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 generic con un conditional type può esprimere alcuni insiemi di overload con una sola firma, ma per due o tre casi gli overload di solito sono più leggibili.

Metodi e costruttori con overload

Dentro una classe i metodi usano lo stesso schema: overload signatures, poi il metodo con il corpo. Anche i costruttori si possono sovraccaricare allo stesso modo.

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

Anche interfacce e tipi oggetto possono dichiarare overload, come più firme di chiamata o più firme di metodo con lo stesso nome. Molte funzioni integrate sono dichiarate così: passa il mouse su reduce di un array in un editor e vedrai "+2 overloads".