TypeScript Enums

Names instead of magic numbers

A traffic light is not “0, 1, or 2” in your head. It is red, amber, or green. If you storelet light = 1;, every reader has to remember what 1 means. An enum gives those values names the compiler understands.

You write Color.Red, the same idea as C++ Color::Red. The names live on the enum type. A loose Red by itself is not a Color.

Write an enum

List the names in braces. A numeric enum assigns integers starting at zero unless you set them yourself. You almost never need the integers. You need the names.

enum Color {
  Red,
  Amber,
  Green,
}

let light: Color = Color.Green;
if (light === Color.Green) {
  console.log("go");
}
light = Color.Red;
if (light === Color.Red) {
  console.log("stop");
}

Compare with ===. Assign with =. You cannot assign a random string to aColor by accident: light = "blue" is an error. That is the point of the enum.

switch on an enum

A switch is a good fit when every value of the enum should take a different path. Write acase for each enumerator. Put break; at the end of each case so execution does not fall through.

enum Color {
  Red,
  Amber,
  Green,
}

const light: Color = Color.Amber;

switch (light) {
  case Color.Red:
    console.log("halt");
    break;
  case Color.Amber:
    console.log("wait");
    break;
  case Color.Green:
    console.log("proceed");
    break;
}

If you later add Color.Blue, the switch will not mention it. Handle the new case, or you silently do nothing for a value you forgot.

Numeric values and string enums

Under the hood, Color.Red is 0, Amber is 1,Green is 2. You can set your own numbers if a file format or a protocol requires them.

A string enum stores the name you wrote, not an integer. That prints cleanly and matches well against text from a file.

enum Status {
  Ok = 200,
  NotFound = 404,
}

enum Mode {
  Read = "read",
  Write = "write",
}

const code: Status = Status.NotFound;
if (code === Status.Ok) {
  console.log("ready");
} else {
  console.log("missing");
}
console.log("stored as " + code);

const mode: Mode = Mode.Read;
console.log(mode);

Prefer the names in everyday logic. Compare to other enumerators. Switch on the type. Leave the raw numbers for storage and debugging.

const enum

const enum is an enum the compiler can erase. At compile time the names still work. In the emitted JavaScript, Color.Red may become the number 0 with no enum object left behind. That is a size trick, not a new kind of value.

Start with a plain enum. You can see Color.Red in the debugger. Switch toconst enum later if a bundle size rule asks for it.

Where enums fit

Use an enum for a closed set of choices: a color, a status, a difficulty, a day of the week. Do not use it for values that grow without a fixed list, such as a player’s score. That is still a number.

Next: a type alias is another name for a type you already wrote.