Tuples in TypeScript

Analogy categoryAnalogies

1. Introduction

A tuple is a special array type in TypeScript where the number of elements and the type of each position are fixed and known ahead of time. Tuples are ideal for representing small, structured groupings of values, like a coordinate pair or a key-value entry.

🏏

Cricket analogy: A tuple is like a fixed run-rate entry [overs, runs] where the first slot is always the over count and the second is always runs scored, a small, structured pairing rather than an open-ended array of scores.

Unlike a regular array where every element shares one type, a tuple can mix different types at specific, well-defined positions.

🏏

Cricket analogy: Unlike a regular array of all-integer scores, a tuple can mix types at fixed positions, like [playerName: string, runsScored: number], so the batter's name and their run total sit in well-defined, differently typed slots.

2. Syntax

typescript

let point: [number, number] = [10, 20];
let entry: [string, number] = ["age", 30];
let labeled: [id: number, name: string] = [1, "Alice"];
let optionalTuple: [string, number?] = ["x"];

3. Explanation

A tuple type is written as a square-bracketed list of types, positionally matched to the array's elements: [string, number] requires exactly a string first and a number second. TypeScript checks both the length and the type at each index.

🏏

Cricket analogy: A tuple type [string, number] for a batting entry demands exactly a player name first and a run total second, TypeScript checks both that there are precisely two elements and that each position's type matches, rejecting [42, Kohli] for having the order swapped.

Tuples are commonly used for function return values that bundle two related pieces of data, such as useState() in React, which returns a [value, setter] tuple.

🏏

Cricket analogy: Just as a partnership scoreboard bundles two related figures into one fixed entry [striker, nonStriker], useState() in React returns a [value, setter] tuple, bundling a state value with its updater function into one fixed, ordered pair.

Tuples enforce fixed length and order only at the point of declaration and direct index access — they are NOT immutable by default. Calling .push() on a tuple is still allowed by the type checker, because TypeScript's array mutation methods are not tuple-length-aware. This means let t: [string, number] = ["a", 1]; t.push("oops"); compiles without error, silently breaking the tuple's contract at runtime. Use as const or a readonly tuple type to guard against this.

4. Example

typescript

let user: [string, number] = ["Bob", 25];
const [name, age] = user;
console.log(`${name} is ${age}`);

// The classic gotcha: push bypasses the fixed-length contract
user.push("extra");
console.log(user);
console.log(user.length);

5. Output

text

Bob is 25
[ 'Bob', 25, 'extra' ]
3

6. Key Takeaways

Tuples are arrays with a fixed length and a known type at each position.
Tuple syntax lists types positionally in square brackets: [string, number].
Optional tuple elements use ?, e.g. [string, number?].
Tuples are NOT immutable by default — .push() still compiles and silently breaks the length contract.
Use readonly tuple types or as const to prevent unwanted mutation.
Destructuring is the most common and safest way to consume tuple values.