TypeScript Tuple: Sözdizimi, İsimli, Opsiyonel ve Rest Elemanlar

Bir TypeScript tuple'ı, eleman sayısı sabit olan ve her konumun kendi tipine sahip olduğu bir dizidir. [string, number] tam olarak iki eleman demektir: önce bir string, sonra bir sayı. Tipleri, değerlerin göründüğü sırayla köşeli parantez içinde yazarsınız.

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

Çalışma zamanında bir tuple düz bir JavaScript dizisidir. Bir tuple'ın eklediği her şey (sabit uzunluk ve her konumdaki tip) derleyici tarafından kontrol edilir ve silinir.

Tuple Sözdizimi

Her biçim aşağıda açıklanıyor. length tipine dikkat etmeye değer: sabit bir tuple için bir literal tiptir, yani derleyici pair.length değerinin tam olarak 2 olduğunu bilir.

Derleyicinin Kontrol Ettikleri

Bir tuple tipi eleman sayısını, sıralarını ve her konumdaki tipi sabitler. Herhangi birini yanlış yapmak derleme hatasıdır:

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

Düz bir dizi sonuncuyu asla yakalayamazdı: string[] için arr[2] sadece çalışma zamanında undefined olan bir string değeridir.

İsimli Tuple Elemanları

Etiketler her konumun ne anlama geldiğini belgeler. Tip ya da indeksleme şekli hakkında hiçbir şeyi değiştirmezler, ama editörler onları üzerine gelince ve imza ipuçlarında gösterir; bu da [number, number] ifadesini çok daha az gizemli kılar.

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

TypeScript 5.2'den beri bazı konumları etiketleyip diğerlerini etiketsiz bırakabilirsiniz, örneğin [first: string, number]. Etiketler yalnızca okuyucular içindir: [x: number, y: number] ve [number, number] aynı tiptir ve birbirine atanabilir.

Opsiyonel Elemanlar

Bir eleman tipinden sonra gelen ? o konumu opsiyonel yapar. Opsiyonel elemanlar zorunlu olanlardan sonra gelmelidir ve her biri length tipini genişletir.

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

Opsiyonel bir elemanı okumak T | undefined verir; bu yüzden aritmetikten önce destructuring kalıbında bir varsayılan değer (a = 1) ya da bir kontrol gerekir.

Rest Elemanlar

Bir rest eleman, ...T[], istenen sayıda T tipinde elemanı temsil eder. Sonda, başta ya da ortada olabilir; tuple başına en fazla bir tane.

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

Rest eleman içeren bir tuple'ın length tipi number olur, çünkü boyut artık sabit değildir. Sabit kalan, tipli konumların nerede olduğudur.

Readonly Tuple'lar ve as const

readonly [T, U], push, pop, splice ve indekse atamayı kaldırır; sabit uzunluklu bir değer de böyle olmalıdır. Bir dizi literal'inden sonra as const yazmak, literal tiplerden oluşan readonly bir tuple çıkarır.

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] tuple'ı eleman tiplerinin bir union'ına dönüştürür; bu kalıp indexed access types sayfasında anlatılıyor. Readonly bir tuple, değiştirilebilir tuple olarak tiplenmiş bir parametreye verilemez; bu yüzden yalnızca okuyan fonksiyonlar readonly [number, number] kabul etmelidir.

readonly kontrolü yalnızca derleme zamanındadır. Çalışma zamanında dizi dondurulmaz (yukarıdaki atama gerçekten çalıştı, çıktı bunu gösteriyor); çalışma zamanı garantisi gerekiyorsa Object.freeze kullanın.

Bir Fonksiyondan Tuple Döndürmek

Birden fazla değeri bir tuple olarak döndürmek, React'in useState fonksiyonunun çalışma şeklidir (const [value, setValue] = useState(0)). Püf noktası: bir return içindeki dizi literal'i tuple olarak değil, dizi olarak çıkarılır.

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

Fonksiyon (number | (() => number))[] döndürür, bu yüzden destructuring ile alınan iki ad da union tipini alır. İki çözüm vardır: dönüş tipine notasyon yazmak ya da as const eklemek.

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

Tuple dönüş değeri, çağıranların parçalara istedikleri adı vermesine izin verir. İki üçten fazla değer olduğunda ya da sıra açık olmadığında bunun yerine bir nesne döndürün: { count, increment } kendini belgeler.

Fonksiyon Parametresi Olarak Tuple'lar

Tuple olarak tiplenmiş bir rest parametre, opsiyonel argümanlar dahil tüm argüman listesini tanımlar. Yerleşik Parameters<T> utility tipi bir fonksiyonun parametrelerini bu şekilde temsil eder.

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

Bir tuple'ı bir çağrıya yaymak (spread), her argümanı konumuna göre tip kontrolünden geçirir; (string | number)[] tipinde bir yayma bunu yapamazdı.

Tuple ile Dizi

Tuple'lar yerleşik tiplerde de karşınıza çıkar. Object.entries(obj), [string, T][] döndürür ve bir Map, [key, value] tuple'larından oluşturulur:

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

Bir tuzak: değiştirilebilir bir tuple hâlâ her dizi metoduna sahiptir, bu yüzden pair.push(3) bir [string, number] üzerinde derlenir ve tipi iki eleman diyen üç elemanlı bir diziyi sessizce oluşturur. Tuple'ları readonly olarak tanımlamak bu açığı kapatır. Ayrıca tipler silindiği için program dışından gelen veriler (JSON, bir API) çalışma zamanında bir tuple tipine göre kontrol edilmez: güvenmeden önce uzunluğunu ve eleman tiplerini doğrulayın.

Variadic Tuple Tipleri

Tuple tipleri başka tuple tiplerini yayabilir, [...T, ...U]. Generic'lerle birleştiğinde bu, her konumu koruyarak birleştiren veya başa ekleyen fonksiyonlara tip verir:

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

Kütüphane tipleri de tuple çıkarımına dayanır: Promise.all([fetchUser(), fetchPosts()]) her girdi promise'i için bir tip içeren bir tuple'a çözümlenir.