Map في TypeScript: Map<K, V> وget وset وhas والتكرار

الـ Map في TypeScript هي Map المدمجة في JavaScript مع مفاتيح وقيم محددة الأنواع: Map<string, number> تربط نصوصًا بأرقام. أنشئها بـ new Map<K, V>()، ثم استخدم set وget وhas وdelete. تعيد get النوع V | undefined، لأن المفتاح قد يكون غير موجود.

const ages = new Map<string, number>();

ages.set("ada", 36);
ages.set("grace", 85).set("alan", 41); // set returns the map, so calls chain

console.log(ages.get("ada"));    // 36
console.log(ages.get("linus"));  // undefined
console.log(ages.has("grace"));  // true
console.log(ages.size);          // 3

ages.delete("alan");
console.log(ages); // Map(2) { 'ada' => 36, 'grace' => 85 }

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
ages.set("bob", "forty");

وسائط النوع هي ما يجعل الـ Map مفيدة في TypeScript: كل استدعاء لـ set يُفحص، وكل get يعيد نوع القيمة. السطر الأخير خطأ ترجمة (TS2345)، ويُبقي @ts-expect-error الكتلة قابلة للتشغيل.

تتناول هذه الصفحة المجموعة Map. إذا كنت تبحث عن array.map() فستجده في القسم الأخير.

إنشاء Map

تأتي الأنواع من وسائط النوع، أو من العناصر الأولية، أو من تحديد نوع صريح. العناصر الأولية مصفوفة من tuples بالشكل [key, value]، أو أي شيء آخر ينتجها.

// 1. Type arguments, empty map
const scores = new Map<string, number[]>();

// 2. Inferred from entries: Map<string, number>
const prices = new Map([
    ["tea", 2.5],
    ["coffee", 3.2],
]);

// 3. From an object: Map<string, boolean>
const flags = new Map(Object.entries({ darkMode: true, beta: false }));

// 4. Keys and values of any type
type User = { id: number; name: string };
const lastSeen = new Map<User, Date>();
lastSeen.set({ id: 1, name: "Ada" }, new Date("2024-03-15T10:30:00Z"));

console.log(scores.size, prices.get("tea"), flags.get("beta"), lastSeen.size);

فخّان في الاستنتاج:

• new Map() دون وسائط نوع ودون عناصر نوعها Map<any, any>. لا يُفحص أي شيء تضعه فيها أو تأخذه منها. اكتب دائمًا new Map<K, V>().
• العناصر ذات أنواع القيم المختلفة لا تُستنتج كـ union. new Map([["a", 1], ["b", "x"]]) خطأ TS2769 (No overload matches this call). اكتب النوع: new Map<string, number | string>([...]).

get تعيد V | undefined

لا تستطيع الـ Map أن تضمن وجود مفتاح، لذلك نوع get هو V | undefined. مع strict يجب أن تتعامل مع undefined قبل استخدام القيمة كـ V:

// This does not compile: get may return undefined.
const stock = new Map<string, number>([["apples", 3]]);

const apples: number = stock.get("apples");
console.log(apples);

index.ts(4,7): error TS2322: Type 'number | undefined' is not assignable to type 'number'.
  Type 'undefined' is not assignable to type 'number'.

الحلول، من الأكثر شيوعًا إلى الأقل:

const stock = new Map<string, number>([["apples", 3]]);

// 1. A default value with ??
const pears = stock.get("pears") ?? 0;
console.log(pears); // 0

// 2. Store the result and check it
const apples = stock.get("apples");
if (apples !== undefined) {
    console.log(apples * 2); // 6: apples is number here
}

// 3. Update a counter in one line
stock.set("apples", (stock.get("apples") ?? 0) + 1);
console.log(stock.get("apples")); // 4

// has() does not narrow a later get():
if (stock.has("apples")) {
    const n = stock.get("apples"); // still number | undefined
    console.log(n);
}

لا يتذكر TypeScript أن has أعادت true عندما تستدعي get لاحقًا. فحص نتيجة get مباشرة أقصر وآمن في الوقت نفسه. تأكيد عدم القيمة الفارغة، stock.get("apples")!، يُسكت الخطأ لكنه لا يحميك إذا كان المفتاح غير موجود.

دوال Map وأنواعها

التكرار على Map

تُكرَّر الـ Map بترتيب الإدراج. تعطي for...of على الـ map أزواجًا بالشكل [key, value]، نوعها [K, V].

const prices = new Map<string, number>([
    ["tea", 2.5],
    ["coffee", 3.2],
    ["juice", 4],
]);

for (const [item, price] of prices) {   // item: string, price: number
    console.log(`${item}: ${price.toFixed(2)}`);
}

