Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A tuple in TypeScript is a specialized array type that enforces a fixed length and a specific type sequence. It allows you to express an array where the type of each element is known at a specific positional index, enabling strict type checking for heterogeneous collections.

​
Basic Syntax and Assignment

A tuple is defined by wrapping a comma-separated list of types in square brackets. The assigned array must exactly match the defined length and the type at each corresponding index. 
let strictTuple: [string, number, boolean];

strictTuple = ["hello", 42, true]; // Valid

// Error: Type 'number' is not assignable to type 'string' at index 0.
strictTuple = [42, "hello", true]; 

// Error: Source has 2 element(s) but target requires 3.
strictTuple = ["hello", 42];

​
Positional Type Inference

When accessing elements via bracket notation or destructuring, the TypeScript compiler infers the exact type based on the index. Accessing an index outside the defined length results in a compile-time error. 
let data: [string, number] = ["TypeScript", 2023];

const text = data[0]; // Inferred as 'string'
const year = data[1]; // Inferred as 'number'

// Error: Tuple type '[string, number]' of length '2' has no element at index '2'.
const outOfBounds = data[2];

​
Optional Elements

Tuple elements can be marked as optional using the ? modifier. Optional elements must always appear at the end of the tuple declaration. This makes the length property of the tuple a union type. 
let optionalTuple: [string, number, boolean?];

optionalTuple = ["test", 1];       // Valid, length is 2
optionalTuple = ["test", 1, true]; // Valid, length is 3

type OptLength = typeof optionalTuple.length; // Type is 2 | 3

​
Variadic Tuples (Rest Elements)

Tuples can incorporate rest elements (...) to represent an open-ended sequence of a specific type while maintaining strict positional types for the other elements. The rest element can be positioned at the beginning, middle, or end of the tuple. 
// Rest element at the end
let stringAndNumbers: [string, ...number[]];
stringAndNumbers = ["start", 1, 2, 3, 4];

// Rest element in the middle
let boundedTuple: [boolean, ...string[], number];
boundedTuple = [true, "a", "b", "c", 99];

​
Labeled (Named) Tuple Elements

To improve code readability and tooling support (like IDE autocompletion), tuple elements can be labeled. These labels are purely metadata and do not affect the runtime behavior or the underlying type structure. 
let userRecord: [name: string, age: number, isActive: boolean];
userRecord = ["Alice", 30, true];

​
Readonly Tuples

By default, tuple elements are mutable. You can enforce immutability using the readonly modifier or the Readonly<T> utility type. This removes mutating methods like push, pop, and splice from the type definition. 
let immutableTuple: readonly [string, number] = ["fixed", 100];

// Error: Cannot assign to '0' because it is a read-only property.
immutableTuple[0] = "mutated"; 

// Error: Property 'push' does not exist on type 'readonly [string, number]'.
immutableTuple.push(200);

​
The Mutation Caveat

In standard (non-readonly) tuples, TypeScript strictly enforces length and types during direct assignment. However, array mutation methods like push() and pop() are permitted by the compiler, provided the pushed value matches the union type of all tuple elements. Despite this, TypeScript will still prevent access to out-of-bounds indices. 
let mutableTuple: [string, number] = ["a", 1];

mutableTuple.push(2); // Valid at compile-time
mutableTuple.push("b"); // Valid at compile-time

// Error: Argument of type 'boolean' is not assignable to parameter of type 'string | number'.
mutableTuple.push(true); 

// Error: Tuple type '[string, number]' of length '2' has no element at index '2'.
const hiddenElement = mutableTuple[2];
Master TypeScript with Deep Grasping Methodology!Learn More