Fonctions en TypeScript : types des paramètres et du retour, void

Une fonction TypeScript est une fonction JavaScript avec des types sur ses paramètres et, si vous le souhaitez, sur sa valeur de retour. Chaque paramètre reçoit une annotation, le type de retour se place après la liste des paramètres, et le compilateur vérifie chaque appel par rapport aux deux.

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

Les deux mauvais appels sont des erreurs de compilation (TS2345 et TS2554). Les commentaires // @ts-expect-error indiquent au compilateur qu'une erreur est attendue à la ligne suivante, si bien que le reste du fichier s'exécute quand même. Retirez-en un et relancez pour voir le vrai message.

Types des paramètres

Chaque paramètre s'écrit name: Type. Avec strict, activé par défaut dans TypeScript 7, un paramètre sans annotation et sans contexte d'inférence est une erreur : Parameter 'x' implicitly has an 'any' type. (TS7006). En pratique, chaque paramètre d'une fonction autonome est donc annoté.

N'importe quel type peut servir de type de paramètre : primitives, tableaux, types objet, unions, autres fonctions.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

TypeScript vérifie aussi le nombre d'arguments. En passer plus ou moins que ce que déclare la fonction est une erreur, contrairement au JavaScript pur, qui remplit les manquants avec undefined et ignore les surplus. Pour rendre un paramètre optionnel ou lui donner une valeur par défaut, voir paramètres optionnels.

Types de retour : annoter ou inférer

Le type de retour suit la parenthèse fermante : function f(): Type. Il est facultatif. Sans lui, TypeScript infère le type à partir de chaque return du corps.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

Une annotation se justifie quand la fonction est exportée, quand elle a plusieurs chemins de retour, ou quand elle est récursive. L'erreur apparaît alors dans la fonction, au mauvais return, et non chez un appelant. Un cas classique est une branche qui oublie de renvoyer une valeur :

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

Le compilateur signale index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Ajoutez un return "C"; final et le code s'exécute. Sans l'annotation : string, la fonction compilerait avec le type inféré "A" | "B" | undefined, et le problème se déplacerait chez celui qui utilise le résultat.

void : les fonctions qui ne renvoient rien

Une fonction qui se contente d'agir (journaliser, écrire, modifier) a le type de retour void. C'est ce que TypeScript infère quand il n'y a pas de return avec une valeur, et vous pouvez l'écrire explicitement.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

Ces règles sur void surprennent :

La deuxième ligne est voulue. C'est pourquoi arr.forEach(x => list.push(x)) compile alors que push renvoie un nombre. void dans un type de fonction signifie « quoi que cela renvoie, personne ne le lit ». Pour une fonction qui ne se termine jamais (elle lève toujours une exception ou boucle indéfiniment), le type de retour est never.

Fonctions fléchées et expressions de fonction

Les fonctions fléchées et les expressions de fonction prennent les mêmes annotations. Le type de retour se place après la liste des paramètres, avant =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

Sans les parenthèses, (x, y) => { x, y } est un bloc sans return, et la fonction renvoie undefined. Les règles d'exécution des fonctions fléchées (pas de this propre, pas d'arguments) sont les mêmes qu'en JavaScript ; voir les fonctions fléchées en JavaScript.

Quand une fonction est écrite directement comme argument, vous n'annotez en général pas du tout ses paramètres. TypeScript sait ce que reçoit le callback grâce à la fonction à laquelle il est passé (typage contextuel) : dans [1, 2].map(n => n * 2), n est déjà un number. L'écriture du type d'une fonction en tant que valeur, (n: number) => string, est présentée dans types de fonctions.

Renvoyer plusieurs valeurs

Une fonction renvoie une seule valeur : renvoyez donc un objet ou un tuple, et déstructurez-le.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

Le type de retour tuple a besoin de l'annotation. Sans elle, [a, b] est inféré comme string[] : la déstructuration fonctionne toujours, mais le type n'indique plus qu'il y a exactement deux éléments.

Fonctions async

Une fonction async renvoie toujours une Promise. Annotez le type de retour comme Promise<T>, où T est ce que la fonction renvoie à l'intérieur.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

Écrire async function f(): number est une erreur : The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

Le paramètre this

JavaScript décide de this au moment de l'appel. TypeScript vous permet de déclarer ce que doit être this grâce à un faux premier paramètre nommé this. Il est retiré du JavaScript compilé et les appelants ne le passent pas.

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

Sans le paramètre this, this dans une fonction autonome est un any implicite et le mode strict signale 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). Dans les méthodes de classe, this est déjà typé comme l'instance de la classe : le paramètre sert donc surtout pour les fonctions autonomes rattachées à des objets et pour les callbacks que des bibliothèques appellent avec un this précis.