Tuple in TypeScript: sintassi, elementi con nome, opzionali e rest

Una tuple in TypeScript è un array con un numero fisso di elementi, in cui ogni posizione ha il proprio tipo. [string, number] significa esattamente due elementi: prima una stringa, poi un numero. Scrivi i tipi tra parentesi quadre nell'ordine in cui compaiono i valori.

// 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

A runtime una tuple è un semplice array JavaScript. Tutto ciò che una tuple aggiunge (la lunghezza fissa e il tipo in ogni posizione) viene controllato dal compilatore e poi eliminato.

Sintassi delle tuple

Ogni forma è spiegata più avanti. Vale la pena notare il tipo di length: per una tuple fissa è un tipo letterale, quindi il compilatore sa che pair.length è esattamente 2.

Cosa controlla il compilatore

Un tipo tuple fissa il numero di elementi, il loro ordine e il tipo in ogni posizione. Sbagliarne uno qualsiasi è un errore di compilazione:

// 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 semplice array non potrebbe mai intercettare l'ultimo: per string[], arr[2] è semplicemente una string che a runtime si rivela undefined.

Elementi con nome

Le etichette documentano il significato di ogni posizione. Non cambiano nulla del tipo né del modo di indicizzarlo, ma gli editor le mostrano al passaggio del mouse e nei suggerimenti della firma, e così [number, number] diventa molto meno misterioso.

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

Da TypeScript 5.2 puoi etichettare alcune posizioni e lasciarne altre senza etichetta, come in [first: string, number]. Le etichette servono solo a chi legge: [x: number, y: number] e [number, number] sono lo stesso tipo e assegnabili l'uno all'altro.

Elementi opzionali

Un ? dopo il tipo di un elemento rende opzionale quella posizione. Gli elementi opzionali devono venire dopo quelli obbligatori, e ognuno allarga il tipo di 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

Leggere un elemento opzionale dà T | undefined, quindi serve un valore predefinito nel pattern di destrutturazione (a = 1) o un controllo prima di fare calcoli.

Elementi rest

Un elemento rest, ...T[], rappresenta un numero qualsiasi di elementi di tipo T. Può stare alla fine, all'inizio o in mezzo, al massimo uno per 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 di una tuple con un elemento rest è number, perché la dimensione non è più fissa. Ciò che resta fisso è la posizione degli elementi tipizzati.

Tuple readonly e as const

readonly [T, U] toglie push, pop, splice e l'assegnazione tramite indice, cioè ciò che un valore di lunghezza fissa dovrebbe essere. Scrivere as const dopo un array letterale deduce una tuple readonly di tipi letterali.

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] trasforma la tuple in una union dei tipi dei suoi elementi, un pattern trattato negli indexed access types. Una tuple readonly non si può passare a un parametro tipizzato come tuple modificabile, quindi le funzioni che si limitano a leggere dovrebbero accettare readonly [number, number].

Il controllo readonly esiste solo in fase di compilazione. A runtime l'array non è congelato (l'assegnazione qui sopra è stata davvero eseguita, come mostra l'output), quindi usa Object.freeze se ti serve una garanzia a runtime.

Restituire una tuple da una funzione

Restituire più valori come tuple è il modo in cui funziona useState di React (const [value, setValue] = useState(0)). Il problema: un array letterale in un return viene dedotto come array, non come 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 funzione restituisce (number | (() => number))[], quindi entrambi i nomi destrutturati ricevono il tipo union. Ci sono due soluzioni: annotare il tipo di ritorno, oppure aggiungere 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

Un valore di ritorno tuple permette a chi chiama la funzione di dare alle parti il nome che preferisce. Quando i valori sono più di due o tre, o l'ordine non è ovvio, restituisci un oggetto: { count, increment } si documenta da solo.

Tuple come parametri di funzione

Un parametro rest tipizzato come tuple descrive un'intera lista di argomenti, compresi quelli opzionali. È così che l'utility type integrato Parameters<T> rappresenta i parametri di una funzione.

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

Lo spread di una tuple in una chiamata controlla ogni argomento per posizione, cosa che lo spread di un (string | number)[] non potrebbe fare.

Tuple e array a confronto

Le tuple compaiono anche nei tipi integrati. Object.entries(obj) restituisce [string, T][], e una Map si costruisce da tuple [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 ] ]

Una trappola: una tuple modificabile ha comunque tutti i metodi degli array, quindi pair.push(3) compila su una [string, number] e crea in silenzio un array di tre elementi il cui tipo ne dichiara due. Dichiarare le tuple readonly chiude questa falla. E poiché i tipi vengono eliminati, i dati che arrivano da fuori dal programma (JSON, un'API) non vengono controllati rispetto a un tipo tuple a runtime: verifica la lunghezza e i tipi degli elementi prima di fidarti.

Variadic tuple types

I tipi tuple possono fare lo spread di altri tipi tuple, [...T, ...U]. Insieme ai generics, questo permette di tipizzare funzioni che concatenano o antepongono elementi mantenendo ogni posizione:

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);

Anche i tipi delle librerie si appoggiano all'inferenza delle tuple: Promise.all([fetchUser(), fetchPosts()]) si risolve in una tuple con un tipo per ogni promise in ingresso.