TypeScript Dictionary: Index Signature, Record ve Map

TypeScript'te ayrı bir dictionary ya da hashmap class'ı yoktur. Bir dictionary ya index signature ile tiplenmiş düz bir nesnedir, { [key: string]: number }, ya aynı tipin Record<string, number> yazımıdır ya da bir Map<string, number>'dır. Üçü de değerleri anahtara göre saklar; anahtar tiplerinde, eksik anahtarların nasıl tiplendiğinde ve nasıl serileştirildiklerinde ayrışırlar.

// 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

String anahtarlar ve JSON biçimli veri için Record<string, T> ile tiplenmiş bir nesne olağan seçimdir. String olmayan anahtarlar ya da sürekli eklenip silinen girdiler için Map kullanın.

Index Signature

Bir index signature, [key: KeyType]: ValueType, "bu tipteki her anahtar bu tipte bir değere karşılık gelir" der. Anahtarın adı (key, name, userId) yalnızca belgeleme içindir. Anahtar tipi string, number, symbol, template literal kalıpları ya da bunların union'ı olabilir.

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 number anahtarları string'e çevirir; bu yüzden bir { [id: number]: string } nesnesinin anahtarları çalışma zamanında yine string'dir: Object.keys({ 1: "one" }) sonucu [ '1' ] olur. Number index signature yalnızca TypeScript'te nesneye nasıl erişebileceğinizi kısıtlar.

Record<K, V>

Record<string, V>, { [key: string]: V } için bir kısaltmadır. string yerine literal anahtarlardan oluşan bir union verildiğinde, her anahtarı içermek zorunda olan sabit bir dictionary'ye dönüşür:

// 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

urls içinden staging anahtarını çıkarmak TS2741 derleme hatasıdır (Property 'staging' is missing...); bu da union anahtarlı Record'u denetlenen bir arama tablosu yapar. Partial her değeri number | undefined yapar.

Hash Map Olarak Map

Bir Map her tipte anahtarı kabul eder, ekleme sırasını korur, bir size değerine sahiptir ve eksik anahtarları dürüstçe tipler: get, V | undefined döndürür.

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

Bir Anahtarın Var Olup Olmadığını Kontrol Etmek

Birkaç kontrol yolu vardır ve hepsi aynı anlama gelmez:

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'");
}

Miras alınan anahtar sorunu, kullanıcıdan gelen "constructor" ya da "__proto__" gibi anahtarların düz nesneleri dictionary olarak riskli yapmasının nedenidir. Bir Map böyle anahtarlara sahip değildir.

Eksik Anahtarın Tip Sorunu

Bir index signature ya da Record<string, T> üzerinde herhangi bir anahtarı okumanın tipi T'dir, var olmayan bir anahtar için bile. Derleyici, çalışma zamanında undefined olan bir değer üzerinde metot çağırmanıza izin verir:

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 derleyici seçeneği bunu düzeltir: bu seçenekle colors["grass"] ifadesinin tipi string | undefined olur ve siz kontrol edene kadar toUpperCase çağrısı bir derleme hatasıdır. strict kapsamında değildir, bu yüzden tsconfig.json içinde ayrıca açılması gerekir; yanında duran diğer bayraklar için strict mode sayfasına bakın. Bir Map'te böyle bir boşluk yoktur, çünkü get her zaman undefined içerir.

Ekleme, Silme ve Döngü

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 özelliklerinde çalışır. Bir nesne tipinin zorunlu adlandırılmış bir özelliğinde ise TS2790 derleme hatasıdır: The operand of a 'delete' operator must be optional.

Hangisini Kullanmalı