Types de fonctions en TypeScript : syntaxe fléchée et callbacks

Un type de fonction décrit les paramètres et la valeur de retour d'une fonction, et s'écrit avec une flèche : (a: number, b: number) => number. Nommez-le avec type et vous pourrez l'utiliser pour des variables, des paramètres et des propriétés d'objets.

type Operation = (a: number, b: number) => number;

const add: Operation = (a, b) => a + b;       // a and b are number
const multiply: Operation = (x, y) => x * y;  // names do not have to match

function apply(op: Operation, a: number, b: number): number {
  return op(a, b);
}

console.log(apply(add, 2, 3));      // 5
console.log(apply(multiply, 2, 3)); // 6

La fonction assignée à add n'a besoin d'aucune annotation : les types de ses paramètres viennent d'Operation. C'est ce qu'on appelle le typage contextuel, et c'est la principale raison de nommer les types de fonctions.

Syntaxe des types de fonctions

La forme est (parameters) => ReturnType. Chaque paramètre demande un nom et un type. Les noms servent à la lisibilité et aux indications de l'éditeur ; toute fonction dont les types de paramètres sont compatibles correspond, quels que soient leurs noms.

type Predicate = (value: number) => boolean;
type Formatter = (value: number, digits?: number) => string; // optional parameter
type Logger = (...parts: string[]) => void;                    // rest parameter
type Factory = () => { id: number };                           // no parameters

Le nom n'est pas facultatif. (string) => void déclare un paramètre appelé string sans type, et le mode strict le refuse avec TS7051: Parameter has a name but no type. Did you mean 'arg0: string'?. Écrivez (value: string) => void.

Typer les fonctions fléchées

Une fonction fléchée peut se typer de deux façons. Annotez la fonction elle-même, ou annotez la variable avec un type de fonction et laissez les paramètres être inférés.

// 1. Annotations on the function
const toCelsius = (f: number): number => ((f - 32) * 5) / 9;

// 2. A function type on the variable
const toFahrenheit: (c: number) => number = (c) => (c * 9) / 5 + 32;

// 3. The same, with a named type
type Convert = (value: number) => number;
const round1: Convert = (v) => Math.round(v * 10) / 10;

console.log(round1(toCelsius(100)));  // 37.8
console.log(toFahrenheit(37));        // 98.6

La forme 1 est le choix habituel pour une fonction autonome. La forme 3 devient rentable quand plusieurs fonctions partagent une même signature (gestionnaires, comparateurs, convertisseurs), car la signature n'est écrite qu'une fois et toute modification est vérifiée partout.

Types de callbacks

Un paramètre dont le type est un type de fonction est un callback. La fonction de l'appelant est vérifiée par rapport à lui, et ses paramètres en sont inférés.

function repeat(times: number, action: (index: number) => void): void {
  for (let i = 0; i < times; i++) action(i);
}

repeat(3, (i) => console.log("run", i));

function mapValues(values: number[], fn: (value: number, index: number) => string): string[] {
  const out: string[] = [];
  values.forEach((v, i) => out.push(fn(v, i)));
  return out;
}

// A callback may ignore trailing parameters: this one takes only value.
console.log(mapValues([1.5, 2.25], (v) => v.toFixed(1))); // [ '1.5', '2.3' ]

Deux règles rendent les callbacks agréables à utiliser :

• Moins de paramètres, c'est permis. Une fonction qui prend un paramètre peut être passée là où deux sont proposés. JavaScript ignore les arguments en trop, donc TypeScript l'autorise. Plus de paramètres que ce que propose le type est une erreur (Target signature provides too few arguments.).
• Un retour void accepte tout. Un callback typé (...) => void peut renvoyer une valeur ; l'appelant promet de ne pas l'utiliser. C'est pourquoi list.forEach((x) => other.push(x)) compile alors que push renvoie un nombre.

Les types des paramètres doivent tout de même être compatibles. Passer (x: string) => ... là où (a: number, b: number) => number est attendu échoue avec Types of parameters 'x' and 'a' are incompatible.

Signatures d'appel

(n: number) => string est un raccourci pour un type objet avec une signature d'appel : { (n: number): string }. La forme longue est nécessaire quand la fonction porte aussi des propriétés.

type Counter = {
  (): number;        // call signature: calling it returns a number
  count: number;     // and it has a property
  reset: () => void; // and a method
};

function makeCounter(): Counter {
  const fn = () => ++fn.count;
  fn.count = 0;
  fn.reset = () => { fn.count = 0; };
  return fn;
}

const next = makeCounter();
next();
next();
console.log(next(), next.count); // 3 3
next.reset();
console.log(next.count);         // 0

TypeScript vous permet d'ajouter des propriétés à une fonction déclarée avec const dans la même portée, et les suit dans le type de la fonction. Une interface peut aussi contenir une signature d'appel : interface Counter { (): number; count: number }.

Une signature de construction décrit quelque chose qu'on appelle avec new. Elle ajoute new devant : new (name: string) => User, ou { new (name: string): User } sous forme objet. C'est ainsi qu'on type un paramètre qui reçoit une classe.

Syntaxe méthode ou syntaxe propriété

Dans un type objet, un membre fonction peut s'écrire comme une méthode, handle(value: string): void, ou comme une propriété contenant une fonction, handle: (value: string) => void. Ils semblent interchangeables mais sont vérifiés différemment avec strict :

// This does not compile: the property form checks parameters strictly.
interface WithMethod { handle(value: string | number): void }
interface WithProperty { handle: (value: string | number) => void }

const onlyStrings = (value: string) => console.log(value.toUpperCase());

const a: WithMethod = { handle: onlyStrings };   // accepted
const b: WithProperty = { handle: onlyStrings }; // rejected
a.handle(42);

Le compilateur signale :

index.ts(8,27): error TS2322: Type '(value: string) => void' is not assignable to type '(value: string | number) => void'.
  Types of parameters 'value' and 'value' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.

L'erreur est justifiée : onlyStrings ne sait pas traiter un nombre. La forme méthode laisse passer la même erreur (les paramètres de méthode sont vérifiés de façon « bivariante » pour des raisons historiques), et a.handle(42) planterait à l'exécution avec TypeError: value.toUpperCase is not a function. Supprimez la ligne b pour voir ce plantage. Quand vous écrivez vos propres types objet, la forme propriété détecte davantage d'erreurs.

Évitez le type Function

Function est le type intégré auquel satisfait toute valeur de fonction. Ce n'est presque jamais ce que vous voulez : TypeScript ne connaît ni les paramètres ni le type de retour, donc chaque appel est accepté et renvoie any.

const loose: Function = Math.max;
const result = loose("a", {});   // compiles: any arguments, result is any
console.log(result);             // NaN

const strict: (...values: number[]) => number = Math.max;
console.log(strict(3, 9, 4));    // 9
// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
strict("a");

Remplacez Function par la vraie signature. Quand vous acceptez vraiment n'importe quelle fonction (un debounce générique, un wrapper de journalisation), (...args: never[]) => unknown accepte toutes les fonctions tout en gardant le résultat unknown au lieu de any. Pour les fonctions dont les types dépendent de leur entrée, voir génériques : un type de fonction générique ressemble à <T>(value: T) => T.