Defining and using a Key-Value pair in TypeScript

# Table of Contents

1. Defining and using a Key-Value pair in TypeScript
2. Using a Map to define a Key-value pair in TypeScript

# Defining and using a Key-Value pair in TypeScript

One way to define a key-value pair in TypeScript is to use an index signature.

An index signature is used when we don't know all the names of a type's keys ahead of time, but we know the shape of their values.

Copied!
const employee: { [key: string]: string | number } = {};

employee.name = 'Bobby Hadz';
employee.salary = 100;

// 👇️ { name: 'Bobby Hadz', salary: 100 }
console.log(employee);

The {[key: string]: string} syntax is an index signature in TypeScript and is used when we don't know all the names of a type's properties ahead of time but know the shape of the values.

You might also see the index signature {[key: string]: any} in examples.

It represents a key-value structure that when indexed with a string returns a value of any type (very broad).

Copied!
const employee: { [key: string]: any } = {};

employee.name = 'Bobby Hadz';
employee.salary = 100;

employee.years = [2023, 2024];

// 👇️ { name: 'Bobby Hadz', salary: 100, years: [ 2023, 2024 ] }
console.log(employee);

The {[key: string]: any} index signature is used to create a key-value pair when we don't know the names of a type's keys and the shape of the values ahead of time.

You can declare the types of the keys and values that you know ahead of time and use an any type for the ones you don't.

Copied!
type Employee = {
  [key: string]: any;
  name: string;
  salary: number;
};

const employee: Employee = {
  name: 'Bobby Hadz',
  salary: 100,
};

employee.country = 'Bobby Hadz';
employee.years = [2021, 2022];

We declared types for the name and salary properties, which we know about ahead of time and used an index signature to still allow us to assign any key with any value to the object.

This is useful because we still get type support for the name and salary properties and the type checker would throw an error if we tried to set the properties to an incompatible type.

# Using a Map to define a Key-value pair in TypeScript

You can use a Map to define a key-value pair. A generic is used to set the type of the Map's keys and values.

Copied!
const map1 = new Map();

map1.set('name', 'Bobby Hadz');
map1.set('age', 30);
map1.set('country', 'Germany');

// 👇️ { 'name' => 'Bobby Hadz', 'age' => 30, 'country' => 'Germany' }
console.log(map1);

// 👇️ Bobby Hadz
console.log(map1.get('name'));

The Map in the example is implicitly typed to have keys and values of any type, but you can also explicitly specify a type.

Copied!
const map1 = new Map<string, string | number>();

map1.set('name', 'Bobby Hadz');
map1.set('age', 30);
map1.set('country', 'Germany');

console.log(map1);

// 👇️ Bobby Hadz
console.log(map1.get('name'));

We used a generic to declare a Map that has string keys and string or number values.

The syntax that is used to type a Map is - new Map<TypeOfKeys, TypeOfValues>().

For example, new Map<number, string> is a Map object with keys of type number and values of type string.

All of the key-value pairs we add to the Map have to conform to the specified types, otherwise, an error is thrown.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

// ⛔️ Error: Argument of type 'boolean' is not
// assignable to parameter of type 'string | number'.ts(2345)
map1.set('country', true);

We used a union type to set the Map's values to be either strings or numbers, but a boolean value is not a member of the union, so we got an error.

# Retrieving values from the Map

We typed the values of the Map to be strings or numbers, so when we use the Map.get() method, we will get a value of type string, number or undefined.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby hadz'],
  ['age', 30],
  ['country', 'Germany'],
]);

// 👇️ const country: string | number | undefined
const country = map1.get('country');

if (typeof country === 'string') {
  // 👇️ GERMANY
  console.log(country.toUpperCase());
}

The if statement serves as a type guard because it directly checks for the type of the value. The country variable is guaranteed to be a string in the if block.

# Adding key-value pairs to the Map

You can use the Map.set() method to add a key-value pair to the Map.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

map1.set('country', 'Germany');

console.log(map1.get('country')); // 👉️ "Germany"

console.log(map1.delete('country')); // 👉️ true

console.log(map1.has('country')); // 👉️ false

Make sure that the type of the key and value you passed to the Map.set() method conform to the types you specified when defining the Map.

The code sample shows how to use the Map.delete() method to remove a key-value pair from the Map.

The Map.has() method returns true if the specified key exists in the Map.

# Iterating over the Map

You can use the Map.forEach method to iterate over a Map in TypeScript.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

map1.forEach((value, key) => {
  console.log(value, key); // 👉️ Bobby Hadz name, 30 age
});

for (const [key, value] of map1) {
  console.log(key, value); // 👉️ name Bobby Hadz, age 30
}

The Map.forEach() method and a for...of loop can be used to iterate over a Map.

The for...of loop might be your preferred approach if you have to use the break keyword to exit the loop prematurely.

Using the break keyword is not supported in the forEach method.

# Converting the Map's keys or values to an array

Something you might often need is to convert the Map's keys or values to an array, because arrays have many useful built-in methods.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

const values = Array.from(map1.values());
console.log(values); // 👉️ ['Bobby Hadz', 30]

const keys = Array.from(map1.keys());
console.log(keys); // 👉️ ['name', 'age']

We used the Map.values() method to get an iterator object containing the values of the Map.

We passed the iterator as the only parameter to the Array.from() method.

The Array.from() method converts the iterable into an array and returns the new array instance.

# Getting the length of the Map

Another common thing you might need is to check how many elements a Map has. The Map.size() method returns the number of elements in the Map.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

console.log(map1.size); // 👉️ 2

map1.set('country', 'Germany');

console.log(map1.size); // 👉️ 3

# Deleting all key-value pairs from the Map

If you need to remove all key-value pairs from a Map object, use the Map.clear() method.

Copied!
const map1 = new Map<string, string | number>([
  ['name', 'Bobby Hadz'],
  ['age', 30],
]);

map1.clear();

console.log(map1.size); // 👉️ 0

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

• How to initialize a typed Empty Object in TypeScript
• Declare functions returning Object or Array in TypeScript
• Deep clone an Object and preserve its Type in TypeScript
• How to declare an Array of Objects in TypeScript
• Type 'IterableIterator' is not an array type or string type