prices.forEach((price, item) => {       // value first, then key
    console.log(item.toUpperCase(), price);
});

const items = [...prices.keys()];       // string[]
const total = [...prices.values()].reduce((a, b) => a + b, 0);
console.log(items, total);              // [ 'tea', 'coffee', 'juice' ] 9.7

// Sorted by value: sort the entries, build a new Map
const byPrice = new Map([...prices].sort((a, b) => b[1] - a[1]));
console.log([...byPrice.keys()]);       // [ 'juice', 'coffee', 'tea' ]

إسناد قيمة لمفتاح موجود يحدّث القيمة لكنه يُبقي المفتاح في موضعه الأصلي من الترتيب.

المفاتيح من نوع كائن والعدّ

أي قيمة يمكن أن تكون مفتاحًا، بما في ذلك الكائنات والمصفوفات. تُقارن المفاتيح كما تفعل ===: كائنان لهما المحتوى نفسه مفتاحان مختلفان. والـ Map أيضًا هي الطريقة المعتادة لعدّ العناصر أو تجميعها.

const a = { id: 1 };
const b = { id: 1 };
const visits = new Map<object, number>([[a, 5]]);
console.log(visits.get(a), visits.get(b)); // 5 undefined: b is another object

// Counting words
const words = "the cat and the hat and the bat".split(" ");
const counts = new Map<string, number>();
for (const w of words) {
    counts.set(w, (counts.get(w) ?? 0) + 1);
}
console.log(counts); // Map(5) { 'the' => 3, 'cat' => 1, 'and' => 2, 'hat' => 1, 'bat' => 1 }

// Grouping into arrays
const byLength = new Map<number, string[]>();
for (const w of new Set(words)) {
    const group = byLength.get(w.length) ?? [];
    group.push(w);
    byLength.set(w.length, group);
}
console.log(byLength); // Map(1) { 3 => [ 'the', 'cat', 'and', 'hat', 'bat' ] }

لاستخدام محتوى الكائن كمفتاح، اشتق منه مفتاحًا نصيًا أو رقميًا، مثل user.id أو `${x},${y}`.

الفرق بين Map والكائن وRecord

قاعدة عملية: Map لمجموعة مفاتيحها بيانات (معرّفات مستخدمين، كلمات، عناصر ذاكرة مؤقتة) وتتغير وقت التشغيل، ونوع كائن أو Record لمجموعة ثابتة من المفاتيح المعروفة ولكل ما يُرسل إلى JSON أو يُقرأ منه. تقارن صفحة القواميس بين index signatures وRecord وMap للبحث بمفاتيح نصية.

تحويل Map إلى كائنات وJSON

عناصر الـ Map ليست خصائص، لذلك لا يراها JSON.stringify. حوّلها عبر Object.fromEntries وObject.entries:

const settings = new Map<string, string | number>([
    ["theme", "dark"],
    ["fontSize", 14],
]);

console.log(JSON.stringify(settings)); // {}

const obj = Object.fromEntries(settings); // { [k: string]: string | number }
const json = JSON.stringify(obj);
console.log(json); // {"theme":"dark","fontSize":14}

// And back again
const restored = new Map(Object.entries(JSON.parse(json) as Record<string, string | number>));
console.log(restored.get("theme")); // dark

يعيد JSON.parse النوع any، لذلك تصرّح as Record<...> بما يُتوقع أن تكون عليه البيانات. هذا ليس فحصًا وقت التشغيل، فتحقق من JSON غير الموثوق قبل أن تثق بذلك النوع.

تحديد أنواع array.map()

كثير من عمليات البحث عن "typescript map" تقصد دالة المصفوفات التي تحوّل كل عنصر وتعيد مصفوفة جديدة. يُستنتج نوعها من دالة الاستدعاء، لذلك نادرًا ما تحتاج إلى تحديد الأنواع:

type User = { id: number; first: string; last: string };
const users: User[] = [
    { id: 1, first: "Ada", last: "Lovelace" },
    { id: 2, first: "Alan", last: "Turing" },
];

const names = users.map((u) => `${u.first} ${u.last}`); // string[]
const ids = users.map((u) => u.id);                     // number[]

// An explicit result type, checked against what the callback returns
type Option = { value: number; label: string };
const options = users.map((u): Option => ({ value: u.id, label: u.first }));

// With the index
const numbered = users.map((u, i) => `${i + 1}. ${u.first}`);

console.log(names, ids);
console.log(options);
console.log(numbered);

تحديد نوع القيمة المُعادة من دالة الاستدعاء ((u): Option => ...) هو أوضح طريقة للتصريح بنوع النتيجة: عندها تصبح أي خاصية مفقودة أو مكتوبة خطأ في الكائن المُعاد خطأ ترجمة عند دالة الاستدعاء.