Tuple di TypeScript: Sintaks, Elemen Bernama, Opsional, Rest

Tuple di TypeScript adalah array dengan jumlah elemen yang tetap, dan setiap posisinya punya tipe sendiri. [string, number] berarti tepat dua elemen: string lebih dulu, lalu number. Kamu menulis tipenya di dalam kurung siku sesuai urutan nilainya.

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

Saat runtime, tuple adalah array JavaScript biasa. Semua yang ditambahkan tuple (panjang yang tetap dan tipe di setiap posisi) dicek oleh compiler lalu dihapus.

Sintaks Tuple

Setiap bentuk dijelaskan di bawah. Tipe length layak diperhatikan: untuk tuple yang tetap, tipenya adalah literal type, jadi compiler tahu pair.length tepat bernilai 2.

Apa yang Dicek Compiler

Tipe tuple menetapkan jumlah elemen, urutannya, dan tipe di setiap posisi. Salah di salah satunya adalah error kompilasi:

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

Array biasa tidak akan pernah bisa menangkap yang terakhir: untuk string[], arr[2] hanyalah sebuah string yang kebetulan bernilai undefined saat runtime.

Elemen Tuple Bernama

Label mendokumentasikan arti setiap posisi. Label tidak mengubah apa pun pada tipe atau cara mengaksesnya lewat index, tetapi editor menampilkannya saat hover dan di petunjuk signature, sehingga [number, number] jauh lebih mudah dipahami.

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

Sejak TypeScript 5.2, kamu bisa memberi label pada sebagian posisi dan membiarkan yang lain tanpa label, seperti [first: string, number]. Label hanya untuk pembaca: [x: number, y: number] dan [number, number] adalah tipe yang sama dan bisa saling di-assign.

Elemen Opsional

? setelah tipe elemen membuat posisi itu opsional. Elemen opsional harus berada setelah elemen wajib, dan masing-masing melebarkan tipe 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

Membaca elemen opsional menghasilkan T | undefined, jadi dibutuhkan nilai default di pola destructuring (a = 1) atau pengecekan sebelum melakukan aritmetika.

Elemen Rest

Elemen rest, ...T[], mewakili elemen bertipe T sebanyak apa pun. Elemen ini boleh berada di akhir, di awal, atau di tengah, paling banyak satu per tuple.

// 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 dari tuple dengan elemen rest adalah number, karena ukurannya tidak lagi tetap. Yang tetap adalah letak posisi-posisi yang bertipe.

Tuple Readonly dan as const

readonly [T, U] menghapus push, pop, splice dan assignment lewat index, dan memang begitulah seharusnya nilai dengan panjang tetap. Menulis as const setelah array literal akan menyimpulkan tuple readonly berisi literal type.

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] mengubah tuple menjadi union dari tipe elemennya, pola yang dibahas di indexed access types. Tuple readonly tidak bisa dikirim ke parameter bertipe tuple yang mutable, jadi fungsi yang hanya membaca sebaiknya menerima readonly [number, number].

Pengecekan readonly hanya berlaku saat kompilasi. Saat runtime, array-nya tidak dibekukan (assignment di atas benar-benar dijalankan, seperti yang terlihat di output), jadi pakai Object.freeze kalau kamu butuh jaminan saat runtime.

Mengembalikan Tuple dari Fungsi

Mengembalikan beberapa nilai sebagai tuple adalah cara kerja useState di React (const [value, setValue] = useState(0)). Masalahnya: array literal di return disimpulkan sebagai array, bukan tuple.

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

Fungsi itu mengembalikan (number | (() => number))[], jadi kedua nama hasil destructuring mendapat tipe union. Ada dua perbaikan: beri anotasi tipe kembalian, atau tambahkan 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

Nilai kembalian berupa tuple membuat pemanggil bebas memberi nama bagian-bagiannya. Kalau nilainya lebih dari dua atau tiga, atau urutannya tidak jelas, kembalikan object sebagai gantinya: { count, increment } sudah menjelaskan dirinya sendiri.

Tuple sebagai Parameter Fungsi

Rest parameter yang bertipe tuple menggambarkan seluruh daftar argumen, termasuk argumen opsional. Begitulah utility type bawaan Parameters<T> merepresentasikan parameter sebuah fungsi.

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

Melakukan spread tuple ke sebuah pemanggilan akan mengecek tipe setiap argumen berdasarkan posisinya, sesuatu yang tidak bisa dilakukan spread dari (string | number)[].

Tuple vs Array

Tuple juga muncul di tipe bawaan. Object.entries(obj) mengembalikan [string, T][], dan sebuah Map dibangun dari tuple [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 ] ]

Satu jebakan: tuple yang mutable tetap punya setiap method array, jadi pair.push(3) lolos kompilasi pada [string, number] dan diam-diam membuat array tiga elemen yang tipenya bilang dua. Mendeklarasikan tuple sebagai readonly menutup celah itu. Lalu, karena tipe dihapus saat kompilasi, data dari luar program (JSON, API) tidak dicek terhadap tipe tuple saat runtime: validasi panjang dan tipe elemennya sebelum memercayainya.

Variadic Tuple Type

Tipe tuple bisa melakukan spread tipe tuple lain, [...T, ...U]. Digabung dengan generic, ini memberi tipe pada fungsi yang menyambung atau menambahkan elemen di depan sambil mempertahankan setiap posisi:

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

Tipe di library juga mengandalkan inferensi tuple: Promise.all([fetchUser(), fetchPosts()]) resolve menjadi tuple dengan satu tipe untuk setiap promise input.