Enum vs union literal type trade-offs in Typescript - Trade-offs & Expert Analysis

Overview - Enum vs union literal type trade-offs

What is it?

Enums and union literal types are ways to represent a fixed set of values in TypeScript. Enums create named constants that can be numbers or strings, while union literal types define a type as a set of specific string or number values. Both help ensure variables only hold allowed values, improving code safety and clarity.

Why it matters

Without enums or union literal types, developers might use plain strings or numbers, risking typos and bugs that are hard to catch. These types help catch errors early, make code easier to read, and improve maintainability. Choosing between them affects code size, runtime behavior, and developer experience.

Where it fits

Learners should know basic TypeScript types and how type checking works before this. After this, they can explore advanced type features like mapped types, discriminated unions, and type guards to write safer and more expressive code.

Mental Model

Core Idea

Enums are named sets of constants with runtime presence, while union literal types are compile-time sets of allowed values without runtime code.

Think of it like...

Think of enums like labeled boxes you can open and check anytime, while union literal types are like a checklist you use only when packing, but the checklist disappears after packing is done.

TypeScript Value Sets

┌───────────────┐       ┌─────────────────────────┐
│   Enum        │       │ Union Literal Type       │
│ ┌───────────┐ │       │ ┌─────────────────────┐ │
│ │ Named     │ │       │ │ Set of allowed       │ │
│ │ constants │ │       │ │ string/number values │ │
│ └───────────┘ │       │ └─────────────────────┘ │
│ Runtime code │       │ Compile-time only       │
└──────┬────────┘       └──────────┬──────────────┘
       │                           │
       │ Used at runtime           │ Used only by compiler
       │                           │
       ▼                           ▼
  Can be iterated, mapped      No runtime code generated
  and referenced by name       Smaller output size

Build-Up - 7 Steps

1

Foundation

What is an Enum in TypeScript

Concept: Introduce enums as named sets of constants with runtime presence.

In TypeScript, an enum lets you define a set of named constants. For example: enum Color { Red, Green, Blue } This creates a Color type with three possible values: Color.Red, Color.Green, and Color.Blue. Enums exist in the compiled JavaScript, so you can use them at runtime.

Result

You get a Color object with properties Red=0, Green=1, Blue=2, usable in code and at runtime.

Understanding enums as runtime objects helps explain why they can be used for iteration and reverse mapping.

2

Foundation

What is a Union Literal Type

Concept: Introduce union literal types as compile-time sets of allowed values without runtime code.

A union literal type defines a type as one of several specific values. For example: type Color = 'red' | 'green' | 'blue'; This means a variable of type Color can only be one of these strings. Unlike enums, this does not create any JavaScript code; it's only for the compiler to check types.

Result

Variables typed with Color can only hold 'red', 'green', or 'blue', and no extra code is generated.

Knowing union literals exist only at compile time explains why they produce smaller output and no runtime overhead.

3

Intermediate

Runtime Behavior Differences

🤔Before reading on: do you think union literal types generate runtime code like enums? Commit to your answer.

Concept: Explain how enums produce JavaScript code while union literals do not.

Enums compile to JavaScript objects with properties for each member, allowing runtime access: const Color = { Red: 0, Green: 1, Blue: 2 }; Union literal types disappear after compilation, so no JavaScript object exists for them. This means you cannot iterate over union literals at runtime or access their values dynamically.

Result

Enums can be used in runtime logic, union literals cannot.

Understanding runtime presence clarifies when to use enums for dynamic behavior and union literals for type safety without runtime cost.

4

Intermediate

Type Safety and Autocompletion

🤔Before reading on: which do you think provides better autocompletion support in editors, enums or union literals? Commit to your answer.

Concept: Compare how enums and union literals help with type safety and editor support.

Both enums and union literals restrict values to a fixed set, preventing typos. Enums provide named constants, so editors can autocomplete enum members like Color.Red. Union literals also provide autocompletion for allowed string values. However, union literals can be more flexible with string values, while enums are better for numeric or mixed values.

Result

Both improve developer experience, but in slightly different ways.

Knowing the subtle differences in editor support helps choose the best tool for your coding style.

5

Intermediate

Code Size and Performance Trade-offs

