מערכים ב-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 עם טיפוסים

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