Enums

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Enum

A named group of related constants, declared with the enum keyword.

Member

One name inside an enum, like Up in Direction.

Numeric enum

An enum whose members are numbers, starting at 0 unless you say otherwise.

String enum

An enum whose members are text values that you write yourself.

Reverse mapping

Looking up a member's name from its number, like Direction[1]. Numeric enums only.

const enum

An enum whose members are replaced by their raw values when compiled.

Emit

The JavaScript code the compiler writes out. Enums emit an object; most types emit nothing.

erasableSyntaxOnly

A compiler option (TypeScript 5.8) that forbids features that need generated code, such as enums.

Literal union

A type like "red" | "green" that lists the exact allowed values.

1. 1

   Give Level a gap

   In the first example, change enum Level { Low = 10, Mid, High } to { Low = 10, Mid = 50, High }. Predict Level.High before you print it (51: numbering continues from the last value).

2. 2

   Turn the enum into an object

   Rewrite Direction as const Direction = { Up: 0, Down: 1, Left: 2, Right: 3 } as const; and delete the reverse-mapping line. Predict which line of the first example breaks: Direction[1] fails, because a plain object has no reverse mapping.

3. 3

   Close the numeric loophole

   In the second example, make Color a string enum (Red = "red", Green = "green"). Predict how many of the lines that assign to a Color now fail: all of the plain-number ones do.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: Plain numbers or text for a fixed set of choices are hard to read, and a typo or wrong number slips through. A named group of choices makes the intent clear. A numeric enum is declared with enum Direction { Up, Down, Left, Right }. The members are numbered automatically from 0 (Up is 0, Down is 1, and so on). You can set a starting number (enum Level { Low = 10, Mid, High } gives 10, 11, 12). The enum name is also a type: let d: Direction accepts the members of Direction.

2. 2

   A string enum gives each member a piece of text: enum Status { Active = "ACTIVE", Banned = "BANNED" }. String enums print readably in logs and in network traffic, so they are usually the better choice over numeric enums. A string enum member isn't interchangeable with a plain string: let s: Status = "ACTIVE" is an error, you must write Status.Active.

3. 3

   Reverse mapping: a numeric enum also lets you go from the number back to the name: Direction[1] is "Down". TypeScript builds an object that stores both directions (you'll see the keys '0', '1'… and Up, Down… in the live example). String enums have no reverse mapping. This is also why numeric enums are not "just types": TypeScript has to emit code to build this object.

4. 4

   Enums are the exception to "types are erased": they are one of the few TypeScript features that produce JavaScript code of their own. That causes real friction. Tools that only strip types and don't compile can't handle them: Node's built-in type stripping stops with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX ("TypeScript enum is not supported in strip-only mode"). The compiler option erasableSyntaxOnly (TypeScript 5.8) turns an enum declaration into an error for exactly this reason (see the last live example).

5. 5

   Numeric enums are loose. Any number is assignable to a numeric enum type, so const c: Color = n compiles for a plain n: number, even if no member has that value (TypeScript 5.0 made the plain *literal* case stricter: const c: Color = 5 is an error when Color only has 0 and 1). If you need a closed set, string enums or literal unions don't have this hole.

6. 6

   **const enum** is an enum whose uses are replaced by the raw values at compile time, so no object exists for the member accesses. It saves a little code but causes trouble across files and with tools that compile one file at a time; isolatedModules (on in tsc --init) restricts how it can be used across files. Most style guides say: don't use const enum in libraries.

7. 7

   The alternative most teams choose today is a plain object with as const plus a union type derived from it: const Status = { Active: "ACTIVE", Banned: "BANNED" } as const; and type Status = (typeof Status)[keyof typeof Status]; (keyof and typeof are taught in Topics 8.1 and 8.2; read the pair as "all the values"). You get named constants, a union type, no special runtime code, and plain strings like "ACTIVE" are accepted where Status is expected. If you only need the type, a bare literal union type Status = "ACTIVE" | "BANNED" is the shortest option (Topic 4.2).

• ↔

  Enums read well and work with autocomplete, but they add emitted code and exclude you from tools that only strip types. A literal union costs nothing at runtime but has no namespace for the values; the as const object gives you both.

• ↔

  Numeric enums are compact for flags and storage; string enums are readable in logs and APIs. If a value is sent to a server or stored in a database, prefer strings: they survive reordering of the members.

• I can declare numeric and string enums and say what values the members get.

• I can use a reverse mapping and say which enums have one.

• I can explain why enums are the exception to "types are erased".

• I can replace an enum with an as const object and a derived union type.

• I can explain const enum and erasableSyntaxOnly in one sentence each.