🤔Before reading on: do you think enums always produce smaller JavaScript code than union literals? Commit to your answer.

Concept: Discuss how enums add runtime code increasing bundle size, while union literals do not.

Enums generate JavaScript objects, which add to the final bundle size and may affect performance in large apps. Union literals produce no runtime code, keeping bundles smaller. If you only need type checking and no runtime use, union literals are more efficient.

Result

Union literals help keep code lightweight; enums add runtime overhead.

Understanding this trade-off guides decisions for performance-sensitive projects.

6

Advanced

When to Use Enums vs Union Literals

🤔Before reading on: do you think enums are always better for representing fixed sets? Commit to your answer.

Concept: Explain practical scenarios favoring enums or union literals based on needs.

Use enums when you need: - Runtime access to values - Iteration over members - Reverse mapping (from value to name) Use union literals when you want: - Pure type safety without runtime code - Smaller bundle size - Flexibility with string values Choosing depends on whether runtime features or minimal code size matter more.

Result

You can pick the right tool for your project's needs.

Knowing when each type shines prevents overusing enums or union literals inappropriately.

7

Expert

Advanced Patterns and Pitfalls

🤔Before reading on: do you think enums and union literals can be combined effectively? Commit to your answer.

Concept: Explore combining enums and union literals, and subtle pitfalls like enum value changes affecting code.

You can combine enums with union literals for flexible APIs, e.g., accept enum members or string literals. Beware that changing enum member values can break code relying on numeric values. Also, string enums behave differently than numeric enums in reverse mapping. Union literals avoid these runtime risks but lack runtime features.

Result

Advanced use requires careful design to avoid bugs and maintain clarity.

Understanding these subtleties helps write robust, maintainable TypeScript code.

Under the Hood

Enums compile into JavaScript objects with properties for each member, allowing runtime access and reverse mapping. Numeric enums get auto-incremented values unless specified. String enums map names to string values without reverse mapping. Union literal types exist only in the TypeScript type system and are erased during compilation, producing no JavaScript code.

Why designed this way?

Enums were introduced to provide a familiar way to define sets of constants with runtime presence, similar to other languages. Union literal types leverage TypeScript's powerful type system to enforce allowed values without runtime cost. This separation balances developer convenience, runtime efficiency, and type safety.

TypeScript Compilation Flow

Source Code:
  ┌───────────────┐       ┌─────────────────────┐
  │ enum Color {  │       │ type Color = 'red' |│
  │   Red, Green, │       │ 'green' | 'blue';    │
  │   Blue }      │       └─────────────────────┘
  └──────┬────────┘                │
         │                         │
         ▼                         ▼
Compiled JavaScript:
  ┌─────────────────────────┐   (no output for union literals)
  │ const Color = {          │
  │   Red: 0,               │
  │   Green: 1,             │
  │   Blue: 2               │
  │ };                      │
  └─────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do enums always produce smaller JavaScript code than union literals? Commit to yes or no.

Common Belief: Enums are always more efficient because they are built-in language features.

Reality: Enums generate runtime JavaScript objects, increasing code size, while union literals produce no runtime code and keep bundles smaller.

Why it matters: Assuming enums are always efficient can lead to unnecessarily large bundles and slower load times.

Quick: Can you iterate over union literal types at runtime like enums? Commit to yes or no.

Common Belief: Union literal types behave like enums and can be iterated at runtime.

Reality: Union literal types exist only at compile time and have no runtime representation, so you cannot iterate over them in JavaScript.

Why it matters: Expecting runtime iteration on union literals causes runtime errors and confusion.

Quick: Do string enums support reverse mapping from value to name? Commit to yes or no.

Common Belief: All enums, including string enums, support reverse mapping from value to name.

Reality: Only numeric enums support reverse mapping; string enums do not have this feature.

Why it matters: Misusing reverse mapping on string enums leads to undefined behavior and bugs.

Quick: Are union literal types less type-safe than enums? Commit to yes or no.

Common Belief: Enums provide better type safety than union literal types.

Reality: Both provide strong type safety, but union literals can be more flexible and prevent runtime surprises since they have no runtime code.

Why it matters: Choosing enums over union literals for type safety alone may add unnecessary runtime complexity.

