TypeScriptの連想配列（辞書）: インデックスシグネチャ、Record、Map

TypeScriptには、辞書やハッシュマップ専用のクラスはありません。辞書（連想配列）は、インデックスシグネチャ { [key: string]: number } で型付けした普通のオブジェクト、同じ型を Record<string, number> と書いたもの、または Map<string, number> のどれかです。3つともキーで値を保持しますが、キーの型、存在しないキーの型、シリアライズの方法が違います。

// 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 を使います。

インデックスシグネチャ

インデックスシグネチャ [key: KeyType]: ValueType は、「この型のどんなキーもこの型の値に対応する」という意味です。キーの名前（key、name、userId）は説明のためだけのものです。キーの型には string、number、symbol、テンプレートリテラルのパターン、またはそれらのユニオンを使えます。

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' ] になります。数値のインデックスシグネチャが制限するのは、TypeScriptでのインデックスの書き方だけです。

Record<K, V>

Record<string, V> は { [key: string]: V } の省略形です。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

urls から staging を省くとコンパイルエラー TS2741（Property 'staging' is missing...）になるので、ユニオンのキーを持つ Record はチェック付きの対応表になります。Partial は各値を number | undefined にします。

ハッシュマップとしての 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 にはそうしたキーはありません。

存在しないキーの型の問題

インデックスシグネチャや 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 モード を参照してください。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 はインデックスシグネチャのプロパティに使えます。オブジェクト型の必須の名前付きプロパティに使うとコンパイルエラー TS2790 The operand of a 'delete' operator must be optional. になります。

どれを使うか