Const Enum

A const enum is a completely erased, compile-time-only enumeration in TypeScript. Unlike standard enums, which generate a reverse-mapped object via an Immediately Invoked Function Expression (IIFE) in the emitted JavaScript, a const enum leaves no runtime footprint. Instead, the TypeScript compiler directly inlines the evaluated enum member values at every call site during the emit phase.

const enum Direction {
  Up = 1,
  Down = 2,
  Left = 3,
  Right = 4
}

Compilation Behavior

The defining characteristic of a const enum is its compilation output. The compiler substitutes the property access with the literal value.

TypeScript Source:

const enum HttpStatusCode {
  OK = 200,
  NotFound = 404
}

const responseCode = HttpStatusCode.OK;

Emitted JavaScript:

const responseCode = 200 /* HttpStatusCode.OK */;

Note: The compiler appends an inline comment indicating the original enum member for debugging purposes.

Technical Constraints and Characteristics

• No Runtime Object: Because the enum is erased, you cannot iterate over a const enum using Object.keys(), Object.values(), or for...in loops. The identifier HttpStatusCode does not exist at runtime.
• Constant Expressions Only: Members of a const enum must be initialized with constant expressions. They cannot be initialized with dynamically computed values (e.g., the result of a function call or a property access from a runtime object).

// Valid: Constant expressions
const enum BitFlags {
  None = 0,
  Read = 1 << 0,
  Write = 1 << 1
}

// Invalid: Computed value
const enum Dynamic {
  Id = Math.random() // Error: const enum member initializers must be constant expressions
}

• Reverse Mapping: Unlike standard numeric enums, numeric const enums do not support reverse mapping (accessing the string key via the numeric value), as the mapping object is never generated.

Compiler Configuration Impacts

The behavior of const enum interacts specifically with certain tsconfig.json compiler options and third-party transpilation tools:

• preserveConstEnums: If set to true, the TypeScript compiler will still inline the values at the call sites, but it will also emit the standard enum object into the JavaScript output.
• isolatedModules: This is strictly a type-checking flag that warns developers about constructs that would be unsafe for single-file transpilers. It does not change tsc’s own compilation process, nor does it prevent tsc from performing full-program analysis and inlining. Exporting a regular const enum and importing it into another file is perfectly valid under isolatedModules. TypeScript will only flag ambient const enums (export declare const enum) under this setting, as those lack implementations for single-file transpilers to emit.
• Single-File Transpilers (Babel, esbuild, SWC): Because modern bundlers and transpilers operate on a strictly per-file basis, they cannot perform the cross-file analysis required to inline values from an imported const enum. To handle this, these tools intentionally compile const enum declarations into standard enums (emitting the runtime object). This ensures that imported values resolve correctly at runtime and prevents ReferenceErrors.

Master TypeScript with Deep Grasping Methodology!

Learn More