Expert Zone

1

Enums can be const enums to remove runtime code but lose some features like computed members and reverse mapping.

2

Changing numeric enum member values can silently break code relying on those values, a risk union literals avoid.

3

Union literal types can be combined with template literal types for powerful, expressive type definitions beyond enums' capabilities.

When NOT to use

Avoid enums when you want zero runtime overhead or need flexible string values; prefer union literals. Avoid union literals when you need runtime features like iteration or reverse mapping; prefer enums or const enums.

Production Patterns

In large codebases, enums are used for API status codes or flags needing runtime checks, while union literals are preferred for configuration options or props in React components to minimize bundle size.

Connections

Algebraic Data Types (ADTs)

Union literal types build on the idea of ADTs by representing fixed sets of values, similar to sum types in functional programming.

Understanding union literals as ADTs helps grasp how TypeScript models complex data safely and expressively.

Database Enum Types

TypeScript enums and union literals correspond to enum types in databases that restrict column values to fixed sets.

Knowing this connection helps design consistent data validation across frontend and backend.

Finite State Machines (FSM)

Enums and union literals can represent states in FSMs, ensuring only valid states are used and transitions are safe.

This cross-domain link shows how type systems enforce correctness in dynamic systems.

Common Pitfalls

#1 Using enums when only type safety is needed, causing larger bundles.

Wrong approach:

enum Status {
Active = 'active',
Inactive = 'inactive'
}
// Used only for type checking, but generates runtime code

Correct approach:

type Status = 'active' | 'inactive';
// No runtime code, just type safety

Root cause:

Confusing enums as only type constructs rather than runtime objects.

#2 Expecting to iterate over union literal types at runtime.

Wrong approach:

const colors = Color;
for (const c of colors) { console.log(c); }
// Error: Color is a type, not a value

Correct approach:

enum Color {
Red,
Green,
Blue
}
for (const c in Color) { console.log(c); }
// Works because Color is a runtime object

Root cause:

Not realizing union literals have no runtime representation.

#3 Changing numeric enum values without updating dependent code.

Wrong approach:

enum Direction {
Up = 1,
Down = 2,
Left = 3,
Right = 4
}
// Later changed Up = 0, breaking code relying on numeric values

Correct approach:

enum Direction {
Up = 0,
Down = 1,
Left = 2,
Right = 3
}
// Keep values stable or use string enums

Root cause:

Not understanding enums' numeric values are part of the API contract.

Key Takeaways

Enums create named constants with runtime presence, enabling iteration and reverse mapping but adding code size.

Union literal types define allowed values only at compile time, producing no runtime code and keeping bundles smaller.

Choosing between enums and union literals depends on whether runtime features or minimal code size matter more.

Misunderstanding their differences can cause bugs, performance issues, or developer confusion.

Advanced use involves combining both and understanding subtle behaviors like const enums and reverse mapping.

Practice

1. Which statement best describes a key difference between TypeScript enums and union literal types?

easy

A. Enums create runtime objects, while union literal types only exist at compile time.

B. Union literal types generate JavaScript code, enums do not.

C. Enums cannot restrict values, union literal types can.

D. Union literal types allow dynamic value assignment, enums do not.

Solution

1. Step 1: Understand enums and union literal types

   Enums create named objects that exist in the generated JavaScript code at runtime. Union literal types only exist during TypeScript's type checking and do not produce runtime code.

2. Step 2: Compare runtime presence

   Since union literal types are erased after compilation, they cannot be used as runtime objects, unlike enums.

3. Final Answer:

   Enums create runtime objects, while union literal types only exist at compile time. -> Option A

4. Quick Check:

   Runtime object presence = A [OK]

Hint: Enums exist at runtime; union types do not [OK]

Common Mistakes:

• Thinking union types generate runtime code
• Believing enums cannot restrict values
• Confusing dynamic assignment capabilities

2. Which of the following is the correct syntax to define a union literal type for colors 'red', 'green', and 'blue' in TypeScript?

easy

A. enum Colors { 'red', 'green', 'blue' }

B. type Colors = 'red' | 'green' | 'blue';

C. type Colors = ['red', 'green', 'blue'];

D. enum Colors = 'red' | 'green' | 'blue';

