Surcharge de fonctions TypeScript : guide 2025 avec exemples

TypeScript Function Overloading : pourquoi ce n'est pas de la « magie », mais un outil pour un code intelligent

Si vous avez déjà écrit en JavaScript une fonction qui accepte « tantôt une chaîne, tantôt un nombre, voire un tableau », vous connaissez ce moment désagréable : à l'intérieur de la fonction, c'est l'enfer des if, et à l'extérieur, une totale incertitude pour celui qui appelle cette fonction. TypeScript résout ce problème avec élégance, mais pas toujours de manière évidente. La surcharge de fonctions (function overloading) ne consiste pas à créer plusieurs fonctions portant le même nom (comme en Java ou C++). Il s'agit de déclarer plusieurs signatures pour une seule implémentation.

En 2025, alors que TypeScript est devenu le standard de facto pour les projets front-end et back-end sérieux, savoir configurer correctement la surcharge n'est pas un « gadget », mais une compétence qui rend votre code lisible, type-safe et pratique pour l'équipe. Voyons comment cela fonctionne, ce qui piège les débutants et quels patterns adopter.

Qu'est-ce que la surcharge de fonctions en réalité ?

Imaginez que vous écrivez une fonction formatDate. Elle doit pouvoir :

\n
• Accepter un objet Date et retourner une chaîne.
\n
• Accepter une chaîne au format ISO et retourner une chaîne.
\n
• Accepter un nombre (timestamp) et retourner une chaîne.
\n

Si vous écrivez simplement function formatDate(input: Date | string | number): string, TypeScript ne pourra pas vous indiquer quel type vous passez dans un appel spécifique. L'IDE affichera un type générique, et vous perdrez l'autocomplétion. La surcharge résout ce problème :

// Signatures de surcharge (overload signatures)\nfunction formatDate(input: Date): string;\nfunction formatDate(input: string): string;\nfunction formatDate(input: number): string;\n\n// Implémentation (implementation signature)\nfunction formatDate(input: Date | string | number): string {\n    if (input instanceof Date) {\n        return input.toISOString();\n    } else if (typeof input === 'string') {\n        return new Date(input).toISOString();\n    } else {\n        return new Date(input).toISOString();\n    }\n}

Maintenant, lorsque vous appelez formatDate(new Date()), TypeScript sait qu'il retourne string et vous suggère les types. Pas de magie : juste une typisation stricte.

Règle n°1 : les signatures de surcharge ne peuvent pas être des implémentations

L'erreur la plus fréquente chez les débutants est d'essayer d'écrire le corps de la fonction dans chaque signature. Ne faites pas ceci :

// ❌ Erreur : duplication de l'implémentation\nfunction foo(x: number): number {\n    return x * 2;\n}\nfunction foo(x: string): string {\n    return x.toUpperCase();\n}

TypeScript ne prend pas en charge plusieurs implémentations avec le même nom. Toujours une seule implémentation, plusieurs déclarations.

Règle n°2 : l'ordre des signatures a son importance

TypeScript vérifie les signatures de haut en bas. La première signature correspondante détermine le type de retour. Par conséquent :

\n
• Placez les types les plus spécifiques en premier (par exemple, string avant any).
\n
• Évitez les signatures qui se chevauchent et pourraient tromper le compilateur.
\n

// Bien : d'abord le cas spécifique\nfunction createButton(label: string, disabled?: boolean): HTMLButtonElement;\nfunction createButton(options: { label: string; disabled?: boolean }): HTMLButtonElement;\nfunction createButton(labelOrOptions: string | { label: string; disabled?: boolean }, disabled?: boolean): HTMLButtonElement {\n    // implémentation\n}

Règle n°3 : utilisez les Union Types si vous avez plus de 3 signatures

La surcharge est un outil puissant, mais n'en abusez pas. Si vous avez 5 signatures ou plus, le code devient illisible. En 2025, une bonne pratique consiste à :

\n
• Jusqu'à 3 signatures — utilisez la surcharge.
\n
• Plus de 3 — envisagez un Union Type ou une