What are TypeScript enums and why to avoid them?

What is a TypeScript enum?

A TypeScript Enum is a type-safe data type that allows you to define a set of named constants. It can be used to define a list of values that are related to each other in some way. For example, you can create an enum for a list of days of the week, or a list of colours.

Enums are useful because they provide a way to group related values together, whilst still allowing them to be used in a type-safe way. This means that you can’t accidentally assign a value that isn’t part of the enum, which can help to avoid errors and bugs.

To create an enum in TypeScript, you use the keyword enum followed by a name for your enum and then you list out the values that make up the enum, separated by a comma.

For example, if we were to create an enum for a list of days of the week, it would look something like this:

enum DayOfWeek {
  Sunday,
  Monday,
  Tuesday,
  Wednesday,
  Thursday,
  Friday,
  Saturday,
}

You can also assign values to each of the enum values. This is useful if you need to store additional information about each value. For example, you could assign a numerical value to each of the days of the week.

enum DayOfWeek {
  Sunday: 0,
  Monday: 1,
  Tuesday: 2,
  Wednesday: 3,
  Thursday: 4,
  Friday: 5,
  Saturday: 6,
}

Once you have created an enum, you can used it in your code and access values of the enum using the dot notation. For example, if we were to access the value of Monday in the above example, we would use DayOfWeek.Monday, and that would return the value of 1.

You can also access the name of an enum value using the enum value, in this case a numerical value using the code above. For example, we can use DayOfWeek[1] to get the name of the enum who’s value is 1, in this case it would return Monday.

This can be very surprising at first, bit this is due to the way in which TypeScript creates a Enum Map for us automatically when the code is transpiled.

Understanding TypeScript enum maps

Lets have a look at what the TypeScript enum map would look like for the above DaysOfWeek enum:

var DayOfWeek;
(function (DayOfWeek) {
  DayOfWeek[(DayOfWeek['Sunday'] = 0)] = 'Sunday';
  DayOfWeek[(DayOfWeek['Monday'] = 1)] = 'Monday';
  DayOfWeek[(DayOfWeek['Tuesday'] = 2)] = 'Tuesday';
  DayOfWeek[(DayOfWeek['Wednesday'] = 3)] = 'Wednesday';
  DayOfWeek[(DayOfWeek['Thursday'] = 4)] = 'Thursday';
  DayOfWeek[(DayOfWeek['Friday'] = 5)] = 'Friday';
  DayOfWeek[(DayOfWeek['Saturday'] = 6)] = 'Saturday';
})(DayOfWeek || (DayOfWeek = {}));

If we were to then output this in the console, you will then notice that an enum is really just a JavaScript object with properties that represent the enum values and their names, like so:

{
  0: "Sunday",
  1: "Monday",
  2: "Tuesday",
  3: "Wednesday",
  4: "Thursday",
  5: "Friday",
  6: "Saturday",
  Sunday: 0,
  Monday: 1,
  Tuesday: 2,
  Wednesday: 3,
  Thursday: 4,
  Friday: 5,
  Saturday: 6,
}

Pitfalls of TypeScript enums

Now that we know what a TypeScript enum is and how it works, let’s look at some of the pitfalls associated with using them.

Mutability

Technically, a enum is mutable. This means that you can actually change the values of an enum after you have defined it. This can then lead to unexpected behavior, and cause bugs in your code.

Performance

Enums can also be a performance issue. This is because they are stored in a map and therefore take up a lot more memory than they ought to. This can lead to slower performance, especially if you are using a lot of enums or large enums.

Accessibility

They can be difficult to access. Because they are stored in a map, they can be difficult to debug. This can make it difficult to find the value of an enum, or to check that the values are correct.

Obscure code

Enums are compiled to some obscure code, instead of being just removed by the TypeScript compiler. They are one of the few pieces of TS syntax that behave this way. Though that’s rarely a real world problem, it slightly increases bundle size and debugging complexity, and slightly decreases performance.

What about const enums?

Adding the keyword const in front of the enum keyword makes it a const enum. But making it a const enum means that when the code is transpiled there is no generated enum map. In fact there is no code that represents the enum at all, and all usages are replaced with the corresponding enum value.

String literal union types

TypeScript’s type system allows you to build new types out of existing ones using a large variety of operators. These types are just types, they do not get transpiled into JavaScript code. As such we can use these for type-safety in our code, but they do not increate the size of our transpiled code like enums do with their enum maps.

A union type is a type formed from two or more other types, representing values that may be any one of those types. We refer to each of these types as the union’s members.

A string literal is a string type and as such we can use two or more string literals to create a new union type like so:

type Visibility = 'hidden' | 'visible';

We can also create new union types by existing other ones like so:

type VisibilityWithLoading = Visibility | 'loading';

Like with enums, you may occasionally want to iterate over the values of union type. With TypeScript this works right out of the box for enums and you don’t need to do anything special. However, with union types you need to adjust the code slightly and introduce a backing constant array which can be iterated over.

Here is an example of the Visibility type from above, rewritten to allow iterating over the values:

// As arrays are iterable, we create an array with all the values you want in your union type
const Visibilities = ['visible', 'hidden'] as const;
 
// If you want to, you can name your array variable and type exactly the same and all will be fine
type Visibility = typeof Visibilities[number];
 
// Like with enums, you can now iterate over the values like this
for (const visibility in visibilities) {
  ...
}

Here are some of the reasons why I recommend using this approach over all others:

• IDEs today have become very smart and powerful enough to suggest values when using string literal unions and indicate with a TypeError when using a string literal value that has not been defined for that union type.
• There is only one way to use union types, while with enums you can use Enum.VALUE and VALUE directly without the transpiler complaining.
• As mentioned above, you can create new union types extending others with ease, which you cannot do with enums.
• Enums are compiled to some obscure code, instead of being just removed by the TypeScript transpiler. They are one of the few pieces of TS syntax that behave this way. Though that’s rarely a real world problem, it slightly increases bundle size and debugging complexity, and slightly decreases performance.
• If code uniformity matters to you, it’s easy to ban enums with an ESlint rule, while banning “string literal union types” is much more complicated since union types are everywhere in TypeScript code.

Conclusion

Although enums are a common language feature used in many other languages, I suggest avoiding them in TypeScript unless there is a real need to, like Bitwise flags. Instead I suggest using my preferred approach mentioned above as it works better in the majority of places that you’ll likely trying to use enums anyway and avoids all of the pain that they cause.

I also found this video on YouTube by Theo that talks about enums being TypeScript’s worst feature and suggests the same alternative as I have above.