Beyond Enums: TypeScript Const Assertions vs. Union Types

In the world of statically typed JavaScript with TypeScript, enums have long been a go-to for representing a fixed set of named constants. They offer a clear and readable way to define a collection of related values. However, as projects grow and evolve, developers often seek more flexible and sometimes more performant alternatives. Two powerful contenders that frequently emerge are const assertions and union types. This post delves into the nuances of using these alternatives to traditional enums, providing practical examples and guiding you on when to choose which.

Understanding Traditional TypeScript Enums

Before we explore the alternatives, it's essential to have a firm grasp on how standard TypeScript enums work. Enums allow you to define a set of named numeric or string constants. They can be numeric (the default) or string-based.

Numeric Enums

By default, enum members are assigned numeric values starting from 0.

            enum DirectionNumeric {
  Up,
  Down,
  Left,
  Right
}

let myDirection: DirectionNumeric = DirectionNumeric.Up;
console.log(myDirection); // Output: 0

            

              
                Copy
              
            
          

You can also explicitly assign numeric values.

            enum StatusCode {
  Success = 200,
  NotFound = 404,
  InternalError = 500
}

let responseStatus: StatusCode = StatusCode.Success;
console.log(responseStatus); // Output: 200

            

              
                Copy
              
            
          

String Enums

String enums are often preferred for their improved debugging experience, as the member names are preserved in the compiled JavaScript.

            enum ColorString {
  Red = "RED",
  Green = "GREEN",
  Blue = "BLUE"
}

let favoriteColor: ColorString = ColorString.Blue;
console.log(favoriteColor); // Output: "BLUE"

            

              
                Copy
              
            
          

The Overhead of Enums

While enums are convenient, they come with a slight overhead. When compiled to JavaScript, TypeScript enums are turned into objects that often have reverse mappings (e.g., mapping the numeric value back to the enum name). This can be useful but also contributes to the bundle size and might not always be necessary.

Consider this simple string enum:

            enum Status {
  Pending = "PENDING",
  Processing = "PROCESSING",
  Completed = "COMPLETED"
}

            

              
                Copy
              
            
          

In JavaScript, this might become something like:

            var Status;
(function (Status) {
    Status["Pending"] = "PENDING";
    Status["Processing"] = "PROCESSING";
    Status["Completed"] = "COMPLETED";
})(Status || (Status = {}));

            

              
                Copy
              
            
          

For simple, read-only sets of constants, this generated code can feel a bit excessive.

Alternative 1: Const Assertions

Const assertions are a powerful TypeScript feature that allows you to tell the compiler to infer the most specific type possible for a value. When used with arrays or objects intended to represent a fixed set of values, they can serve as a lightweight alternative to enums.

Const Assertions with Arrays

You can create an array of string literals and then use a const assertion to make its type immutable and its elements literal types.

            const statusArray = ["PENDING", "PROCESSING", "COMPLETED"] as const;

type StatusType = typeof statusArray[number];

let currentStatus: StatusType = "PROCESSING";
// currentStatus = "FAILED"; // Error: Type '"FAILED"' is not assignable to type 'StatusType'.

function processStatus(status: StatusType) {
  console.log(`Processing status: ${status}`);
}

processStatus("COMPLETED");

            

              
                Copy
              
            
          

Let's break down what's happening here:

• as const: This assertion tells TypeScript to treat the array as read-only and infer the most specific literal types for its elements. So, instead of `string[]`, the type becomes `readonly ["PENDING", "PROCESSING", "COMPLETED"]`.
• typeof statusArray[number]: This is a mapped type. It iterates over all indices of the statusArray and extracts their literal types. The number index signature essentially says "give me the type of any element in this array." The result is a union type: "PENDING" | "PROCESSING" | "COMPLETED".

This approach provides type safety similar to string enums but generates minimal JavaScript. The statusArray itself remains an array of strings in JavaScript.

Const Assertions with Objects

Const assertions are even more powerful when applied to objects. You can define an object where keys represent your named constants and values are the literal strings or numbers.

            const userRoles = {
  Admin: "ADMIN",
  Editor: "EDITOR",
  Viewer: "VIEWER"
} as const;

type UserRole = typeof userRoles[keyof typeof userRoles];

let currentUserRole: UserRole = "EDITOR";
// currentUserRole = "GUEST"; // Error: Type '"GUEST"' is not assignable to type 'UserRole'.

function displayRole(role: UserRole) {
  console.log(`User role is: ${role}`);
}

displayRole(userRoles.Admin); // Valid
displayRole("EDITOR"); // Valid

            

              
                Copy
              
            
          

In this object example:

