Paramètres optionnels, valeurs par défaut et rest en TypeScript

Ajoutez ? après le nom d'un paramètre pour le rendre optionnel. Les appelants peuvent l'omettre, et dans la fonction son type inclut undefined.

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScript vérifie le nombre d'arguments : sans le ?, le premier appel serait une erreur de compilation, Expected 2 arguments, but got 1. (TS2554).

Les paramètres optionnels peuvent valoir undefined

Comme un appelant peut l'omettre, le type d'un paramètre optionnel dans la fonction est T | undefined. Avec strictNullChecks, vous devez traiter le cas undefined avant de l'utiliser comme un T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

Le chaînage optionnel (?.) et la coalescence des nuls (??) sont les outils habituels ici. Quand la valeur de repli est fixe, un paramètre par défaut est plus court.

Valeurs par défaut des paramètres

Une valeur par défaut rend le paramètre optionnel pour les appelants et lui donne un type sans undefined dans la fonction. Le type est inféré à partir de la valeur par défaut, l'annotation est donc souvent inutile.

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

L'appelant voit la signature repeat(text: string, times?: number, separator?: string). Les valeurs par défaut suivent la règle de JavaScript : elles s'appliquent quand l'argument vaut undefined, qu'il soit omis ou passé explicitement, et pas quand il vaut null. Une expression par défaut peut utiliser les paramètres précédents : function range(start: number, end = start + 10).

Règles d'ordre des paramètres

Un paramètre avec valeur par défaut placé avant un paramètre obligatoire est légal mais maladroit. Son type pour les appelants devient number | undefined, et personne n'aime écrire undefined comme bouche-trou. Si vous avez besoin d'un premier paramètre flexible, utilisez plutôt un objet d'options ou la surcharge de fonctions.

Omis ou undefined

x?: number et x: number | undefined se ressemblent et ont le même type dans la fonction. Ils diffèrent pour l'appelant : le premier peut être omis, le second doit être passé.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

Utilisez | undefined pour un argument obligatoire qui peut ne pas avoir de valeur, afin que chaque appelant doive y réfléchir. Utilisez ? quand l'omettre est un appel normal. (Le message dit vraiment « 1 arguments » : c'est la formulation de TypeScript.)

Paramètres rest

Un paramètre rest, ...name: T[], rassemble un nombre quelconque d'arguments dans un tableau. Il doit être le dernier paramètre.

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

Étaler un tableau dans des paramètres fixes est plus strict. Un paramètre rest accepte l'étalement de n'importe quel number[], mais une fonction déclarée (a: number, b: number) n'accepte que l'étalement d'un tuple, car TypeScript doit connaître la longueur :

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

Un paramètre rest peut aussi avoir un type tuple, qui type chaque position : ...args: [name: string, age?: number].

Objets d'options

Dès qu'une fonction a plus de deux ou trois paramètres optionnels, les appelants perdent le fil des positions. Un objet d'options avec des valeurs par défaut donne des arguments nommés, dans n'importe quel ordre.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

Le = {} final rend l'objet entier optionnel. Sans lui, fetchData("/a") est une erreur de compilation (Expected 2 arguments, but got 1., TS2554), et en JavaScript pur le même appel lèverait une TypeError à l'exécution, car la déstructuration a besoin d'un objet à lire.

Paramètres optionnels dans les types de callbacks

Dans un type de fonction, ? signifie « celui qui appelle ce callback peut ne pas le passer ». Cela ne signifie pas « le callback peut l'ignorer » : un callback peut toujours ignorer les derniers paramètres. Ne marquez donc pas les paramètres d'un callback comme optionnels juste pour permettre aux gestionnaires de prendre moins d'arguments.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);