Implementing Dictionary Types in TypeScript: Index Signatures and Record Utility Explained

Traditional Dictionary Implementation in JavaScript

In JavaScript development, using plain objects as dictionaries or maps is a common pattern. Developers typically implement key-value storage and access through dynamic property assignment:

var people = {};
people["john@example.com"] = {name: "John", age: 30};
var person = people["john@example.com"];
delete people["john@example.com"];

While this pattern is straightforward, it requires explicit type annotations in TypeScript to ensure type safety. When migrating from JavaScript to TypeScript, developers face the key challenge of providing appropriate type definitions for such dynamic structures.

TypeScript Index Signatures Fundamentals

TypeScript provides type support for dynamic property access through index signatures. Index signatures allow us to define type constraints for unknown property names in objects:

interface StringToCustomerMap {
    [email: string]: Customer;
}

In this example, the StringToCustomerMap interface declares that any string key will return a value of type Customer. This definition ensures type safety:

var map: StringToCustomerMap = {};
map["foo@gmail.com"] = new Customer(); // Correct
map[14] = new Customer(); // Error: number not assignable to string index
map["bar@hotmail.com"] = "x"; // Error: string not assignable to Customer type

Record Utility Type

In newer TypeScript versions, the Record<K, T> utility type provides a more concise way to define dictionary types:

type Customers = Record<string, Customer>;

Record<string, Customer> is functionally equivalent to { [key: string]: Customer } but offers more concise syntax. The Record type accepts two type parameters: key type and value type, providing a standardized solution for common mapping scenarios.

Type Constraints in Index Signatures

Index signatures support various key types including string, number, symbol, and union types composed of these. When using both numeric and string indices simultaneously, special attention must be paid to type consistency:

interface NumberDictionary {
    [index: string]: number;
    length: number; // Correct: compatible with index signature type
    name: string; // Error: conflicts with index signature type
}

Since JavaScript converts numeric keys to strings when accessing object properties, the return type of a numeric indexer must be a subtype of the string indexer's return type to ensure type safety.

Map Object Alternative

In addition to plain objects, TypeScript supports ES6 Map objects, available when compiling to ES6 or using appropriate polyfills:

let people = new Map<string, Person>();
people.set("john@example.com", {firstName: "John", lastName: "Doe"});
let person = people.get("john@example.com");
people.delete("john@example.com");

Map objects offer several advantages over plain objects: support for keys of any type (including objects), richer API (such as size, clear(), forEach()), and performance optimizations for frequent addition and deletion scenarios.

Practical Scenario Comparison

When choosing a dictionary implementation, multiple factors should be considered:

Index Signature Objects are suitable for simple key-value storage, particularly when keys are strings and the structure is relatively stable. Their advantages include compatibility with existing JavaScript code and convenient serialization.

Record Type provides more modern and concise syntax, especially useful in type aliases to improve code readability and maintainability.

Map Objects are appropriate for scenarios requiring complex key types, frequent addition/deletion operations, or rich built-in methods. They offer better type safety and avoid potential conflicts with object prototype chains.

Best Practice Recommendations

Based on different usage scenarios, we recommend the following practices:

For simple configuration objects or data transfer, using index signatures or Record types provides good type safety and development experience. When defining interfaces, explicit index signatures aid documentation and type checking.

When dealing with dynamic, frequently changing data structures, Map objects are the better choice. Their methods are specifically designed for mapping operations, offering better performance and richer functionality.

In team collaboration projects, it's recommended to standardize on one pattern to improve code consistency. For new projects, prioritize using Map objects; for migrating existing projects, choose the most suitable solution based on specific circumstances.