Tuple TypeScript: cú pháp, phần tử có tên, tùy chọn và rest

Tuple trong TypeScript là một mảng có số phần tử cố định, trong đó mỗi vị trí có kiểu riêng. [string, number] nghĩa là đúng hai phần tử: đầu tiên là một chuỗi, sau đó là một số. Bạn viết các kiểu trong cặp ngoặc vuông theo đúng thứ tự xuất hiện của các giá trị.

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

Lúc chạy, tuple chỉ là một mảng JavaScript thông thường. Mọi thứ tuple bổ sung (độ dài cố định và kiểu tại mỗi vị trí) đều được trình biên dịch kiểm tra rồi xóa đi.

Cú pháp tuple

Mỗi dạng được giải thích ở bên dưới. Kiểu của length đáng để ý: với tuple cố định, nó là một literal type, nên trình biên dịch biết pair.length chính xác là 2.

Trình biên dịch kiểm tra những gì

Một kiểu tuple cố định số phần tử, thứ tự của chúng và kiểu tại mỗi vị trí. Sai bất kỳ điều nào cũng là lỗi biên dịch:

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

Một mảng thông thường không bao giờ bắt được lỗi cuối cùng: với string[], arr[2] đơn giản là một string mà lúc chạy lại tình cờ là undefined.

Phần tử tuple có tên

Nhãn cho biết ý nghĩa của từng vị trí. Chúng không thay đổi gì về kiểu hay cách truy cập theo chỉ số, nhưng trình soạn thảo hiển thị chúng khi rê chuột và trong gợi ý chữ ký hàm, giúp [number, number] bớt khó hiểu hơn nhiều.

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

Từ TypeScript 5.2, bạn có thể đặt nhãn cho một số vị trí và để trống những vị trí khác, như [first: string, number]. Nhãn chỉ dành cho người đọc: [x: number, y: number] và [number, number] là cùng một kiểu và gán được cho nhau.

Phần tử tùy chọn

Dấu ? sau kiểu của một phần tử biến vị trí đó thành tùy chọn. Các phần tử tùy chọn phải đứng sau các phần tử bắt buộc, và mỗi phần tử tùy chọn mở rộng kiểu của 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

Đọc một phần tử tùy chọn cho ra T | undefined, nên cần một giá trị mặc định trong mẫu destructuring (a = 1) hoặc một phép kiểm tra trước khi tính toán.

Phần tử rest

Phần tử rest, ...T[], đại diện cho bao nhiêu phần tử kiểu T cũng được. Nó có thể nằm ở cuối, ở đầu hoặc ở giữa, và mỗi tuple có tối đa một phần tử rest.

// 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 của một tuple có phần tử rest là number, vì kích thước không còn cố định. Điều vẫn cố định là vị trí của các phần tử có kiểu riêng.

Tuple readonly và as const

readonly [T, U] loại bỏ push, pop, splice và phép gán theo chỉ số, đúng như một giá trị có độ dài cố định nên có. Viết as const sau một mảng literal sẽ suy ra một tuple readonly gồm các 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] biến tuple thành union của các kiểu phần tử, một mẫu được trình bày trong trang indexed access type. Không thể truyền một tuple readonly cho tham số có kiểu là tuple có thể thay đổi, nên những hàm chỉ đọc nên nhận readonly [number, number].

Kiểm tra readonly chỉ có lúc biên dịch. Lúc chạy, mảng không bị đóng băng (phép gán ở trên thật sự đã chạy, như đầu ra cho thấy), nên hãy dùng Object.freeze nếu bạn cần đảm bảo lúc chạy.

Trả về tuple từ hàm

Trả về nhiều giá trị dưới dạng tuple chính là cách useState của React hoạt động (const [value, setValue] = useState(0)). Điểm cần lưu ý: một mảng literal trong return được suy ra là mảng, không phải 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.

Hàm trả về (number | (() => number))[], nên cả hai tên được destructuring đều nhận kiểu union. Có hai cách sửa: chú thích kiểu trả về, hoặc thêm 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

Giá trị trả về là tuple cho phép nơi gọi tự đặt tên các phần theo ý muốn. Khi có nhiều hơn hai hoặc ba giá trị, hoặc thứ tự không hiển nhiên, hãy trả về một đối tượng: { count, increment } tự nói lên ý nghĩa của nó.

Tuple làm tham số hàm

Một tham số rest có kiểu tuple mô tả toàn bộ danh sách đối số, kể cả đối số tùy chọn. Đây là cách utility type dựng sẵn Parameters<T> biểu diễn các tham số của một hàm.

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

Spread một tuple vào lời gọi hàm sẽ kiểm tra kiểu từng đối số theo vị trí, điều mà spread một (string | number)[] không làm được.

Tuple và mảng

Tuple cũng xuất hiện trong các kiểu dựng sẵn. Object.entries(obj) trả về [string, T][], và một Map được tạo từ các 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 ] ]

Một cái bẫy: tuple có thể thay đổi vẫn có mọi phương thức của mảng, nên pair.push(3) vẫn biên dịch được trên một [string, number] và âm thầm tạo ra một mảng ba phần tử trong khi kiểu nói là hai. Khai báo tuple là readonly sẽ bịt lỗ hổng đó. Và vì kiểu bị xóa khi biên dịch, dữ liệu từ bên ngoài chương trình (JSON, một API) không được kiểm tra theo kiểu tuple lúc chạy: hãy xác thực độ dài và kiểu phần tử trước khi tin dùng.

Variadic tuple type

Kiểu tuple có thể spread các kiểu tuple khác, [...T, ...U]. Kết hợp với generic, điều này giúp khai báo kiểu cho những hàm nối hoặc chèn vào đầu mà vẫn giữ nguyên mọi vị trí:

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

Kiểu trong các thư viện cũng dựa vào khả năng suy ra tuple: Promise.all([fetchUser(), fetchPosts()]) cho ra một tuple với mỗi kiểu ứng với một promise đầu vào.