Tuplas en TypeScript: sintaxis, nombres, opcionales y rest

Una tupla en TypeScript es un array con un número fijo de elementos, en el que cada posición tiene su propio tipo. [string, number] significa exactamente dos elementos: primero un string y después un número. Escribes los tipos entre corchetes en el orden en que aparecen los valores.

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

En tiempo de ejecución una tupla es un array normal de JavaScript. Todo lo que añade una tupla (la longitud fija y el tipo de cada posición) lo comprueba el compilador y después se borra.

Sintaxis de las tuplas

Cada forma se explica más abajo. Fíjate en el tipo de length: en una tupla fija es un tipo literal, así que el compilador sabe que pair.length es exactamente 2.

Qué comprueba el compilador

Un tipo tupla fija el número de elementos, su orden y el tipo de cada posición. Equivocarse en cualquiera de ellos es un error de compilación:

// 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 array normal nunca podría detectar el último: para string[], arr[2] es simplemente un string que en tiempo de ejecución resulta ser undefined.

Elementos con nombre

Las etiquetas documentan qué significa cada posición. No cambian nada del tipo ni de cómo se indexa, pero los editores las muestran al pasar el cursor y en las pistas de firma, lo que hace [number, number] mucho 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 TypeScript 5.2 puedes etiquetar unas posiciones y dejar otras sin etiqueta, como en [first: string, number]. Las etiquetas son solo para quien lee: [x: number, y: number] y [number, number] son el mismo tipo y se pueden asignar entre sí.

Elementos opcionales

Un ? después del tipo de un elemento hace opcional esa posición. Los elementos opcionales deben ir después de los obligatorios, y cada uno amplía el 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

Leer un elemento opcional da T | undefined, así que hace falta un valor por defecto en el patrón de desestructuración (a = 1) o una comprobación antes de hacer aritmética.

Elementos rest

Un elemento rest, ...T[], representa cualquier cantidad de elementos de tipo T. Puede ir al final, al principio o en medio, con uno como máximo 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

El length de una tupla con un elemento rest es number, porque el tamaño ya no es fijo. Lo que sigue fijo es dónde están las posiciones tipadas.

Tuplas readonly y as const

readonly [T, U] elimina push, pop, splice y la asignación por índice, que es lo que debe ser un valor de longitud fija. Escribir as const después de un array literal infiere una tupla readonly de tipos literales.

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] convierte la tupla en una unión de los tipos de sus elementos, un patrón que se explica en indexed access types. Una tupla readonly no se puede pasar a un parámetro tipado como tupla mutable, así que las funciones que solo leen deberían aceptar readonly [number, number].

La comprobación de readonly es solo en tiempo de compilación. En tiempo de ejecución el array no está congelado (la asignación de arriba se ejecutó de verdad, como muestra la salida), así que usa Object.freeze si necesitas una garantía en tiempo de ejecución.

Devolver una tupla desde una función

Devolver varios valores como tupla es como funciona useState de React (const [value, setValue] = useState(0)). El problema: un array literal en un return se infiere como array, no 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.

La función devuelve (number | (() => number))[], así que los dos nombres desestructurados reciben el tipo unión. Hay dos soluciones: anotar el tipo de retorno o añadir 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

Devolver una tupla permite a quien llama nombrar las partes como quiera. Cuando hay más de dos o tres valores, o el orden no es evidente, devuelve un objeto: { count, increment } se documenta solo.

Tuplas como parámetros de función

Un parámetro rest tipado como tupla describe una lista de argumentos completa, incluidos los argumentos opcionales. Así es como el tipo utilitario integrado Parameters<T> representa los parámetros de una función.

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

Expandir una tupla en una llamada comprueba el tipo de cada argumento por posición, algo que no podría hacer la expansión de un (string | number)[].

Tupla frente a array

Las tuplas también aparecen en tipos integrados. Object.entries(obj) devuelve [string, T][], y un Map se construye 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 ] ]

Una trampa: una tupla mutable sigue teniendo todos los métodos de array, así que pair.push(3) compila sobre un [string, number] y crea sin avisar un array de tres elementos cuyo tipo dice que tiene dos. Declarar las tuplas readonly cierra ese agujero. Y como los tipos se borran, los datos que vienen de fuera del programa (JSON, una API) no se comprueban contra un tipo tupla en tiempo de ejecución: valida su longitud y los tipos de sus elementos antes de fiarte de ellos.

Tuplas variádicas

Los tipos tupla pueden expandir otros tipos tupla, [...T, ...U]. Junto con los genéricos, esto permite tipar funciones que concatenan o anteponen elementos conservando cada posición:

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

Los tipos de las librerías también se apoyan en la inferencia de tuplas: Promise.all([fetchUser(), fetchPosts()]) se resuelve en una tupla con un tipo por cada promesa de entrada.