• as const: This assertion makes the entire object read-only. More importantly, it infers literal types for all property values (e.g., "ADMIN" instead of string) and makes the properties themselves readonly.
• keyof typeof userRoles: This expression results in a union of the keys of the userRoles object, which is "Admin" | "Editor" | "Viewer".
• typeof userRoles[keyof typeof userRoles]: This is a lookup type. It takes the union of keys and uses it to look up the corresponding values in the userRoles type. This results in the union of the values: "ADMIN" | "EDITOR" | "VIEWER", which is our desired type for roles.

The JavaScript output for userRoles will be a plain JavaScript object:

            var userRoles = {
    Admin: "ADMIN",
    Editor: "EDITOR",
    Viewer: "VIEWER"
};

            

              
                Copy
              
            
          

This is significantly lighter than a typical enum.

When to Use Const Assertions

• Read-only constants: When you need a fixed set of string or number literals that should not change at runtime.
• Minimal JavaScript output: If you're concerned about bundle size and want the most performant runtime representation for your constants.
• Object-like structure: When you prefer the readability of key-value pairs, similar to how you might structure data or configuration.
• String-based sets: Particularly useful for representing states, types, or categories that are best identified by descriptive strings.

Alternative 2: Union Types

Union types allow you to declare that a variable can hold a value of one of several types. When combined with literal types (string, number, boolean literals), they form a powerful way to define a set of allowed values without needing an explicit constant declaration for the set itself.

Union Types with String Literals

You can directly define a union of string literals.

            type TrafficLightColor = "RED" | "YELLOW" | "GREEN";

let currentLight: TrafficLightColor = "YELLOW";
// currentLight = "BLUE"; // Error: Type '"BLUE"' is not assignable to type 'TrafficLightColor'.

function changeLight(color: TrafficLightColor) {
  console.log(`Changing light to: ${color}`);
}

changeLight("RED");
// changeLight("REDDY"); // Error

            

              
                Copy
              
            
          

This is the most direct and often the most concise way to define a set of allowed string values.

Union Types with Numeric Literals

Similarly, you can use numeric literals.

            type HttpStatusCode = 200 | 400 | 404 | 500;

let responseCode: HttpStatusCode = 404;
// responseCode = 201; // Error: Type '201' is not assignable to type 'HttpStatusCode'.

function handleResponse(code: HttpStatusCode) {
  if (code === 200) {
    console.log("Success!");
  } else {
    console.log(`Error code: ${code}`);
  }
}

handleResponse(500);

            

              
                Copy
              
            
          

When to Use Union Types

• Simple, direct sets: When the set of allowed values is small, clear, and doesn't require descriptive keys beyond the values themselves.
• Implicit constants: When you don't need to refer to a named constant for the set itself, but rather directly use the literal values.
• Maximum conciseness: For straightforward scenarios where defining a dedicated object or array feels like overkill.
• Function parameters/return types: Excellent for defining the exact set of acceptable string or number inputs/outputs for functions.

Comparing Enums, Const Assertions, and Union Types

Let's summarize the key differences and use cases:

Runtime Behavior

• Enums: Generate JavaScript objects, potentially with reverse mappings.
• Const Assertions (Arrays/Objects): Generate plain JavaScript arrays or objects. The type information is erased at runtime, but the data structure remains.
• Union Types (with literals): No runtime representation for the union itself. The values are just literals. Type checking happens purely at compile time.

Readability and Expressiveness

• Enums: High readability, especially with descriptive names. Can be more verbose.
• Const Assertions (Objects): Good readability through key-value pairs, mimicking configurations or settings.
• Const Assertions (Arrays): Less readable for representing named constants, more for just an ordered list of values.
• Union Types: Very concise. Readability depends on the clarity of the literal values themselves.

Type Safety

• All three approaches offer strong type safety. They ensure that only valid, predefined values can be assigned to variables or passed to functions.

Bundle Size

• Enums: Generally the largest due to generated JavaScript objects.
• Const Assertions: Smaller than enums, as they produce plain data structures.
• Union Types: The smallest, as they don't generate any specific runtime data structure for the type itself, only relying on literal values.

Use Cases Matrix

Here's a quick guide:

Practical Examples and Best Practices

Example 1: Representing API Status Codes

Enum:

            enum ApiStatus {
  Success = "SUCCESS",
  Error = "ERROR",
  Pending = "PENDING"
}

function handleApiResponse(status: ApiStatus) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Const Assertion (Object):

            
const apiStatusCodes = {
  SUCCESS: "SUCCESS",
  ERROR: "ERROR",
  PENDING: "PENDING"
} as const;

type ApiStatus = typeof apiStatusCodes[keyof typeof apiStatusCodes];

function handleApiResponse(status: ApiStatus) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Union Type:

            
type ApiStatus = "SUCCESS" | "ERROR" | "PENDING";

