A Deep Dive into TypeScript Map: Master the Essentials

Written by - Deepak Prasad

A TypeScript Map is a collection of key-value pairs where each unique key maps to a single value. While JavaScript has had the Map object since ES6, TypeScript further extends its usability and effectiveness by allowing you to add type annotations. A TypeScript Map ensures type safety and brings object-oriented programming features into the simple key-value store.

A TypeScript Map is a powerful, flexible, and type-safe way to handle collections of key-value pairs in your application.


Basic Syntax to use TypeScript Map

Declaring a Map

In TypeScript, declaring a Map involves specifying the types for the keys and values that the Map will hold. This enhances type safety and ensures that you can only insert elements that adhere to the specified types. Here's how you can declare a Map in TypeScript:

// Declare a Map with number keys and string values
let myMap: Map<number, string> = new Map();

// Declare a Map with string keys and boolean values
let anotherMap: Map<string, boolean> = new Map();

Inserting Elements

To insert elements into a TypeScript Map, you can use the set method. This method takes two arguments: the key and the value. Here's an example:

// Declare a Map with number keys and string values
let myMap: Map<number, string> = new Map();

// Inserting elements into the Map
myMap.set(1, 'apple');
myMap.set(2, 'banana');
myMap.set(3, 'cherry');

// Attempting to insert an incorrect type will result in a compile-time error
// myMap.set('four', 'date');  // This will throw a TypeScript error

In the example above, myMap is of type Map<number, string>, which means it will only accept numbers as keys and strings as values. If you try to insert a different type, TypeScript will throw a compile-time error.

The set method is chainable, so you can insert multiple elements like this:

myMap.set(1, 'apple').set(2, 'banana').set(3, 'cherry');

The TypeScript Map set method ensures that each key is unique. If you try to insert a key-value pair using a key that already exists, the new value will overwrite the existing value.


How to Add Type Annotations to Map

In TypeScript, type annotations add an extra layer of type safety to your code. They indicate the type of value that a variable should hold. When it comes to Maps, type annotations specify the types for both keys and values that the Map will contain.

Here's how you can add type annotations to a TypeScript Map:

// Using type annotations to declare a Map with number keys and string values
let numToStrMap: Map<number, string> = new Map<number, string>();

// Using type annotations to declare a Map with string keys and boolean values
let strToBoolMap: Map<string, boolean> = new Map<string, boolean>();

In the above examples, numToStrMap is annotated to be of type Map<number, string>, which means it will accept numbers as keys and strings as values. Likewise, strToBoolMap will accept strings as keys and booleans as values.

Type annotations for Maps in TypeScript provide two key advantages:

  1. They enable TypeScript to catch type errors at compile time, improving code quality.
  2. They make the code more readable and maintainable by providing explicit information about the types of keys and values the Map can hold.

Here's an example demonstrating how to use type annotations while working with a TypeScript Map:

// Declaring a Map with type annotations for keys of type string and values of type number
let studentGrades: Map<string, number> = new Map<string, number>();

// Correct usage: Adding entries to the Map
studentGrades.set('Alice', 90);
studentGrades.set('Bob', 85);
studentGrades.set('Charlie', 92);

// Incorrect usage: This will result in a TypeScript compile-time error
// studentGrades.set(100, 'Ninety');  // Error: Argument types do not match the type annotations

In the above example, studentGrades is a TypeScript Map that is meant to hold student names (strings) as keys and their grades (numbers) as values. Thanks to type annotations, any attempt to add entries with the wrong types will result in a compile-time error.


Common Operations

1. Adding and Deleting Elements

In TypeScript, Maps offer various methods for adding, updating, and deleting key-value pairs. The most commonly used methods for these operations are set() for adding and updating elements, and delete() for removing elements.

Adding Elements

To add a new key-value pair to a TypeScript Map, you can use the set() method. This method takes two arguments: the key and the value.

