TypeScript 딕셔너리: 인덱스 시그니처, Record, Map

TypeScript에는 별도의 딕셔너리나 해시맵 클래스가 없습니다. 딕셔너리는 인덱스 시그니처 { [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)

인덱스 시그니처 [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.입니다.

무엇을 쓸까