Кортежи (tuple) в TypeScript: именованные и опциональные

Кортеж в TypeScript это массив с фиксированным числом элементов, в котором у каждой позиции свой тип. [string, number] означает ровно два элемента: сначала строка, затем число. Типы пишутся в квадратных скобках в том порядке, в котором идут значения.

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

Во время выполнения кортеж это обычный массив JavaScript. Всё, что добавляет кортеж (фиксированная длина и тип на каждой позиции), проверяется компилятором и стирается.

Синтаксис кортежей

Каждая форма разобрана ниже. Стоит обратить внимание на тип length: у фиксированного кортежа это литеральный тип, поэтому компилятор знает, что pair.length равно ровно 2.

Что проверяет компилятор

Тип кортежа фиксирует количество элементов, их порядок и тип на каждой позиции. Ошибка в любом из них даёт ошибку компиляции:

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

Обычный массив последнюю ошибку никогда бы не поймал: для string[] выражение arr[2] просто имеет тип string, а во время выполнения оказывается undefined.

Именованные элементы кортежа

Метки описывают, что означает каждая позиция. Они никак не меняют тип и способ индексации, но редакторы показывают их во всплывающих подсказках и подсказках сигнатур, и [number, number] становится гораздо понятнее.

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

Начиная с TypeScript 5.2 можно пометить одни позиции и оставить другие без меток, как в [first: string, number]. Метки нужны только читателям: [x: number, y: number] и [number, number] это один и тот же тип, и они присваиваются друг другу.

Опциональные элементы

? после типа элемента делает позицию опциональной. Опциональные элементы должны идти после обязательных, и каждый из них расширяет тип 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

Чтение опционального элемента даёт T | undefined, поэтому перед арифметикой нужно значение по умолчанию в шаблоне деструктуризации (a = 1) или проверка.

Rest-элементы

Rest-элемент, ...T[], обозначает любое количество элементов типа T. Он может стоять в конце, в начале или в середине, но в кортеже может быть только один.

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

length кортежа с rest-элементом имеет тип number, потому что размер больше не фиксирован. Фиксированным остаётся расположение типизированных позиций.

Readonly-кортежи и as const

readonly [T, U] убирает push, pop, splice и присвоение по индексу, то есть делает то, чем и должно быть значение фиксированной длины. as const после литерала массива выводит readonly-кортеж литеральных типов.

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] превращает кортеж в объединение типов его элементов; этот приём описан на странице индексированные типы доступа. Readonly-кортеж нельзя передать в параметр с типом изменяемого кортежа, поэтому функции, которые только читают, должны принимать readonly [number, number].

Проверка readonly работает только во время компиляции. Во время выполнения массив не заморожен (присвоение выше действительно выполнилось, это видно в выводе), поэтому, если нужна гарантия во время выполнения, используйте Object.freeze.

Возврат кортежа из функции

Именно так, кортежем из нескольких значений, работает useState в React (const [value, setValue] = useState(0)). Подвох в том, что литерал массива в return выводится как массив, а не как кортеж.

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

Функция возвращает (number | (() => number))[], поэтому оба имени после деструктуризации получают тип-объединение. Исправлений два: аннотировать возвращаемый тип или добавить 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

Кортеж в качестве возвращаемого значения позволяет вызывающему коду назвать части как угодно. Если значений больше двух-трёх или порядок неочевиден, возвращайте объект: { count, increment } документирует себя сам.

Кортежи как параметры функций

Rest-параметр с типом кортежа описывает весь список аргументов, включая опциональные. Именно так встроенный служебный тип Parameters<T> представляет параметры функции.

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

Разворачивание кортежа в вызов проверяет каждый аргумент по позиции, чего разворачивание (string | number)[] сделать не может.

Кортеж и массив

Кортежи встречаются и во встроенных типах. Object.entries(obj) возвращает [string, T][], а Map создаётся из кортежей [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 ] ]

Одна ловушка: у изменяемого кортежа есть все методы массива, поэтому pair.push(3) компилируется на [string, number] и незаметно создаёт массив из трёх элементов, хотя тип говорит о двух. Объявление кортежей как readonly закрывает эту дыру. И раз типы стираются, данные извне программы (JSON, API) во время выполнения по типу кортежа не проверяются: прежде чем им доверять, проверьте длину и типы элементов.

Вариативные типы кортежей

Типы кортежей могут разворачивать другие типы кортежей, [...T, ...U]. Вместе с дженериками это позволяет типизировать функции, которые склеивают кортежи или добавляют элементы в начало, сохраняя каждую позицию:

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

Типы библиотек тоже опираются на вывод кортежей: Promise.all([fetchUser(), fetchPosts()]) разрешается в кортеж с отдельным типом для каждого входного промиса.