Tuple en TypeScript : syntaxe, éléments nommés, optionnels et rest

Un tuple TypeScript est un tableau au nombre d'éléments fixe, où chaque position a son propre type. [string, number] signifie exactement deux éléments : d'abord une chaîne, puis un nombre. Vous écrivez les types entre crochets, dans l'ordre où les valeurs apparaissent.

// A tuple type: position 0 is a string, position 1 is a number
let user: [string, number] = ["Ada", 36];

const userName = user[0]; // string
const age = user[1];      // number
console.log(userName.toUpperCase(), age + 1); // ADA 37

// Destructuring gives each element its own type
const [n, a] = user;
console.log(`${n} is ${a}`); // Ada is 36

user = ["Grace", 85];     // fine: same shape
console.log(user, user.length); // [ 'Grace', 85 ] 2

À l'exécution, un tuple est un simple tableau JavaScript. Tout ce qu'apporte un tuple (la longueur fixe et le type à chaque position) est vérifié par le compilateur, puis effacé.

Syntaxe des tuples

Chaque forme est expliquée plus bas. Le type de length mérite l'attention : pour un tuple fixe, c'est un type littéral, le compilateur sait donc que pair.length vaut exactement 2.

Ce que vérifie le compilateur

Un type tuple fixe le nombre d'éléments, leur ordre et le type à chaque position. Se tromper sur l'un d'eux est une erreur de compilation :

// This does not compile: wrong length, wrong order, index out of range.
const tooShort: [string, number] = ["Ada"];
const swapped: [string, number] = [36, "Ada"];
const ok: [string, number] = ["Ada", 36];
console.log(ok[2]);

index.ts(2,7): error TS2322: Type '[string]' is not assignable to type '[string, number]'.
  Source has 1 element(s) but target requires 2.
index.ts(3,36): error TS2322: Type 'number' is not assignable to type 'string'.
index.ts(3,40): error TS2322: Type 'string' is not assignable to type 'number'.
index.ts(5,16): error TS2493: Tuple type '[string, number]' of length '2' has no element at index '2'.

Un simple tableau ne pourrait jamais détecter le dernier cas : pour string[], arr[2] est simplement un string qui se trouve valoir undefined à l'exécution.

Éléments nommés

Les étiquettes documentent le sens de chaque position. Elles ne changent rien au type ni à l'accès par indice, mais les éditeurs les affichent au survol et dans les indications de signature, ce qui rend [number, number] bien moins mystérieux.

type Point = [x: number, y: number];
type Span = [start: number, end: number];
type HttpResult = [status: number, body: string];

function distance([x1, y1]: Point, [x2, y2]: Point): number {
    return Math.hypot(x2 - x1, y2 - y1);
}

const start: Point = [0, 0];
console.log(distance(start, [3, 4])); // 5

const result: HttpResult = [404, "Not Found"];
const [code, text] = result;
console.log(code, text); // 404 Not Found

Depuis TypeScript 5.2, vous pouvez étiqueter certaines positions et pas d'autres, comme dans [first: string, number]. Les étiquettes ne servent qu'aux lecteurs : [x: number, y: number] et [number, number] sont le même type et assignables l'un à l'autre.

Éléments optionnels

Un ? après le type d'un élément rend cette position optionnelle. Les éléments optionnels doivent venir après les éléments obligatoires, et chacun élargit le type de length.

type Rgb = [red: number, green: number, blue: number, alpha?: number];

const solid: Rgb = [255, 128, 0];
const faded: Rgb = [255, 128, 0, 0.5];

function toCss([r, g, b, a = 1]: Rgb): string {
    return `rgba(${r}, ${g}, ${b}, ${a})`;
}

console.log(toCss(solid)); // rgba(255, 128, 0, 1)
console.log(toCss(faded)); // rgba(255, 128, 0, 0.5)

const alpha = faded[3];   // number | undefined
const len = solid.length; // 3 | 4
console.log(alpha, len);  // 0.5 3

Lire un élément optionnel donne T | undefined : une valeur par défaut dans le motif de déstructuration (a = 1) ou une vérification est nécessaire avant tout calcul.

Éléments rest

Un élément rest, ...T[], représente un nombre quelconque d'éléments de type T. Il peut se trouver à la fin, au début ou au milieu, avec au plus un par tuple.

// A label, then any number of scores
type Row = [name: string, ...scores: number[]];
const rows: Row[] = [["Ada", 90, 85], ["Grace", 77], ["Alan"]];

for (const [name, ...scores] of rows) {
    const avg = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 0;
    console.log(name, scores, avg);
}

// Any number of strings, then a number at the end
type PathAndSize = [...segments: string[], bytes: number];
const file: PathAndSize = ["home", "ada", "notes.txt", 2048];
console.log(file.at(-1)); // 2048

La length d'un tuple avec un élément rest est number, puisque la taille n'est plus fixe. Ce qui reste fixe, c'est l'emplacement des positions typées.

Tuples readonly et as const

readonly [T, U] retire push, pop, splice et l'assignation par indice, ce qui correspond bien à une valeur de longueur fixe. Écrire as const après un littéral de tableau infère un tuple readonly de types littéraux.

const pair: readonly [string, number] = ["x", 1];
// @ts-expect-error: Cannot assign to '0' because it is a read-only property.
pair[0] = "y";
console.log(pair); // [ 'y', 1 ]: not frozen at runtime

// as const: a readonly tuple with the exact literal values
const corner = [10, 20] as const; // readonly [10, 20]
const [cx, cy] = corner;          // cx: 10, cy: 20
console.log(cx + cy);             // 30

