Tupla em TypeScript: sintaxe, elementos nomeados, opcionais e rest

Uma tupla em TypeScript é um array com um número fixo de elementos, em que cada posição tem seu próprio tipo. [string, number] significa exatamente dois elementos: primeiro uma string, depois um número. Você escreve os tipos entre colchetes na ordem em que os valores aparecem.

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

Em tempo de execução uma tupla é um array comum do JavaScript. Tudo o que a tupla acrescenta (o tamanho fixo e o tipo de cada posição) é verificado pelo compilador e depois apagado.

Sintaxe de tupla

Cada forma é explicada abaixo. Vale reparar no tipo de length: em uma tupla fixa ele é um tipo literal, então o compilador sabe que pair.length é exatamente 2.

O que o compilador verifica

Um tipo de tupla fixa a quantidade de elementos, a ordem deles e o tipo de cada posição. Errar qualquer um desses é erro de compilação:

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

Um array comum nunca pegaria o último: para string[], arr[2] é só uma string que por acaso é undefined em tempo de execução.

Elementos nomeados

Os rótulos documentam o que cada posição significa. Eles não mudam nada no tipo nem na forma de indexar, mas os editores os mostram ao passar o mouse e nas dicas de assinatura, o que torna [number, number] bem menos 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

Desde o TypeScript 5.2 você pode rotular algumas posições e deixar outras sem rótulo, como em [first: string, number]. Os rótulos são só para quem lê: [x: number, y: number] e [number, number] são o mesmo tipo e podem ser atribuídos um ao outro.

Elementos opcionais

Um ? depois do tipo de um elemento torna aquela posição opcional. Elementos opcionais precisam vir depois dos obrigatórios, e cada um amplia o tipo 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

Ler um elemento opcional dá T | undefined, então é preciso um valor padrão na desestruturação (a = 1) ou uma verificação antes de fazer contas.

Elementos rest

Um elemento rest, ...T[], representa qualquer quantidade de elementos do tipo T. Ele pode ficar no fim, no início ou no meio, com no máximo um por tupla.

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

O length de uma tupla com elemento rest é number, já que o tamanho deixa de ser fixo. O que continua fixo é onde ficam as posições tipadas.

Tuplas readonly e as const

readonly [T, U] remove push, pop, splice e a atribuição por índice, que é o que se espera de um valor de tamanho fixo. Escrever as const depois de um array literal infere uma tupla readonly de tipos literais.

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] transforma a tupla em uma union dos tipos dos seus elementos, um padrão explicado em indexed access types. Uma tupla readonly não pode ser passada para um parâmetro tipado como tupla mutável, então funções que só leem devem aceitar readonly [number, number].

A verificação de readonly só existe em tempo de compilação. Em tempo de execução o array não está congelado (a atribuição acima rodou de verdade, como mostra a saída), então use Object.freeze se precisar de uma garantia em tempo de execução.

Retornando uma tupla de uma função

Retornar vários valores como uma tupla é como o useState do React funciona (const [value, setValue] = useState(0)). O problema: um array literal em um return é inferido como array, não como tupla.

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

A função retorna (number | (() => number))[], então os dois nomes desestruturados recebem o tipo union. Há duas correções: anotar o tipo de retorno ou adicionar 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

Um retorno em tupla deixa quem chama dar o nome que quiser a cada parte. Quando há mais de dois ou três valores, ou a ordem não é óbvia, retorne um objeto: { count, increment } se documenta sozinho.

Tuplas como parâmetros de função

Um parâmetro rest tipado como tupla descreve uma lista inteira de argumentos, inclusive os opcionais. É assim que o utility type nativo Parameters<T> representa os parâmetros de uma função.

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

Espalhar uma tupla em uma chamada verifica o tipo de cada argumento pela posição, algo que um spread de (string | number)[] não conseguiria.

Tupla vs array

Tuplas também aparecem nos tipos nativos. Object.entries(obj) retorna [string, T][], e um Map é construído a partir de tuplas [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 ] ]

Uma armadilha: uma tupla mutável ainda tem todos os métodos de array, então pair.push(3) compila em um [string, number] e cria silenciosamente um array de três elementos cujo tipo diz dois. Declarar tuplas como readonly fecha essa brecha. E como os tipos são apagados, dados de fora do programa (JSON, uma API) não são verificados contra um tipo de tupla em tempo de execução: valide o tamanho e os tipos dos elementos antes de confiar neles.

Variadic tuple types

Tipos de tupla podem espalhar outros tipos de tupla, [...T, ...U]. Combinado com generics, isso tipa funções que concatenam ou adicionam elementos no início mantendo cada posição:

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

Os tipos de bibliotecas também dependem da inferência de tuplas: Promise.all([fetchUser(), fetchPosts()]) resolve para uma tupla com um tipo por promise de entrada.