Dictionary ב-TypeScript: Index Signatures, Record ו-Map

ב-TypeScript אין מחלקה נפרדת של dictionary או 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, או unions שלהם.

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; ראו strict mode לשאר הדגלים שלצידה. ל-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.

במה להשתמש