TypeScript Tuple: Syntax, benannte, optionale und Rest-Elemente

Ein TypeScript-Tupel ist ein Array mit einer festen Anzahl von Elementen, bei dem jede Position ihren eigenen Typ hat. [string, number] bedeutet genau zwei Elemente: zuerst ein String, dann eine Zahl. Du schreibst die Typen in eckigen Klammern in der Reihenfolge, in der die Werte stehen.

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

Zur Laufzeit ist ein Tupel ein einfaches JavaScript-Array. Alles, was ein Tupel hinzufügt (die feste Länge und der Typ an jeder Position), prüft der Compiler und entfernt es dann.

Tupel-Syntax

Jede Form wird unten erklärt. Beachte den Typ von length: Bei einem festen Tupel ist er ein Literaltyp, der Compiler weiß also, dass pair.length genau 2 ist.

Was der Compiler prüft

Ein Tupel-Typ legt die Anzahl der Elemente, ihre Reihenfolge und den Typ an jeder Position fest. Ist davon etwas falsch, gibt es einen Compilerfehler:

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

Ein einfaches Array könnte den letzten Fehler nie finden: Bei string[] ist arr[2] schlicht ein string, der zur Laufzeit zufällig undefined ist.

Benannte Tupel-Elemente

Bezeichner dokumentieren, was jede Position bedeutet. Sie ändern nichts am Typ oder am Indexzugriff, aber Editoren zeigen sie in Hovern und Signaturhinweisen, was [number, number] viel weniger rätselhaft macht.

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

Seit TypeScript 5.2 kannst du manche Positionen benennen und andere nicht, etwa [first: string, number]. Bezeichner sind nur für Leser da: [x: number, y: number] und [number, number] sind derselbe Typ und untereinander zuweisbar.

Optionale Elemente

Ein ? hinter einem Elementtyp macht diese Position optional. Optionale Elemente müssen nach den Pflichtelementen stehen, und jedes erweitert den Typ von 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

Ein optionales Element zu lesen ergibt T | undefined, daher brauchst du vor Rechnungen einen Standardwert im Destructuring-Muster (a = 1) oder eine Prüfung.

Rest-Elemente

Ein Rest-Element, ...T[], steht für beliebig viele Elemente vom Typ T. Es kann am Ende, am Anfang oder in der Mitte stehen, höchstens eines pro Tupel.

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

Die length eines Tupels mit Rest-Element ist number, weil die Größe nicht mehr fest ist. Fest bleibt, wo die typisierten Positionen liegen.

Readonly Tupel und as const

readonly [T, U] entfernt push, pop, splice und Zuweisungen per Index, und genau so sollte ein Wert fester Länge sein. as const hinter einem Array-Literal leitet ein readonly Tupel aus Literaltypen ab.

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] macht aus dem Tupel eine Union seiner Elementtypen, ein Muster, das unter Indexed Access Types erklärt wird. Ein readonly Tupel kann nicht an einen Parameter übergeben werden, der als veränderbares Tupel typisiert ist, deshalb sollten Funktionen, die nur lesen, readonly [number, number] akzeptieren.

Die readonly-Prüfung gilt nur beim Kompilieren. Zur Laufzeit ist das Array nicht eingefroren (die Zuweisung oben lief tatsächlich, wie die Ausgabe zeigt), nimm also Object.freeze, wenn du eine Garantie zur Laufzeit brauchst.

Ein Tupel aus einer Funktion zurückgeben

Mehrere Werte als Tupel zurückzugeben ist das Prinzip von Reacts useState (const [value, setValue] = useState(0)). Der Haken: Ein Array-Literal in einem return wird als Array abgeleitet, nicht als Tupel.

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

Die Funktion gibt (number | (() => number))[] zurück, daher bekommen beide Namen beim Destructuring den Union-Typ. Es gibt zwei Lösungen: den Rückgabetyp annotieren oder as const ergänzen.

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

Mit einem Tupel als Rückgabewert können Aufrufer die Teile beliebig benennen. Bei mehr als zwei oder drei Werten, oder wenn die Reihenfolge nicht offensichtlich ist, gib lieber ein Objekt zurück: { count, increment } dokumentiert sich selbst.

Tupel als Funktionsparameter

Ein Rest-Parameter, der als Tupel typisiert ist, beschreibt eine ganze Argumentliste, optionale Argumente eingeschlossen. So stellt der eingebaute Utility-Typ Parameters<T> die Parameter einer Funktion dar.

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

Wird ein Tupel in einen Aufruf gespreadet, prüft TypeScript jedes Argument nach Position, was bei einem Spread von (string | number)[] nicht ginge.

Tupel vs Array

Tupel tauchen auch in eingebauten Typen auf. Object.entries(obj) gibt [string, T][] zurück, und eine Map wird aus [key, value]-Tupeln erzeugt:

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

Eine Falle: Ein veränderbares Tupel hat weiterhin alle Array-Methoden, also kompiliert pair.push(3) auf einem [string, number] und erzeugt stillschweigend ein Array mit drei Elementen, dessen Typ zwei behauptet. Tupel als readonly zu deklarieren schließt diese Lücke. Und weil Typen entfernt werden, werden Daten von außerhalb des Programms (JSON, eine API) zur Laufzeit nicht gegen einen Tupel-Typ geprüft: Validiere Länge und Elementtypen, bevor du ihnen vertraust.

Variadic Tuple Types

Tupel-Typen können andere Tupel-Typen spreaden, [...T, ...U]. Zusammen mit Generics lassen sich so Funktionen typisieren, die verketten oder vorn anfügen und dabei jede Position behalten:

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

Auch Bibliothekstypen stützen sich auf Tupel-Inferenz: Promise.all([fetchUser(), fetchPosts()]) wird zu einem Tupel mit einem Typ je Eingabe-Promise aufgelöst.