Mapped types are a handy TypeScript feature that allow authors to keep their types DRY (“Don’t Repeat Yourself”). However, because they tow the line between programming and metaprogramming, they can be difficult to understand at first.
In this post, we’ll cover some foundational concepts that enable mapped types, then walk through an advanced, real-world example.
Why use mapped types in TypeScript?
Using mapped types in a program is especially useful when there is a need for a type to be derived from (and remain in sync with) another type.
This example is problematic because there is an implicit relationship between
AppPermissions. Whenever a new configuration value is added to
AppConfig, there must also be a corresponding
boolean value in
It is better to have the type system manage this relationship than to rely on the discipline of future program editors to make the appropriate updates to both types simultaneously.
We’ll delve into the specifics of the mapped types syntax later on, but here is a preview of the same example using mapped types instead of explicit types:
Foundational concepts of mapped types
Mapped types build upon each of these concepts and TypeScript features.
What is a mapped type?
In a computer science context, the term “map” means to transform one thing into another, or, more commonly, refers to turning similar items into a different list of transformed items. Likely the most familiar application of this idea is
Here we’ve mapped each number in the array to its string representation. So a mapped type in TypeScript means we’re taking one type and transforming it into another type by applying a transformation to each of its properties.
Indexed access types in TypeScript
TypeScript authors can access the type of a property by looking it up by name:
In this case, the resolved type of
string. For more information on indexed access types, see the official docs.
Index signatures are handy for cases when the actual names of the type’s properties are not known, but the type of data they will reference is known.
In this example, the TypeScript compiler reports that the type of
string rather than
any. This functionality, in conjunction with the
keyof operator detailed below, is one of the core components that make mapped types possible. For more information on index signatures, see the official documentation on object types.
Using union types in TypeScript
A union type is a combination of two or more types. It signals to the TypeScript compiler that the type of the underlying value could be any one of the types included in the union. This is a valid TypeScript program:
Here is a more complicated example that shows some of the advanced protection the compiler can offer with union types:
See the docs on everyday types for more information on union types.
keyof type operator
keyof type operator returns a union of the keys of the type passed to it. For example:
AppConfigKey type resolves to
"username" | "layout". Note that this also works in tandem with index signatures:
UserPreferenceKey type resolves to
string | number (
keyof type operator here.
Mapped types: a real-world example
Now that we’ve covered the foundations upon which TypeScript’s mapped types feature is built, let’s walk through a detailed real-world example. Suppose our program keeps track of electronic devices and their manufacturers and prices. We might have a type like this to represent each device:
Now, we’d like to ensure that we have a way to display those devices to the user in a human-readable format, so we’ll add a new type for an object that can format each property of a
Device with an appropriate formatting function:
Let’s pull this code block apart, piece by piece.
Key in keyof Device uses the
keyof type operator to generate a union of all keys in
Device. Putting it inside of an index signature essentially iterates through all properties of
Device and maps them to properties of
(value: Device[Key]) => string; is where we utilize the indexed access type
Device[Key] to indicate that the format function’s
value parameter is of the type of the property we are formatting. So,
formatManufacturer takes a
string (the manufacturer) while
formatPrice takes a
number (the price).
Here’s what the
DeviceFormatter type looks like:
Now, let’s suppose we add a third property,
releaseYear, to our
Thanks to the power of mapped types, the
DeviceFormatter type is automatically expanded to look like this without any additional work on our part:
Any implementations of
DeviceFormatter must add the new function or compilation will fail. Voilà!
Bonus: a reusable formatter type with generics
Suppose now that our program not only needs to keep track of electronic devices but also accessories for those devices:
Again, we want a type for an object that can provide string formatting functions for all the properties of
Accessory. We could implement an
AccessoryFormatter type, similar to how we implemented
DeviceFormatter, but we end up with mostly duplicate code:
The only difference is that we’ve replaced references to the
Device type with
Accessory. Instead, we can create a generic type that takes
Accessory as a type argument and produces the desired mapped type. Traditionally,
T is used to represent the type argument.
Note that we have to make one slight change to our property name transformation. Because
T could be any type, we don’t know for sure that
Key is a
string (for example, arrays have
number properties), so we take the intersection of the property name and
string to satisfy the constraint imposed by
See the TypeScript documentation on generics for more detail on how they work. Now we can replace our bespoke implementations of
AccessoryFormatter to use the generic type instead:
Here is the full final code:
Mapped types provide a powerful way to keep related types in sync automatically. They can also help prevent bugs by keeping types DRY and obviating the need to repetitively type (or copy and paste) similar property names.