القاموس في TypeScript: Index Signatures وRecord وMap

لا يوجد في TypeScript صنف مستقل للقاموس أو الـ hashmap. القاموس إما كائن عادي نوعه محدد بـ index signature، { [key: string]: number }، أو النوع نفسه مكتوبًا Record<string, number>، أو Map<string, number>. الثلاثة تخزن القيم بمفتاح، وتختلف في أنواع المفاتيح، وفي نوع المفاتيح الغائبة، وفي طريقة تحويلها إلى نص.

// 1. Index signature on an object
const ages: { [name: string]: number } = { ada: 36 };
ages["grace"] = 85;
ages.alan = 41;

// 2. Record: the same type, shorter to write
const prices: Record<string, number> = { tea: 2.5 };
prices["coffee"] = 3.2;

// 3. Map: a real hash map class
const stock = new Map<string, number>();
stock.set("apples", 3);

console.log(ages);            // { ada: 36, grace: 85, alan: 41 }
console.log(prices.coffee);   // 3.2
console.log(stock.get("apples")); // 3

للمفاتيح النصية والبيانات ذات شكل JSON، الكائن بالنوع Record<string, T> هو الخيار المعتاد. للمفاتيح غير النصية، أو للعناصر التي تُضاف وتُحذف باستمرار، استخدم Map.

Index Signatures

تقول index signature، [key: KeyType]: ValueType، إن "أي مفتاح من هذا النوع يرتبط بقيمة من هذا النوع". اسم المفتاح (key، name، userId) للتوثيق فقط. يمكن أن تكون أنواع المفاتيح string أو number أو symbol أو أنماط template literal أو union منها.

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

// The key name documents what the key is
const usersById: { [userId: string]: User } = {
    u1: { name: "Ada", admin: true },
};
usersById["u2"] = { name: "Grace", admin: false };

// Index signature plus named properties: named ones must fit the signature
type Scores = {
    total: number;
    [player: string]: number;
};
const scores: Scores = { total: 12, ada: 7, alan: 5 };

// Every value is checked against the value type
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
scores.grace = "nine";

console.log(Object.keys(usersById), scores.total);

تحوّل JavaScript مفاتيح الأرقام إلى نصوص، لذلك يبقى للكائن { [id: number]: string } مفاتيح نصية وقت التشغيل: Object.keys({ 1: "one" }) يعطي [ '1' ]. الـ index signature الرقمية تقيّد فقط طريقة الفهرسة في TypeScript.

Record<K, V>

Record<string, V> اختصار لـ { [key: string]: V }. وعند استخدام union من مفاتيح حرفية بدلًا من string يصبح قاموسًا ثابتًا يجب أن يحتوي على كل مفتاح:

// Open dictionary: any string key
const counts: Record<string, number> = {};
for (const word of ["a", "b", "a"]) {
    counts[word] = (counts[word] ?? 0) + 1;
}
console.log(counts); // { a: 2, b: 1 }

// Closed dictionary: exactly these keys, all required
type Env = "dev" | "staging" | "prod";
const urls: Record<Env, string> = {
    dev: "http://localhost:3000",
    staging: "https://staging.example.com",
    prod: "https://example.com",
};
console.log(urls.prod);

// Some of the keys: wrap in Partial
const overrides: Partial<Record<Env, number>> = { prod: 5 };
console.log(overrides.dev ?? "default"); // default

حذف staging من urls خطأ ترجمة TS2741 (Property 'staging' is missing...)، وهذا ما يجعل Record بمفاتيح union جدول بحث مفحوصًا. ويجعل Partial كل قيمة من النوع number | undefined.

Map كـ Hash Map

تقبل الـ Map مفاتيح من أي نوع، وتحفظ ترتيب الإدراج، ولها size، وتحدد نوع المفاتيح الغائبة بصدق: تعيد get النوع V | undefined.

type Point = { x: number; y: number };

// Object keys work: compared by identity
const home: Point = { x: 0, y: 0 };
const labels = new Map<Point, string>([[home, "home"]]);
console.log(labels.get(home)); // home

// A string key built from the contents, for lookup by value
const grid = new Map<string, string>();
const key = (p: Point) => `${p.x},${p.y}`;
grid.set(key({ x: 2, y: 3 }), "tree");
console.log(grid.get(key({ x: 2, y: 3 }))); // tree
console.log(grid.get(key({ x: 9, y: 9 })) ?? "empty"); // empty
console.log(grid.size); // 1

التحقق من وجود مفتاح

توجد عدة طرق للفحص، ولا تعني كلها الشيء نفسه:

const dict: Record<string, number> = { zero: 0, one: 1 };

console.log(Object.hasOwn(dict, "zero"));   // true: own property
console.log("zero" in dict);                // true
console.log("toString" in dict);            // true: inherited from Object.prototype!
console.log(Object.hasOwn(dict, "toString")); // false

console.log(dict["zero"] !== undefined);    // true
console.log(dict["zero"] ? "truthy" : "falsy"); // falsy: 0 is falsy, the key exists

const value = dict["two"];
if (value !== undefined) {
    console.log(value.toFixed(1)); // not reached
} else {
    console.log("no key 'two'");
}

مشكلة المفاتيح الموروثة هي السبب في أن المفاتيح التي يقدمها المستخدمون مثل "constructor" أو "__proto__" تجعل الكائنات العادية خطرة كقواميس. أما الـ Map فليس فيها مفاتيح كهذه.

مشكلة نوع المفتاح الغائب

في index signature أو Record<string, T> تكون قراءة أي مفتاح من النوع T، حتى لو لم يكن المفتاح موجودًا. يسمح لك المترجم باستدعاء دوال على قيمة هي undefined وقت التشغيل:

const colors: Record<string, string> = { sky: "blue" };

const grass = colors["grass"]; // type: string, value: undefined
console.log(typeof grass);     // undefined

try {
    console.log(grass.toUpperCase()); // compiles, then throws
} catch (e) {
    if (e instanceof Error) console.log(e.message);
}

خيار المترجم noUncheckedIndexedAccess يحل ذلك: معه يصبح نوع colors["grass"] هو string | undefined، ويصبح استدعاء toUpperCase خطأ ترجمة إلى أن تفحص القيمة. هذا الخيار ليس جزءًا من strict، لذلك يجب تفعيله بشكل منفصل في tsconfig.json؛ راجع الوضع الصارم لبقية الخيارات المجاورة له. والـ Map لا تعاني هذه الفجوة، لأن get تتضمن undefined دائمًا.

الإضافة والحذف والتكرار

const inventory: Record<string, number> = { apples: 3, pears: 0 };

inventory["kiwis"] = 12;   // add or update
delete inventory["pears"]; // remove: allowed on index signatures

for (const [item, qty] of Object.entries(inventory)) { // [string, number]
    console.log(item, qty);
}

console.log(Object.keys(inventory).length); // 2 (the size)

// Map equivalents
const m = new Map(Object.entries(inventory)); // Map<string, number>
m.delete("apples");
console.log(m.size, [...m.keys()]); // 1 [ 'kiwis' ]

يعمل delete مع خصائص index signature. أما مع خاصية مسماة إلزامية في نوع كائن فهو خطأ ترجمة TS2790، The operand of a 'delete' operator must be optional.

أيها تستخدم