المصفوفات في TypeScript: الأنواع ومصفوفات الكائنات وmap وfilter

نوع المصفوفة في TypeScript هو نوع العنصر متبوعًا بـ []: string[] مصفوفة نصوص، وnumber[] مصفوفة أرقام. والكتابة العامة Array<string> هي النوع نفسه. بعد تحديد نوع المصفوفة، يكون لكل عنصر تضيفه وكل عنصر تقرؤه ذلك النوع.

const names: string[] = ["Ada", "Grace"];
const scores: Array<number> = [90, 85, 72]; // same as number[]

names.push("Alan");
// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type 'string'.
names.push(42);

const first: string = names[0];
const total = scores.reduce((sum, s) => sum + s, 0); // number

console.log(names, first, total);

سطر @ts-expect-error خطأ ترجمة (TS2345). هنا يُعلَّم على أنه متوقع حتى يعمل المثال، ولأن الأنواع تُمحى، يُضاف 42 فعلًا وقت التشغيل: الناتج يظهر ذلك.

string[] مقابل Array<string>

اختر أسلوبًا واحدًا لقاعدة الكود. القاعدة array-type في typescript-eslint تفضّل T[] افتراضيًا.

مصفوفات الكائنات

صِف العنصر بـ type alias أو interface، ثم استخدم Type[]. كل ما يُقرأ من المصفوفة يُفحص مقابل ذلك الشكل.

type User = { id: number; name: string; admin: boolean };

const users: User[] = [
    { id: 1, name: "Ada", admin: true },
    { id: 2, name: "Grace", admin: false },
    { id: 3, name: "Alan", admin: false },
];

users.push({ id: 4, name: "Linus", admin: false });

const admins = users.filter((u) => u.admin);       // User[]
const names = users.map((u) => u.name);            // string[]
const byId = users.find((u) => u.id === 2);        // User | undefined

console.log(admins.length, names);
console.log(byId?.name ?? "not found"); // Grace

الكائن الحرفي الذي يُضاف إلى users يجب أن يطابق User تمامًا: غياب admin أو خطأ إملائي في اسم خاصية خطأ ترجمة.

أنواع map وfilter وreduce وfind

دوال المصفوفات عامة (generic)، لذلك تحمل نتائجها أنواعًا. ما تفعله كل دالة وقت التشغيل مشروح في صفحة دوال المصفوفات في JavaScript؛ والأنواع هي ما تضيفه TypeScript:

const prices = [4.5, 12, 8.25];

const labels = prices.map((p) => `$${p.toFixed(2)}`); // string[]
console.log(labels); // [ '$4.50', '$12.00', '$8.25' ]

const expensive = prices.find((p) => p > 100); // number | undefined
console.log(expensive ?? "none"); // none

// reduce's result type comes from the initial value,
// or from a type argument when the initial value is just {}
const byInitial = ["apple", "avocado", "banana"].reduce<Record<string, string[]>>(
    (acc, word) => {
        (acc[word[0]] ??= []).push(word);
        return acc;
    },
    {},
);
console.log(byInitial); // { a: [ 'apple', 'avocado' ], b: [ 'banana' ] }

// filter narrows when the callback is a type check
const raw = [1, undefined, 3, undefined];
const defined = raw.filter((n) => n !== undefined); // number[]
console.log(defined); // [ 1, 3 ]

يعمل المثال الأخير لأن TypeScript (منذ 5.5) تستنتج أن (n) => n !== undefined هو type predicate، فتعيد filter النوع number[] بدل (number | undefined)[]. وللفحوص التي لا تستطيع استنتاجها، اكتب الـ predicate بنفسك: filter((x): x is User => x !== null).

مصفوفات تحمل أكثر من نوع

نوع عنصر من union يسمح بالخلط. أما union من أنواع مصفوفات فلا:

const mixed: (string | number)[] = [1, "two", 3]; // each element: string or number

let ids: string[] | number[] = [1, 2, 3]; // all numbers...
ids = ["a", "b"];                          // ...or all strings

// @ts-expect-error: (string | number)[] is not assignable to string[] | number[]
ids = [1, "b"];

for (const item of mixed) {
    // narrow each element before using type-specific methods
    console.log(typeof item === "string" ? item.toUpperCase() : item.toFixed(1));
}

عندما تكون للمواضع أنواع ثابتة، مثل زوج [name, age]، استخدم tuple بدلًا من ذلك: يعرف [string, number] أن الفهرس 0 نص والفهرس 1 رقم، بينما لا يعرف (string | number)[] ذلك.

المصفوفات للقراءة فقط

يحذف readonly T[] كل دالة تعدّل المصفوفة. استخدمه للمعاملات التي يجب ألا تغيّرها الدالة، وللثوابت.

// This does not compile: readonly arrays have no push.
function average(values: readonly number[]): number {
    values.push(0);
    return values.reduce((a, b) => a + b, 0) / values.length;
}

console.log(average([2, 4, 6]));

index.ts(3,12): error TS2339: Property 'push' does not exist on type 'readonly number[]'.

احذف سطر push فيطبع المثال 4. يمكن دائمًا تمرير number[] القابلة للتعديل حيث يُتوقع readonly number[]، لذلك لا تكلف معاملات readonly المستدعين شيئًا. الفحص وقت الترجمة فقط: وقت التشغيل هي مصفوفة عادية. ولترتيب مصفوفة للقراءة فقط، رتّب نسخة منها: [...values].sort().

مشكلة includes مع المصفوفات الحرفية

يحوّل as const المصفوفة إلى tuple للقراءة فقط من أنواع حرفية. هذا مفيد لقائمة من القيم المسموحة، لكن includes فيها لا يقبل عندئذ إلا تلك القيم الحرفية:

const COLORS = ["red", "green", "blue"] as const;
type Color = (typeof COLORS)[number]; // "red" | "green" | "blue"

function isColor(value: string): value is Color {
    // COLORS.includes(value) is error TS2345: 'string' is not assignable
    // to '"blue" | "green" | "red"'. Widen the array for the check:
    return (COLORS as readonly string[]).includes(value);
}

const input: string = "green";
if (isColor(input)) {
    const c: Color = input; // narrowed to Color
    console.log("valid color:", c);
}
console.log(isColor("purple")); // false

وضع الفحص داخل type guard (value is Color) يعني أن التوسيع يحدث مرة واحدة، ويحصل المستدعون على قيمة مضيَّقة.

الفهرسة والمصفوفات الفارغة

قراءة arr[i] تعطي النوع T، حتى عندما يكون i خارج النطاق وتكون القيمة وقت التشغيل undefined. أما at(i) فنوعها T | undefined، وخيار المترجم noUncheckedIndexedAccess يجعل الفهرسة العادية تعيد T | undefined أيضًا.

const queue: string[] = []; // annotate empty arrays

const head = queue[0];     // type string, value undefined
const last = queue.at(-1); // type string | undefined

console.log(head, last);            // undefined undefined
console.log(last?.toUpperCase());   // undefined, safely

كان queue[0].toUpperCase() سيُترجم ثم يرمي TypeError وقت التشغيل. فضّل at() أو فحص الطول أو noUncheckedIndexedAccess عندما قد يكون الفهرس غير موجود.