let myMap: Map<string, number> = new Map();
myMap.set("apple", 1);
myMap.set("banana", 2);

Deleting Elements

To remove an element from the Map, you can use the delete() method. This method takes one argument: the key of the element to be deleted.

myMap.delete("apple");  // This will remove the key-value pair ("apple", 1)

2. Looping Through Elements

TypeScript Maps can be iterated through in multiple ways. You can use forEach, for-of loops, or built-in iterators like keys(), values(), and entries().

Using forEach

myMap.forEach((value, key) => {
  console.log(`Key: ${key}, Value: ${value}`);

Using for-of with entries()

for (let [key, value] of myMap.entries()) {
  console.log(`Key: ${key}, Value: ${value}`);

3. Example with Common Operations

Here's a simple example that demonstrates adding, deleting, and looping through elements in a TypeScript Map:

// Declaring a TypeScript Map
let fruits: Map<string, number> = new Map();

// Adding elements
fruits.set("apple", 1);
fruits.set("banana", 2);
fruits.set("cherry", 3);

// Deleting an element

// Looping through elements using forEach
fruits.forEach((value, key) => {
  console.log(`Key: ${key}, Value: ${value}`);

// Looping through elements using for-of and entries()
for (let [key, value] of fruits.entries()) {
  console.log(`Key: ${key}, Value: ${value}`);


Different TypeScript Map Methods

The Map object in TypeScript comes with a set of built-in methods that allow you to perform various operations like adding, retrieving, checking, deleting, and clearing key-value pairs. Below are the essential methods you need to know when working with a TypeScript Map.


1. set()

The set() method adds or updates a key-value pair in the Map. If the key already exists, the value is updated; otherwise, a new key-value pair is added to the Map.

let map: Map<string, number> = new Map();
map.set("one", 1);
map.set("two", 2);


2. get()

The get() method retrieves the value associated with a specific key. If the key does not exist, it returns undefined.

let valueOne = map.get("one");  // Output will be 1
let valueThree = map.get("three");  // Output will be undefined


3. has()

The has() method checks if a specific key exists in the Map and returns a boolean value (true or false).

let hasOne = map.has("one");  // Output will be true
let hasThree = map.has("three");  // Output will be false


4. delete()

The delete() method removes a key-value pair from the Map based on the key provided. It returns true if the element existed and has been removed, or false if the element does not exist.

let isDeleted = map.delete("one");  // Output will be true


5. clear()

The clear() method removes all key-value pairs from the Map, making it empty.

map.clear();  // This will empty the map

Example Demonstrating All Methods

Here is an example that demonstrates all these methods in action:

// Create a new TypeScript Map
let myMap: Map<string, number> = new Map();

// Using set()
myMap.set("apple", 10);
myMap.set("banana", 20);

// Using get()
console.log(myMap.get("apple"));  // Output: 10

// Using has()
console.log(myMap.has("banana"));  // Output: true
console.log(myMap.has("grapes"));  // Output: false

// Using delete()

// Using clear()


Different methods to Iterate over Maps

Iterating over Maps in TypeScript can be achieved in multiple ways, mainly through the forEach method and the for...of loop. Below are examples that demonstrate these approaches.


1. forEach Method

The forEach method allows you to iterate over each key-value pair in the Map. This method takes a callback function that is called for each pair in the Map.

let myMap: Map<string, number> = new Map();
myMap.set("apple", 10);
myMap.set("banana", 20);

// Using forEach
myMap.forEach((value, key) => {
  console.log(`Key is ${key} and value is ${value}`);

// Output will be:
// Key is apple and value is 10
// Key is banana and value is 20


2. for...of Loop

The for...of loop allows you to traverse through the Map using the keys(), values(), and entries() methods, which return iterators.

// Using for...of with keys()
for (let key of myMap.keys()) {
  console.log(`Key: ${key}`);
// Output will be:
// Key: apple
// Key: banana

// Using for...of with values()
for (let value of myMap.values()) {
  console.log(`Value: ${value}`);
// Output will be:
// Value: 10
// Value: 20

// Using for...of with entries()
for (let [key, value] of myMap.entries()) {
  console.log(`Key is ${key} and value is ${value}`);
// Output will be:
// Key is apple and value is 10
// Key is banana and value is 20


How TypeScript enhances JavaScript Maps

TypeScript offers a range of built-in utility types that can enhance how you work with JavaScript Maps. These utility types can provide more flexibility and stronger type safety.

1. Record

The Record type allows you to create an object type where keys are specific strings and values are of a specific type. Although not exactly the same as a TypeScript Map, it provides similar functionality for mapping keys to values.

type MyRecord = Record<string, number>;

const myRecord: MyRecord = {
  apple: 10,
  banana: 20

2. Partial and Readonly

While TypeScript doesn't offer utility types specifically designed for Maps, you can still use utility types like Partial and Readonly to create new types based on existing types, though these are generally more useful for objects than for Maps.

3. Type Aliases and Interfaces

TypeScript allows you to create type aliases and interfaces that can specify the types for the keys and values in a Map.

type FruitMap = Map<string, number>;

const myFruitMap: FruitMap = new Map();
myFruitMap.set("apple", 10);

Or using an interface:

interface IFruitMap extends Map<string, number> {}

const myFruitMap: IFruitMap = new Map();
myFruitMap.set("apple", 10);


Conversion Between Array and Map

In TypeScript, it's common to find scenarios where you need to convert between arrays and Maps. Two useful techniques for doing this include using Array.from and the spread operator. Below are some examples to illustrate these conversions.

1. Using Array.from

You can convert a Map to an array of key-value pairs (which themselves are arrays) using the Array.from method. Here's how:

const myMap = new Map<string, number>();
myMap.set("apple", 10);
myMap.set("banana", 20);

const arrayFromMap = Array.from(myMap);
console.log(arrayFromMap); // Output: [["apple", 10], ["banana", 20]]

To convert this array back to a TypeScript Map, you can again use Array.from.

const newMap = new Map(arrayFromMap);
console.log(newMap); // Output: Map { 'apple' => 10, 'banana' => 20 }

2. Using Spread Operator

The spread operator can also be used to convert a TypeScript Map to an array or to create a new Map from an array of key-value pairs.

const myMap = new Map<string, number>();
myMap.set("apple", 10);
myMap.set("banana", 20);

// Convert Map to Array
const arrayFromMap = [...myMap];
console.log(arrayFromMap); // Output: [["apple", 10], ["banana", 20]]

// Convert Array to Map
const newMap = new Map([...arrayFromMap]);
console.log(newMap); // Output: Map { 'apple' => 10, 'banana' => 20 }

In both examples, we successfully converted between a TypeScript Map and an array using Array.from and the spread operator.


Performance Considerations

When it comes to data storage in TypeScript, you generally have two main options: using an object or a Map. Both have their pros and cons, but understanding when to use one over the other is crucial for optimizing performance. Here are some considerations to keep in mind.

1. Lookup Speed

Both Maps and objects have fast lookups (O(1) on average). However, Maps in TypeScript are implemented to be more efficient when it comes to frequent additions and deletions of key-value pairs.

// Using Object
const obj = {
  "apple": 10,
  "banana": 20
console.log(obj["apple"]); // Output: 10

// Using TypeScript Map
const myMap = new Map<string, number>();
myMap.set("apple", 10);
console.log(myMap.get("apple")); // Output: 10

2. Iteration

Maps are more efficient when it comes to iteration, as they maintain the order of insertion, unlike objects. So if the order of elements matters to you, Maps should be your go-to choice.

// Iterating over a TypeScript Map
myMap.forEach((value, key) => {
  console.log(`${key}: ${value}`);
// Output:
// apple: 10

// Iterating over an Object (order not guaranteed)
for (const key in obj) {
  console.log(`${key}: ${obj[key]}`);
// Output could be:
// apple: 10
// banana: 20


Frequently Asked Questions

Why Should I Use a Map Over an Object?

The Map data structure in TypeScript offers several advantages over objects. These include the ability to have any type of key, maintaining insertion order, and better performance for frequent additions and removals. It also comes with built-in methods to manipulate data easily.

Can I Use a Map in Interfaces?

Yes, you can define an interface that includes a Map. You can specify the types for the keys and values to maintain type safety.

How Can I Iterate Over a TypeScript Map?

TypeScript offers multiple ways to iterate over a Map, such as using the forEach method or the for...of loop.

Is Map Faster Than an Object?

It depends on the use-case. For general-purpose key-value storage with any key type, Maps may offer better performance, especially when there are frequent insertions and deletions.

Are TypeScript Maps Mutable?

Yes, TypeScript Maps are mutable. You can add or remove elements after a Map is created.

Can I Initialize a Map with Values?

Yes, you can initialize a TypeScript Map with an array of key-value pairs.

What Are the Common Methods Available in a Map?

Common methods include set, get, has, delete, and clear.

Can a Map Key be an Object or Function?

Yes, unlike objects, a Map in TypeScript can have keys of any type, including objects and functions.

Is it Possible to Convert a Map to an Object?

Yes, you can convert a Map to an object using methods like Object.fromEntries() or manually looping through the Map.

How to Make a Map Read-Only in TypeScript?

While TypeScript doesn't provide native read-only Maps, you can define an interface or type that only includes the read-only methods like get and has.


Advanced Topics

1. Nested Maps

Nested Maps in TypeScript allow you to have a Map as the value for a key in another Map. This is particularly useful for complex data structures or when you need to associate multiple values with a single key.

// Define a nested TypeScript Map
const nestedMap = new Map<string, Map<string, number>>();

// Initialize the inner Map
const innerMap = new Map<string, number>();
innerMap.set('score', 42);

// Set the inner Map as a value for a key in the outer Map
nestedMap.set('John', innerMap);

// Accessing values
const person = nestedMap.get('John');
const score = person ? person.get('score') : null;

console.log(`John's score is ${score}`);

Here, we have used nested Maps to associate a score with a person's name.

2. Combining Maps with other TypeScript Features like Generics

TypeScript allows you to use Generics to create reusable and type-safe components. You can use Generics with Maps to ensure type safety while maintaining code reusability.

// Define a generic function to process Maps
function processMap<K, V>(map: Map<K, V>): V[] {
  const values: V[] = [];
  map.forEach((value) => {
  return values;

// Usage
const stringMap = new Map<string, number>();
stringMap.set('one', 1);
stringMap.set('two', 2);

const numbers = processMap(stringMap);
console.log(numbers); // Output: [1, 2]

In this example, the processMap function is a generic function that takes a Map of any key type K and value type V and returns an array of values of type V.



In this article, we've taken an in-depth look at various aspects of using Maps in TypeScript. Maps offer a way to store key-value pairs in a manner that is both efficient and easy to understand. Whether you're storing primitive values or complex objects, TypeScript Maps provide a robust and type-safe way to handle data. They offer various built-in methods and are natively iterable, making them a powerful tool in any TypeScript developer's toolkit.

We've also explored some advanced features like Nested Maps and how to use Generics with Maps for added type safety and reusability. All these aspects make TypeScript Maps a preferable choice for scenarios where you need fast access to data based on keys, without sacrificing the strong type-checking features that TypeScript provides.


Additional Resources


Deepak Prasad

He is the founder of GoLinuxCloud and brings over a decade of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels in various domains, from development to DevOps, Networking, and Security, ensuring robust and efficient solutions for diverse projects. You can reach out to him on his LinkedIn profile or join on Facebook page.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to admin@golinuxcloud.com

Thank You for your support!!

Leave a Comment