function handleApiResponse(status: ApiStatus) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Recommendation: For this scenario, a union type is often the most concise and efficient. The literal values themselves are descriptive enough. If you needed to associate additional metadata with each status (e.g., a user-friendly message), a const assertion object would be a better choice.

Example 2: Defining User Roles

Enum:

            
enum UserRoleEnum {
  Admin = "ADMIN",
  Moderator = "MODERATOR",
  User = "USER"
}

function getUserPermissions(role: UserRoleEnum) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Const Assertion (Object):

            
const userRolesObject = {
  Admin: "ADMIN",
  Moderator: "MODERATOR",
  User: "USER"
} as const;

type UserRole = typeof userRolesObject[keyof typeof userRolesObject];

function getUserPermissions(role: UserRole) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Union Type:

            
type UserRole = "ADMIN" | "MODERATOR" | "USER";

function getUserPermissions(role: UserRole) {
  // ... logic ...
}

            

              
                Copy
              
            
          

Recommendation: A const assertion object strikes a good balance here. It provides clear key-value pairs (e.g., userRolesObject.Admin) which can improve readability when referencing roles, while still being performant. A union type is also a very strong contender if direct string literals are sufficient.

Example 3: Representing Configuration Options

Imagine a configuration object for a global application that might have different themes.

Enum:

            
enum Theme {
  Light = "light",
  Dark = "dark",
  System = "system"
}

interface AppConfig {
  theme: Theme;
  // ... other config options ...
}

            

              
                Copy
              
            
          

Const Assertion (Object):

            
const themes = {
  Light: "light",
  Dark: "dark",
  System: "system"
} as const;

type Theme = typeof themes[keyof typeof themes];

interface AppConfig {
  theme: Theme;
  // ... other config options ...
}

            

              
                Copy
              
            
          

Union Type:

            
type Theme = "light" | "dark" | "system";

interface AppConfig {
  theme: Theme;
  // ... other config options ...
}

            

              
                Copy
              
            
          

Recommendation: For configuration settings like themes, the const assertion object is often ideal. It clearly defines the available options and their corresponding string values. The keys (Light, Dark, System) are descriptive and map directly to the values, making the configuration code very understandable.

Choosing the Right Tool for the Job

The decision between TypeScript enums, const assertions, and union types isn't always black and white. It often comes down to a trade-off between runtime performance, bundle size, and code readability/expressiveness.

• Opt for Union Types when you need a simple, constrained set of string or number literals and maximum conciseness is desired. They are excellent for function signatures and basic value restrictions.
• Opt for Const Assertions (with Objects) when you want a more structured, readable way to define named constants, similar to an enum, but with significantly less runtime overhead. This is great for configuration, roles, or any set where the keys add significant meaning.
• Opt for Const Assertions (with Arrays) when you simply need an immutable ordered list of values, and the direct access via index is more important than named keys.
• Consider TypeScript Enums when you need their specific features, such as reverse mapping (though this is less common in modern development) or if your team has a strong preference and the performance impact is negligible for your project.

In many modern TypeScript projects, you'll find a leaning towards const assertions and union types over traditional enums, especially for string-based constants, due to their better performance characteristics and often simpler JavaScript output.

Global Considerations

When developing applications for a global audience, consistent and predictable constant definitions are crucial. The choices we've discussed (enums, const assertions, union types) all contribute to this consistency by enforcing type safety across different environments and developer locales.

• Consistency: Regardless of the chosen method, the key is consistency within your project. If you decide to use const assertion objects for roles, stick with that pattern throughout the codebase.
• Internationalization (i18n): When defining labels or messages that will be internationalized, use these type-safe structures to ensure that only valid keys or identifiers are used. The actual translated strings will be managed separately via i18n libraries. For example, if you have a `status` field that can be "PENDING", "PROCESSING", "COMPLETED", your i18n library would map these internal identifiers to localized display text.
• Time Zones & Currencies: While not directly related to enums, remember that when dealing with values like dates, times, or currencies, TypeScript's type system can help enforce correct usage, but external libraries are usually necessary for accurate global handling. For instance, a `Currency` union type could be defined as `"USD" | "EUR" | "GBP"`, but the actual conversion logic requires specialized tools.

Conclusion

TypeScript provides a rich set of tools for managing constants. While enums have served us well, const assertions and union types offer compelling, often more performant, alternatives. By understanding their differences and choosing the right approach based on your specific needs—whether it's performance, readability, or conciseness—you can write more robust, maintainable, and efficient TypeScript code that scales globally.

Embracing these alternatives can lead to smaller bundle sizes, faster applications, and a more predictable developer experience for your international team.