// Useful for fixed lists of allowed values
const SIZES = ["small", "medium", "large"] as const;
type Size = (typeof SIZES)[number]; // "small" | "medium" | "large"
const pick: Size = "medium";
console.log(SIZES.length, pick);   // 3 medium

(typeof SIZES)[number] transforme le tuple en union des types de ses éléments, un motif présenté sur la page des types d'accès indexé. Un tuple readonly ne peut pas être passé à un paramètre typé comme tuple modifiable, les fonctions qui se contentent de lire devraient donc accepter readonly [number, number].

La vérification readonly n'a lieu qu'à la compilation. À l'exécution, le tableau n'est pas gelé (l'assignation ci-dessus a bien eu lieu, comme le montre la sortie) : utilisez Object.freeze si vous avez besoin d'une garantie à l'exécution.

Renvoyer un tuple depuis une fonction

Renvoyer plusieurs valeurs sous forme de tuple, c'est le fonctionnement du useState de React (const [value, setValue] = useState(0)). Le piège : un littéral de tableau dans un return est inféré comme un tableau, pas comme un tuple.

// This does not compile: the return type was inferred as an array.
function useCounter(start: number) {
    let count = start;
    const increment = () => ++count;
    return [count, increment];
}

const [count, increment] = useCounter(10);
console.log(count + 1);
increment();

index.ts(9,13): error TS2365: Operator '+' cannot be applied to types 'number | (() => number)' and 'number'.
index.ts(10,1): error TS2349: This expression is not callable.
  Not all constituents of type 'number | (() => number)' are callable.
    Type 'number' has no call signatures.

La fonction renvoie (number | (() => number))[], donc les deux noms déstructurés reçoivent le type union. Il y a deux corrections : annoter le type de retour, ou ajouter as const.

// Fix 1: annotate the return type as a tuple
function useCounter(start: number): [number, () => number] {
    let count = start;
    return [count, () => ++count];
}

// Fix 2: as const infers readonly [boolean, () => boolean]
function useToggle(initial: boolean) {
    let on = initial;
    return [on, () => (on = !on)] as const;
}

const [count, increment] = useCounter(10);
console.log(count + 1, increment()); // 11 11

const [on, toggle] = useToggle(false);
console.log(on, toggle(), toggle()); // false true false

Une valeur de retour en tuple laisse les appelants nommer les parties comme ils le veulent. Quand il y a plus de deux ou trois valeurs, ou que l'ordre n'est pas évident, renvoyez plutôt un objet : { count, increment } se documente tout seul.

Les tuples comme paramètres de fonction

Un paramètre rest typé par un tuple décrit toute une liste d'arguments, arguments optionnels compris. C'est ainsi que le type utilitaire intégré Parameters<T> représente les paramètres d'une fonction.

function greet(...args: [name: string, times?: number]) {
    const [name, times = 1] = args;
    console.log(Array(times).fill(`Hi ${name}`).join(", "));
}

greet("Ada");     // Hi Ada
greet("Ada", 2);  // Hi Ada, Hi Ada

type GreetArgs = Parameters<typeof greet>; // [name: string, times?: number | undefined]
const saved: GreetArgs = ["Grace", 3];
greet(...saved); // Hi Grace, Hi Grace, Hi Grace

Étaler un tuple dans un appel vérifie chaque argument selon sa position, ce qu'un étalement de (string | number)[] ne pourrait pas faire.

Tuple ou tableau

Les tuples apparaissent aussi dans les types intégrés. Object.entries(obj) renvoie [string, T][], et une Map se construit à partir de tuples [key, value] :

const stock = { apples: 3, pears: 0 };

for (const [fruit, qty] of Object.entries(stock)) { // [string, number]
    console.log(fruit, qty > 0 ? "in stock" : "sold out");
}

const prices = new Map<string, number>([["tea", 2.5], ["coffee", 3.2]]);
const entries: [string, number][] = [...prices];
console.log(entries); // [ [ 'tea', 2.5 ], [ 'coffee', 3.2 ] ]

Un piège : un tuple modifiable possède toujours toutes les méthodes de tableau, donc pair.push(3) compile sur un [string, number] et crée discrètement un tableau de trois éléments dont le type en annonce deux. Déclarer les tuples readonly ferme cette brèche. Et comme les types sont effacés, les données venues de l'extérieur du programme (JSON, une API) ne sont pas vérifiées par rapport à un type tuple à l'exécution : validez leur longueur et le type de leurs éléments avant de leur faire confiance.

Types tuple variadiques

Les types tuple peuvent étaler d'autres types tuple, [...T, ...U]. Combiné aux génériques, cela permet de typer des fonctions qui concatènent ou ajoutent en tête tout en conservant chaque position :

function concat<T extends unknown[], U extends unknown[]>(a: [...T], b: [...U]): [...T, ...U] {
    return [...a, ...b];
}

const joined = concat([1, "a"], [true]); // [number, string, boolean]
const [num, str, flag] = joined;
console.log(num.toFixed(1), str.toUpperCase(), !flag); // 1.0 A false

type WithId<T extends unknown[]> = [id: number, ...rest: T];
const row: WithId<[string, boolean]> = [7, "Ada", true];
console.log(row);

Les types des bibliothèques s'appuient eux aussi sur l'inférence de tuples : Promise.all([fetchUser(), fetchPosts()]) se résout en un tuple avec un type par promesse en entrée.