Solution

1. Step 1: Identify union literal type syntax

   Union literal types use the syntax: type Name = 'value1' | 'value2' | 'value3';

2. Step 2: Check options for correct syntax

   type Colors = 'red' | 'green' | 'blue'; correctly uses the union literal type syntax. Options B and D misuse enum syntax, and C defines a tuple type, not a union.

3. Final Answer:

   type Colors = 'red' | 'green' | 'blue'; -> Option B

4. Quick Check:

   Union literal type syntax = A [OK]

Hint: Union types use | between quoted literals [OK]

Common Mistakes:

• Using enum syntax for union types
• Using array syntax instead of union
• Assigning enum with = and union syntax mixed

3. Given the enum and union type below, what will be the output of the console.log statements?

enum StatusEnum { Active = 'active', Inactive = 'inactive' }
type StatusUnion = 'active' | 'inactive';

const enumValue = StatusEnum.Active;
const unionValue: StatusUnion = 'active';

console.log(enumValue === 'active');
console.log(unionValue === 'active');

medium

A. false false

B. true false

C. false true

D. true true

Solution

1. Step 1: Understand enum and union values

   StatusEnum.Active is assigned the string 'active'. The unionValue is also the string 'active'.

2. Step 2: Evaluate the console.log comparisons

   Both enumValue === 'active' and unionValue === 'active' compare string 'active' to 'active', so both are true.

3. Final Answer:

   true true -> Option D

4. Quick Check:

   String equality for enum and union = D [OK]

Hint: Enum string values equal union strings if assigned same literal [OK]

Common Mistakes:

• Assuming enum values are numbers by default
• Thinking enumValue is an object, not a string
• Confusing enum and union value types

4. Identify the error in the following TypeScript code using enums and union types:

enum Direction {
  Up = 'UP',
  Down = 'DOWN'
}

type DirectionUnion = 'UP' | 'DOWN';

function move(dir: DirectionUnion) {
  console.log(dir);
}

move(Direction.Up);
move('LEFT');

medium

A. Calling move with Direction.Up causes a type error.

B. Enum Direction is missing a 'LEFT' value causing an error.

C. Calling move with 'LEFT' causes a type error.

D. Function move should accept enum Direction, not union type.

Solution

1. Step 1: Check function parameter type

   Function move expects a parameter of type DirectionUnion, which allows only 'UP' or 'DOWN'.

2. Step 2: Analyze function calls

   Calling move(Direction.Up) passes 'UP', which is valid. Calling move('LEFT') passes a string not in the union, causing a type error.

3. Final Answer:

   Calling move with 'LEFT' causes a type error. -> Option C

4. Quick Check:

   Invalid union argument = B [OK]

Hint: Union types restrict allowed strings strictly [OK]

Common Mistakes:

• Assuming enum values are incompatible with union types
• Thinking missing enum values cause errors
• Believing function parameter types are flexible

5. You want to create a set of fixed string values representing user roles that can be checked at runtime and also provide type safety. Which approach is best and why?

// Option 1
enum UserRoleEnum { Admin = 'admin', User = 'user', Guest = 'guest' }

// Option 2
type UserRoleUnion = 'admin' | 'user' | 'guest';

hard

A. Use UserRoleEnum because it creates a runtime object for checks and type safety.

B. Use UserRoleUnion because it generates runtime code and is simpler.

C. Use UserRoleUnion because enums cannot restrict string values.

D. Use UserRoleEnum because union types cannot be used in type annotations.

Solution

1. Step 1: Understand runtime and type safety needs

   To check values at runtime, you need an actual JavaScript object. Enums generate this object. Union types only exist at compile time and do not generate code.

2. Step 2: Compare options for runtime checks and type safety

   UserRoleEnum provides both runtime presence and type safety. UserRoleUnion provides only type safety but no runtime object for checks.

3. Final Answer:

   Use UserRoleEnum because it creates a runtime object for checks and type safety. -> Option A

4. Quick Check:

   Runtime object + type safety = C [OK]

Hint: Enums create runtime objects; unions only type safety [OK]

Common Mistakes:

• Thinking union types generate runtime code
• Believing enums cannot restrict string values
• Assuming union types can be used for runtime checks