Tuple في TypeScript: الصياغة والعناصر المسماة والاختيارية و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، لذلك تحتاج إلى قيمة افتراضية في نمط التفكيك (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))[]، فيحصل الاسمان المفككان كلاهما على نوع 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]. ومع الأنواع العامة، يحدد هذا أنواع الدوال التي تدمج أو تضيف في البداية مع الحفاظ على كل موضع:

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

وتعتمد أنواع المكتبات على استنتاج tuple أيضًا: Promise.all([fetchUser(), fetchPosts()]) ينتهي إلى tuple فيه نوع لكل promise مُدخل.