TypeScript enums

This guide will explore the basics of TypeScript enums, explore various types of enums, and discuss converting enums between strings and numbers.

What is an enum in TypeScript?

An enum (short for enumeration) is a feature in TypeScript that allows you to define a set of named constants, either numeric or string-based. Using enums can make it easier to document intent, or create a set of distinct cases. TypeScript provides both numeric and string-based enums.

Numeric enums

By default, enums are numeric. Numeric enum values are auto-incremented from zero if no initializer is provided. Here is a basic example:

enum Direction {
  Up,
  Down,
  Left,
  Right
}

In this enum, Direction.Up would have a value of 0, Direction.Down of 1, and so on. You can also manually set the value of the first item and have TypeScript auto-increment the rest:

enum Direction {
  Up = 1,
  Down, // Automatically assigned 2
  Left, // Automatically assigned 3
  Right // Automatically assigned 4
}

String enums

String enums are similar to numeric enums, except they use string values instead of numeric values. Each member has to be constant-initialized with a string literal, or another string enum member.

enum Direction {
  Up = 'UP',
  Down = 'DOWN',
  Left = 'LEFT',
  Right = 'RIGHT'
}

TypeScript enum to string and string to enum

Enum to string conversion: Converting an enum member to a string is straightforward as TypeScript enums are real objects that exist at runtime. You can simply use the enum member, and it will evaluate to its assigned string or numeric value:

enum Direction {
  Up = 'UP',
  Down = 'DOWN',
  Left = 'LEFT',
  Right = 'RIGHT'
}

let currentDirection = Direction.Up
console.log(currentDirection) // Outputs: "UP"

String to enum conversion: To convert a string to an enum type, you can perform a reverse lookup if the enum is numeric, or you might need a function to handle string enums:

enum Direction {
  Up = 'UP',
  Down = 'DOWN',
  Left = 'LEFT',
  Right = 'RIGHT'
}

function getDirectionFromString(value: string): Direction | undefined {
  return Object.values(Direction).includes(value as Direction)
    ? (value as Direction)
    : undefined
}

let myDirection = getDirectionFromString('UP')
console.log(myDirection) // Outputs: "UP"

Advanced enum features in TypeScript

Const enums: A const enum is a special kind of enum that is completely removed during TypeScript’s compilation process. It allows for certain optimizations by inlining members at usage sites. Here's how you can declare a const enum:

const enum Direction {
  Up = 'UP',
  Down = 'DOWN',
  Left = 'LEFT',
  Right = 'RIGHT'
}

let directions = [Direction.Up, Direction.Down]
console.log(directions) // Outputs: ["UP", "DOWN"]

Union enums and type safety: Enums can be used to create a union type to restrict function parameters or variables to allow only certain values:

enum Fruit {
  Apple,
  Banana,
  Cherry
}

function eatFruit(fruit: Fruit) {
  console.log('Eating ' + Fruit[fruit])
}

eatFruit(Fruit.Apple) // Correct
eatFruit(5) // Error: Argument of type '5' is not assignable to parameter of type 'Fruit'.

For further reading see the official documentation.