Surcharge de fonctions en TypeScript : les signatures d'overload

La surcharge de fonctions en TypeScript consiste à écrire plusieurs signatures d'appel pour une fonction, suivies d'une seule implémentation. Chaque signature peut associer des types de paramètres différents à un type de retour différent, et l'appelant obtient le type précis qui lui correspond.

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

Sans les surcharges, parse renverrait number | number[] pour chaque appel, et one + 1 serait une erreur tant que vous n'auriez pas affiné le résultat vous-même.

Signatures de surcharge et implémentation

Une fonction surchargée a deux parties :

1. Les signatures de surcharge : des déclarations sans corps, une par forme d'appel prise en charge. Ce sont les seules signatures que les appelants peuvent utiliser.
2. La signature d'implémentation : la dernière déclaration, avec le corps. Ses paramètres doivent accepter tout ce qu'acceptent les surcharges, et son type de retour doit couvrir celui de chaque surcharge. Elle est invisible de l'extérieur.

Les types n'existent qu'à la compilation : il n'y a donc qu'une seule fonction JavaScript à l'exécution. L'implémentation doit inspecter ses arguments (typeof, Array.isArray, arguments.length...) pour décider quoi faire. Le compilateur vérifie que les surcharges et l'implémentation concordent :

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 correction consiste à élargir l'implémentation : function format(value: string | number): string | number.

La signature d'implémentation n'est pas appelable

C'est la règle qui surprend le plus. Un appel doit correspondre à l'une des signatures de surcharge à elle seule ; TypeScript ne les combine pas.

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

Le compilateur affiche :

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'implémentation accepte string | string[], mais les appelants ne la voient pas. Ajoutez une troisième surcharge qui prend l'union et renvoie l'union, et l'appel compile et affiche [ 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);
}

Des nombres de paramètres différents

Les surcharges décrivent aussi des appels avec des nombres d'arguments différents. Ici, une date peut être construite à partir d'un timestamp ou d'une année, d'un mois et d'un jour, mais pas à partir de deux nombres :

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);

Une seule signature avec deux paramètres optionnels accepterait makeDate(2024, 3) et construirait en silence une mauvaise date. Les surcharges en font une erreur de compilation (TS2575).

L'ordre compte

TypeScript essaie les surcharges de haut en bas et choisit la première qui correspond. Placez les signatures les plus précises en premier. Une surcharge large placée tôt dans la liste avale les appels destinés à celles qui la suivent :

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"

Échangez les deux premières signatures et describe("hi") est typé "text".

Surcharges ou paramètre union ?

Les surcharges valent leurs lignes supplémentaires quand le type de retour dépend des types des arguments. Quand ce n'est pas le cas, une seule signature avec un paramètre union est plus courte, plus lisible, et accepte les arguments union que les surcharges refuseraient.

// 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 générique combiné à un type conditionnel peut exprimer certains ensembles de surcharges en une seule signature, mais pour deux ou trois cas, les surcharges sont en général plus lisibles.

Méthodes et constructeurs surchargés

Les méthodes utilisent le même motif dans une classe : des signatures de surcharge, puis la méthode avec son corps. Les constructeurs se surchargent de la même façon.

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

Les interfaces et les types objet peuvent aussi déclarer des surcharges, sous forme de plusieurs signatures d'appel ou de plusieurs signatures de méthode portant le même nom. Beaucoup de fonctions intégrées sont déclarées ainsi : survolez reduce sur un tableau dans un éditeur et il affiche « +2 overloads ».