typescript dictionary
Typescript Dictionary

In the realm of modern programming, efficient data management is paramount. You may be building web applications, APIs, or complex software systems. The ability to organize and manipulate data well is key. It can improve your projects’ functionality and performance. This is where TypeScript dictionaries come into play.

A TypeScript dictionary stores key-value pairs. It lets developers link values to unique keys and get them quickly. Developers use this data structure in TypeScript and JavaScript. It has many uses. They range from managing settings to caching and handling user input.

In this guide, we will explore TypeScript dictionaries. We will look at their usage, implementation, and the operations you can do on them. We will cover basic concepts and advanced techniques. Are you a beginner learning TypeScript basics? Or, are you an experienced developer seeking to optimize your code? Understanding TypeScript dictionaries will improve your skills. They will help you build robust and maintainable software.

Demystifying Dictionaries: Key-Value Powerhouses

A dictionary is a key data structure. It stores key-value pairs. It’s also known as a hash map or associative array. Each key is an identifier for a value. It allows for fast data retrieval and manipulation. Dictionaries excel in situations where you need to:

  • Map data to unique identifiers: Imagine a user profile with an ID as the key and the user’s information as the value.
  • Implement fast lookups: Retrieving data with a known key is fast. It happens in constant time on average. This makes dictionaries ideal for scenarios where fast access is crucial.
  • Store heterogeneous data: Dictionaries allow you to store many data types. These include strings, numbers, objects, and arrays. They provide flexibility in managing data in your application.

What is a TypeScript Dictionary?

A TypeScript dictionary is also called a map or associative array. It is a collection of key-value pairs, where each key is unique. Arrays use numeric indices. In contrast, dictionaries allow you to use any key to access its value. This flexibility makes dictionaries powerful. They organize and manipulate data in TypeScript apps.

Why Use Dictionaries in TypeScript?

  • Organization: Keep your data neatly categorized for easy retrieval.
  • Efficiency: Quickly access information using unique keys.
  • Type Safety: Prevent errors by ensuring expected data types.
  • Flexibility: Adapt dictionary types to fit your specific needs.

By utilizing TypeScript dictionaries, you can create well-structured, type-safe, and efficient programs that make managing your data a breeze!

Here’s a glimpse into how to create a type-safe dictionary in TypeScript.  TypeScript dictionary example:

Example 1. A Simple String-Number Dictionary

let personAges: Map<string, number> = new Map<string, number>();
personAges.set("Alice", 30);
personAges.set("Bob", 25);

console.log(personAges.get("Alice")); // Output: 30

In this example, personAges is a dictionary specifically designed to hold key-value pairs where keys are strings (names) and values are numbers (ages). TypeScript prevents you from accidentally storing a non-string key or a non-number value.

Example 2: Leveraging Interfaces for Complex Values

interface Product {
  name: string;
  price: number;

let products: Map<number, Product> = new Map<number, Product>();
products.set(100, { name: "Shirt", price: 20 });

console.log(products.get(100).name); // Output: Shirt

Here, we define an interface Product to specify the structure of product data (name and price). The dictionary products can only store key-value pairs where keys are numbers (product IDs) and values conform to the Product interface.

Why TypeScript Dictionary Matter

Traditional JavaScript dictionaries are easy to use. However, they lack type definitions for keys and values. This can lead to several challenges:

  • Runtime Errors: Assigning incompatible data types to keys or values can result in unexpected errors only revealed during runtime.
  • Reduced Code Clarity: Lack of type definitions makes code less readable and maintainable, especially in complex projects.
  • Debugging Challenges: Identifying issues caused by incorrect data types within dictionaries becomes more difficult after writing and potentially deploying code.

TypeScript dictionary or dictionaries address these issues by introducing type annotations. By explicitly defining the expected types for keys and values, you gain several advantages:

  • Improved Code Clarity: Your code becomes self-documenting, clearly conveying the intended data structure.
  • Enhanced Developer Experience: TypeScript’s static type checker identifies potential type mismatches during development, preventing runtime errors.
  • Increased Maintainability: Type annotations make it easier for other developers to understand how to interact with your code’s dictionaries.
  • Reduced Refactoring Efforts: Catching type issues early on leads to less refactoring work later in the development process.

What is a Type-Safe Dictionary?

A type-safe dictionary is a data structure that stores information like a regular dictionary, but with an added layer of control. It enforces specific data types for both the keys (which act like labels) and the values (the actual information). This means you define what kind of data each part of the dictionary can hold, preventing unexpected errors and making your code more robust.

Benefits of Type-Safe Dictionaries:

