Krotki (tuple) w TypeScript: nazwane, opcjonalne i rest

Krotka (tuple) w TypeScript to tablica o stałej liczbie elementów, w której każda pozycja ma własny typ. [string, number] oznacza dokładnie dwa elementy: najpierw string, potem liczbę. Typy zapisujesz w nawiasach kwadratowych w tej kolejności, w jakiej pojawiają się wartości.

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

W czasie wykonania krotka to zwykła tablica JavaScriptu. Wszystko, co dodaje krotka (stała długość i typ na każdej pozycji), sprawdza kompilator, a potem to usuwa.

Składnia krotek

Każda forma jest omówiona niżej. Warto zwrócić uwagę na typ length: dla krotki o stałej długości to typ literału, więc kompilator wie, że pair.length to dokładnie 2.

Co sprawdza kompilator

Typ krotki ustala liczbę elementów, ich kolejność i typ na każdej pozycji. Pomyłka w którejkolwiek z tych rzeczy to błąd kompilacji:

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

Zwykła tablica nigdy nie wyłapałaby ostatniego błędu: dla string[] wyrażenie arr[2] to po prostu string, który w czasie wykonania okazuje się undefined.

Nazwane elementy krotki

Etykiety opisują, co oznacza każda pozycja. Nie zmieniają niczego w typie ani w sposobie indeksowania, ale edytory pokazują je w podpowiedziach i sygnaturach, dzięki czemu [number, number] staje się dużo mniej tajemnicze.

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

Od TypeScript 5.2 możesz oznaczyć etykietami tylko część pozycji, jak w [first: string, number]. Etykiety są tylko dla czytelnika: [x: number, y: number] i [number, number] to ten sam typ i można je przypisywać jeden do drugiego.

Elementy opcjonalne

? po typie elementu sprawia, że ta pozycja jest opcjonalna. Elementy opcjonalne muszą stać po wymaganych, a każdy z nich poszerza typ 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

Odczyt elementu opcjonalnego daje T | undefined, więc przed działaniami arytmetycznymi potrzebna jest wartość domyślna we wzorcu destrukturyzacji (a = 1) albo sprawdzenie.

Elementy rest

Element rest, ...T[], oznacza dowolną liczbę elementów typu T. Może stać na końcu, na początku albo w środku, najwyżej jeden na krotkę.

// 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 krotki z elementem rest ma typ number, bo rozmiar nie jest już stały. Stałe pozostaje to, gdzie leżą otypowane pozycje.

Krotki readonly i as const

readonly [T, U] usuwa push, pop, splice i przypisanie przez indeks, czyli dokładnie to, czego nie powinna mieć wartość o stałej długości. as const po literale tablicy wnioskuje krotkę readonly z typami literałów.

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] zamienia krotkę w unię typów jej elementów. Ten wzorzec omawia strona o indexed access types. Krotki readonly nie da się przekazać do parametru o typie modyfikowalnej krotki, więc funkcje, które tylko czytają, powinny przyjmować readonly [number, number].

Sprawdzenie readonly działa tylko w czasie kompilacji. W czasie wykonania tablica nie jest zamrożona (przypisanie powyżej naprawdę się wykonało, co widać na wyjściu), więc jeśli potrzebujesz gwarancji w czasie wykonania, użyj Object.freeze.

Zwracanie krotki z funkcji

Zwracanie kilku wartości jako krotki to sposób działania useState w React (const [value, setValue] = useState(0)). Haczyk: literał tablicy w return jest wnioskowany jako tablica, a nie krotka.

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

Funkcja zwraca (number | (() => number))[], więc obie zmienne z destrukturyzacji dostają typ unii. Są dwie poprawki: podać typ zwracany albo dodać 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

Krotka jako wartość zwracana pozwala wywołującym nazwać części, jak chcą. Gdy wartości jest więcej niż dwie albo trzy albo kolejność nie jest oczywista, zwróć obiekt: { count, increment } sam się dokumentuje.

Krotki jako parametry funkcji

Parametr rest o typie krotki opisuje całą listę argumentów, także argumenty opcjonalne. Tak wbudowany typ narzędziowy Parameters<T> przedstawia parametry funkcji.

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

Rozwinięcie krotki w wywołaniu sprawdza typ każdego argumentu według pozycji, czego nie potrafi rozwinięcie (string | number)[].

Krotka a tablica

Krotki pojawiają się też we wbudowanych typach. Object.entries(obj) zwraca [string, T][], a Map tworzy się z krotek [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 ] ]

Jedna pułapka: modyfikowalna krotka nadal ma wszystkie metody tablic, więc pair.push(3) kompiluje się na [string, number] i po cichu tworzy tablicę z trzema elementami, choć typ mówi o dwóch. Deklarowanie krotek jako readonly zamyka tę lukę. A ponieważ typy są usuwane, dane spoza programu (JSON, API) nie są w czasie wykonania sprawdzane względem typu krotki: zanim im zaufasz, sprawdź ich długość i typy elementów.

Variadic tuple types

Typy krotek mogą rozwijać inne typy krotek, [...T, ...U]. W połączeniu z generykami pozwala to otypować funkcje, które łączą albo doklejają elementy na początku, zachowując każdą pozycję:

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

Typy bibliotek też korzystają z wnioskowania krotek: Promise.all([fetchUser(), fetchPosts()]) rozwiązuje się do krotki z jednym typem na każdy wejściowy promise.