TypeScript tuple: תחביר, איברים עם שמות, אופציונליים ו-rest

Tuple ב-TypeScript הוא מערך עם מספר קבוע של איברים, שבו לכל מיקום יש טיפוס משלו. [string, number] פירושו בדיוק שני איברים: קודם מחרוזת, אחר כך מספר. כותבים את הטיפוסים בסוגריים מרובעים, בסדר שבו הערכים מופיעים.

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

בזמן ריצה tuple הוא מערך JavaScript רגיל. כל מה ש-tuple מוסיף (האורך הקבוע והטיפוס בכל מיקום) נבדק על ידי הקומפיילר ונמחק.

תחביר של tuple

כל צורה מוסברת בהמשך. שימו לב לטיפוס של length: ב-tuple קבוע הוא טיפוס ליטרלי, כך שהקומפיילר יודע ש-pair.length הוא בדיוק 2.

מה הקומפיילר בודק

טיפוס tuple קובע את מספר האיברים, את הסדר שלהם ואת הטיפוס בכל מיקום. טעות באחד מהם היא שגיאת קומפילציה:

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

מערך רגיל לא היה יכול לתפוס את השגיאה האחרונה: עבור string[], arr[2] הוא פשוט string שבמקרה הוא undefined בזמן ריצה.

איברי tuple עם שמות

תוויות מתעדות מה המשמעות של כל מיקום. הן לא משנות דבר בטיפוס או באופן הגישה לפי אינדקס, אבל עורכי קוד מציגים אותן בחלוניות המידע וברמזי החתימה, וזה הופך את [number, number] להרבה פחות מסתורי.

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 אפשר לתת תוויות לחלק מהמיקומים ולהשאיר אחרים בלי תווית, כמו ב-[first: string, number]. התוויות נועדו לקוראים בלבד: [x: number, y: number] ו-[number, number] הם אותו טיפוס, וניתנים להשמה זה לזה.

איברים אופציונליים

? אחרי טיפוס של איבר הופך את המיקום הזה לאופציונלי. איברים אופציונליים חייבים לבוא אחרי האיברים הנדרשים, וכל אחד מהם מרחיב את הטיפוס של 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

קריאה של איבר אופציונלי נותנת T | undefined, ולכן צריך ערך ברירת מחדל בתבנית ה-destructuring (a = 1) או בדיקה לפני חישוב.

איברי rest

איבר rest, ...T[], מייצג מספר כלשהו של איברים מטיפוס T. הוא יכול להופיע בסוף, בהתחלה או באמצע, ולכל היותר אחד בכל 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 של tuple עם איבר rest הוא number, כי הגודל כבר לא קבוע. מה שנשאר קבוע הוא המקום של המיקומים עם הטיפוסים.

Tuples לקריאה בלבד ו-as const

readonly [T, U] מסיר את push, pop, splice ואת ההשמה לפי אינדקס, וזה בדיוק מה שערך באורך קבוע צריך להיות. כתיבת as const אחרי מערך ליטרלי מסיקה tuple לקריאה בלבד של טיפוסים ליטרליים.

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 ל-union של טיפוסי האיברים שלו, דפוס שמוסבר בעמוד indexed access types. אי אפשר להעביר tuple לקריאה בלבד לפרמטר שמוגדר כ-tuple שניתן לשינוי, ולכן פונקציות שרק קוראות צריכות לקבל readonly [number, number].

הבדיקה של readonly קיימת רק בזמן קומפילציה. בזמן ריצה המערך לא מוקפא (ההשמה שלמעלה באמת רצה, כמו שהפלט מראה), ולכן השתמשו ב-Object.freeze אם צריך הבטחה בזמן ריצה.

החזרת tuple מפונקציה

החזרה של כמה ערכים כ-tuple היא הדרך שבה useState של React עובד (const [value, setValue] = useState(0)). המלכודת: מערך ליטרלי ב-return מוסק כמערך, לא כ-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.

הפונקציה מחזירה (number | (() => number))[], ולכן שני השמות שחולצו ב-destructuring מקבלים את טיפוס ה-union. יש שני תיקונים: להצהיר על טיפוס ההחזרה, או להוסיף 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

ערך החזרה מסוג tuple מאפשר למי שקורא לפונקציה לקרוא לחלקים איך שהוא רוצה. כשיש יותר משניים או שלושה ערכים, או כשהסדר לא ברור מאליו, החזירו אובייקט במקום: { count, increment } מתעד את עצמו.

Tuples כפרמטרים של פונקציה

פרמטר rest שמוגדר כ-tuple מתאר רשימת ארגומנטים שלמה, כולל ארגומנטים אופציונליים. כך טיפוס העזר המובנה Parameters<T> מייצג את הפרמטרים של פונקציה.

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

פריסה של tuple לתוך קריאה בודקת כל ארגומנט לפי המיקום שלו, משהו שפריסה של (string | number)[] לא יכולה לעשות.

Tuple מול מערך

Tuples מופיעים גם בטיפוסים מובנים. Object.entries(obj) מחזיר [string, T][], ו-Map נבנה מ-tuples של [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 ] ]

מלכודת אחת: ל-tuple שניתן לשינוי עדיין יש כל מתודות המערך, ולכן pair.push(3) מתקמפל על [string, number] ויוצר בשקט מערך של שלושה איברים שהטיפוס שלו אומר שניים. הצהרה על tuples כ-readonly סוגרת את הפרצה הזו. ומאחר שהטיפוסים נמחקים, נתונים מחוץ לתוכנית (JSON, API) לא נבדקים מול טיפוס tuple בזמן ריצה: בדקו את האורך ואת טיפוסי האיברים לפני שסומכים עליהם.

Variadic tuple types

טיפוסי tuple יכולים לפרוס טיפוסי tuple אחרים, [...T, ...U]. בשילוב עם generics, זה נותן טיפוסים לפונקציות שמשרשרות או מוסיפות איברים בהתחלה ושומרות על כל מיקום:

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

גם טיפוסים של ספריות נשענים על הסקת tuples: Promise.all([fetchUser(), fetchPosts()]) נפתר ל-tuple עם טיפוס אחד לכל promise בקלט.