  • Early Error Detection: Type-checking happens during compilation (when your code is converted into machine code), so you catch errors before your program even runs.
  • Improved Code Readability: By specifying data types, you make your code easier to understand for yourself and others. It’s clear what kind of information each part of the dictionary holds.
  • Reduced Runtime Errors: Type safety prevents issues that might arise at runtime (when the program is actually running) due to unexpected data types.

Create a type-safe dictionary in a few simple steps:

  • Declaring and Initializing: You can use the Map object and specify the data types for keys and values.
const characterProfiles: Map<string, Character> = new Map();

In this example, characterProfiles is a dictionary where keys are strings (representing character names) and values are of type Character, which might be a custom type defined elsewhere.

  • Combining Key-Value Pairs: Use the set method of the Map object to add key-value pairs.
characterProfiles.set("Anya", { name: "Anya", age: 25, class: "Mage" });
characterProfiles.set("Boris", { name: "Boris", age: 30, class: "Warrior" });
  • Checking Key Existence: Use the has method to check if a specific key exists in the dictionary.
if (characterProfiles.has("Anya")) {
    console.log("Found Anya's profile!");
  • Obtaining Value by Key: Use the get method to retrieve the value associated with a specific key.
const anyaProfile = characterProfiles.get("Anya");
if (anyaProfile) {
    console.log("Anya's class:", anyaProfile.class);
  • Removing Key-Value Pair: Use the delete method to remove a key and its corresponding value.
  • Iterating Over the Dictionary: Use a loop with the entries method to iterate through all key-value pairs.
for (const [name, profile] of characterProfiles.entries()) {
    console.log(name, profile.age);
  • Calculating Size: Use the size property of the Map object to get the number of key-value pairs stored.
const numProfiles = characterProfiles.size;
console.log("Number of profiles:", numProfiles);

Example: A Character Profile with Type Safety

Let’s build a character profile using a type-safe dictionary in TypeScript (a language that adds types to JavaScript):

type Character = {
  name: string;
  age: number;
  class: string; // Could be "warrior", "mage", etc.

const characterProfile: Character = {
  name: "Anya",
  age: 25,
  class: "Mage",

Here, we define a Character type that specifies the data types for each key:

  • name must be a string (text).
  • age must be a number.
  • class must be a string, but restricted to specific values like “warrior” or “mage”.

This ensures that only the intended data types are stored in the dictionary, making our code more reliable.

Building Your Type-Safe Dictionary: Implementation Approaches

TypeScript offers several ways to create type-safe dictionaries. Here’s a breakdown of the most common approaches:

  1. Object Literal Notation with Index Signatures:

This approach utilizes TypeScript’s index signatures to define the type of keys and values for an object literal.

interface Person {
  name: string;
  age: number;

const people: { [key: string]: Person } = {
  john: { name: "John Doe", age: 30 },
  jane: { name: "Jane Doe", age: 25 },

In this example, the people dictionary expects keys to be strings and values to be objects of type Person. The index signature [key: string]: Person enforces this type safety.

  1. Interface with Index Signature:

Similar to object literal notation, you can define an interface with an index signature to create a reusable dictionary type.

interface StringDictionary {
  [key: string]: string;

const productCodes: StringDictionary = {
  A123: "Product X",
  B456: "Product Y",

Here, the StringDictionary interface dictates that keys are strings and values are also strings.

  1. Generic Types with Record<Keys, Type>:

TypeScript’s built-in Record<Keys, Type> utility type creates a dictionary type with generic placeholders for key and value types.

type NumberDictionary<T> = Record<string, T>;

const scores: NumberDictionary<number> = {
  Alice: 90,
  Bob: 85,

This approach offers flexibility by allowing you to specify the value type as a generic parameter T.

  1. Using the Map Object:

The native Map object in JavaScript provides an ordered collection of key-value pairs. TypeScript leverages generics to enable type-safe usage of Map.

const studentDetails = new Map<string, string>(); 
 studentDetails.set("1234", "John Doe"); 
 studentDetails.set("5678", "Jane Doe");

By explicitly defining the key and value types within the Map constructor, you achieve type safety.

Choosing the Right Approach: A Matter of Context

The optimal approach for creating dictionaries in TypeScript depends on your specific needs. Here’s a breakdown to guide your decision:

  • For simple, type-safe dictionaries: Use the built-in Map object with generics.
  • For defining reusable dictionary types: Utilize generics and index signatures.
  • For concise code when types are clear upfront: Leverage the Record<Keys, Type> utility.

Essential Operations for Your TypeScript Dictionary Toolkit

Once you’ve created your TypeScript dictionary, you’ll likely encounter situations where you need to perform various operations on it. Here’s a breakdown of some key methods:

  • set(key: K, value: V): Adds a new key-value pair to the dictionary.
  • get(key: K): Retrieves the value associated with the specified key.
  • has(key: K): Checks if a particular key exists in the dictionary.
  • delete(key: K): Removes the key-value pair linked

Common Operations with TypeScript Dictionaries

Implementing dictionaries in TypeScript is straightforward. You can define a dictionary using the Record type, specifying the types for keys and values. For example:

const myDictionary: Record<string, number> = {
 "apple": 5,
 "banana": 10,
 "orange": 7

In this example, myDictionary is a dictionary where keys are strings and values are numbers.

  1. Adding and Updating Entries: Dictionaries in TypeScript are mutable, allowing you to add new entries or update existing ones easily.
myDictionary["grape"] = 8; // Adding a new entry
myDictionary["apple"] = 6; // Updating an existing entry
  1. Accessing Entries: You can access dictionary entries using square bracket notation or the . notation.
console.log(myDictionary["banana"]); // Output: 10
console.log(myDictionary.orange); // Output: 7
  1. Iterating Over Entries: TypeScript dictionaries support iteration using loops or methods like forEach.
for (const key in myDictionary) {
 console.log(`${key}: ${myDictionary[key]}`);

// Using forEach
Object.entries(myDictionary).forEach(([key, value]) => {
 console.log(`${key}: ${value}`);
  1. Checking Existence: You can check if a key exists in a dictionary using the in operator or the hasOwnProperty method.
if ("apple" in myDictionary) {
   console.log("Apple exists in the dictionary");

if (myDictionary.hasOwnProperty("grape")) {
   console.log("Grape exists in the dictionary");

Also Learn:

  1. TypeScript vs JavaScript
  2. Difference Between Array and Pointer

Common Use Cases for TypeScript Dictionary:

Now that we understand how to implement dictionaries in TypeScript, let’s explore some common use cases where dictionaries prove to be invaluable:

  1. Configuration Management: Dictionaries can be used to store configuration settings where each key represents a configuration parameter, and its value represents the corresponding setting. TypeScript Dictionary Example:

    const config: Record<string, any> = {
     "theme": "dark",
     "fontSize": 14,
     "showNotifications": true
  2. Caching: In web applications, dictionaries can be utilized for caching frequently accessed data to improve performance and reduce redundant computations.

    const cache: Record<string, any> = {};
    async function fetchDataFromAPI(endpoint: string) {
        if (cache.hasOwnProperty(endpoint)) {
            return cache[endpoint];
        } else {
            const response = await fetch(endpoint); // Fetch data from API
            const data = await response.json(); // Assuming response is JSON
            cache[endpoint] = data;
            return data;
  3. Data Transformation: Dictionaries are useful for transforming data from one format to another, such as converting JSON objects into a more structured format.

  4. Grouping Data: Dictionaries are useful for grouping data based on specific criteria, such as categorizing products by their type.
    const products: Record<string, string[]> = {
      "fruits": ["apple", "banana", "orange"],
      "vegetables": ["carrot", "spinach", "potato"]
  5. Error Handling: Dictionaries can store error codes and their corresponding error messages, making it easier to handle and display errors in the application.

  6. Event Handling: In event-driven programming, dictionaries can be used to manage event listeners, with keys representing event names and values representing callback functions.

JavaScript vs. TypeScript Dictionary

While JavaScript offers basic dictionary functionality through objects, TypeScript takes it a step further. Here’s the key difference:

  • JavaScript Dictionaries: These are inherently flexible, allowing you to store various data types under the same key. However, this flexibility can lead to runtime errors if you accidentally store the wrong data type.

  • TypeScript Dictionaries: TypeScript shines with its type safety. You can define the expected data types for both keys and values, preventing unexpected behavior and ensuring cleaner, more reliable code.

Examples of TypeScript Dictionary Usage:

1. Student Grades Record

Consider a scenario where we need to store the grades of students keyed by their names. We can utilize a TypeScript dictionary for this purpose:

// Define a dictionary to store student grades
let studentGrades: { [key: string]: number } = {
    "Alice": 85,
    "Bob": 90,
    "Charlie": 78,
    "Diana": 95

// Accessing grades using student names
console.log(studentGrades["Alice"]); // Output: 85
console.log(studentGrades["Bob"]);   // Output: 90

In this example, studentGrades serves as a dictionary where student names act as keys and their corresponding grades as values. We can easily retrieve grades by referencing the student names.

2. Product Catalog

Suppose we are building an e-commerce platform and need to maintain a catalog of products with their prices. TypeScript dictionaries can efficiently handle this scenario:

// Define a dictionary to store product prices
let productPrices: { [key: string]: number } = {
    "Laptop": 999,
    "Smartphone": 699,
    "Headphones": 99,
    "Tablet": 399

// Accessing prices using product names
console.log(productPrices["Laptop"]);    // Output: 999
console.log(productPrices["Smartphone"]); // Output: 699

Here, productPrices acts as a dictionary where product names serve as keys and their corresponding prices as values, enabling seamless price retrieval based on product names.

3. A Simple Dictionary

Let’s create a dictionary to store student information:

type Student = {
  name: string;
  age: number;

const students: Map<string, Student> = new Map();

students.set("Alice", { name: "Alice", age: 20 });
students.set("Bob", { name: "Bob", age: 22 });

console.log(students.get("Alice")); // { name: "Alice", age: 20 }

Here, the Student type defines the structure for student data. Our students dictionary uses strings (student IDs) as keys and Student objects as values.

4. Using Generics for Flexibility

Want a dictionary that can hold any key-value combination? TypeScript generics allow that!

type Dictionary<K, V> = {
  [key in K]: V;

const productCodes: Dictionary<string, number> = {};
productCodes["A100"] = 123;
productCodes["B200"] = 456;

const orderDetails: Dictionary<number, string> = {};
orderDetails[101] = "Pending";
orderDetails[102] = "Shipped";

This generic Dictionary type lets you define key and value types on the fly. The productCodes dictionary uses strings for keys and numbers for values, while orderDetails uses numbers for keys and strings for values.

5. Using Generics with Object Literals:

Generics are a powerful TypeScript feature that allows you to define dictionaries with flexible data types.

// Define a generic dictionary type (key: any type, value: any type)
type MyDictionary<K, V> = { [key in K]: V };

// Create a dictionary to store phone numbers (key: string - name, value: string - phone number)
const phonebook: MyDictionary<string, string> = {};
phonebook["Alice"] = "123-456-7890";
phonebook["Bob"] = "987-654-3210";

This example creates a more generic dictionary (MyDictionary) that can hold any data type for both keys and values. However, you can then create specific instances with defined types, like the phonebook dictionary which holds names as keys and phone numbers as values.


In conclusion, the TypeScript dictionary is a versatile data structure that play a vital role in TypeScript programming. By mastering dictionaries, you can enhance the efficiency, readability, and maintainability of your TypeScript code. Whether you’re building web applications, APIs, or command-line utilities, incorporating dictionaries into your development toolkit will elevate your TypeScript programming skills.

Start implementing TypeScript dictionaries in your projects today and unlock a world of possibilities in TypeScript development!

Follow Us on Facebook for the Latest Updates.


What's the difference between a regular JavaScript object and a TypeScript dictionary?

While both store key-value pairs, TypeScript dictionaries leverage type annotations to define the expected types for both keys and values. This enforces type safety, preventing unexpected behavior and errors. Regular JavaScript objects lack this type of enforcement.

When should I use a TypeScript dictionary?

Use TypeScript dictionaries whenever you want to ensure type safety and clarity in your data structures. This is particularly helpful for complex objects, configuration settings, user data management, and maintaining consistency across your codebase.

Are there any downsides to using TypeScript dictionaries?

While generally beneficial, TypeScript dictionaries add some overhead compared to plain JavaScript objects. The type annotations can increase code size slightly, and there might be a small learning curve for developers unfamiliar with TypeScript concepts.

Can I use existing JavaScript libraries with TypeScript dictionaries?

Yes, most JavaScript libraries work seamlessly with TypeScript dictionaries. The type annotations in your dictionaries help bridge the gap between the library's expected data types and your code.