Skip to main content

0025 - Deprecate TypeScript Enum Types

ID:ADR-0025
Status:ACCEPTED
Published:2025-05-30

Context and Problem Statement​

TypeScript experts have long discouraged the use of enums. There are a variety of cited reasons. Among them:

  • Enums that are not const substantially increase output size.
  • Numeric enums implicitly cast from number to the enum type, which allows invalid enum values to be transmitted to functions.
  • String enums are named types that require a member is used, which is inconsistent with the behavior of numeric enums.

These inconsistencies cause increased complexity from guard statements in the best of cases. In the worst cases, their limitations may be unknown, and thus unguarded.

Detection​

TypeScript deprecation can be linted using a fairly short ESLint plugin. The code has already been contributed to main and is configured as an error-level lint. The same PR adds FIXME comments for each team to address.

The Enum-like Pattern​

In most cases, enums are unnecessary. A readonly (as const) object coupled with a type alias avoids both code generation and type inconsistencies.

export const CipherType = Object.freeze({
  Login: 1,
  SecureNote: 2,
  Card: 3,
  Identity: 4,
  SshKey: 5,
} as const);

export type CipherType = (typeof CipherType)[keyof typeof CipherType];

This code creates a type CipherType that allows arguments and variables to be typed similarly to an enum.

warning

Unlike an enum, TypeScript lifts the type of the members of const CipherType to number. Code like the following requires you explicitly type your variables:

// ✅ Do: strongly type enum-likes
const subject = new Subject<CipherType>();
let value: CipherType = CipherType.Login;

// ❌ Do not: use type inference
const array = [CipherType.Login]; // infers `number[]`
let value = CipherType.Login; // infers `1`

// ❌ Do not: use type assertions
let value = CipherType.Login as CipherType; // this operation is unsafe

Considered Options​

  • Allow enums, but advise against them - Allow enum use to be decided on a case-by-case basis by the team that owns the enum. Reduce the level of the lint to a "suggestion".
  • Deprecate enum use - Allow enums to exist for historic or technical purposes, but prohibit the introduction of new ones. Reduce the lint to a "warning" and allow the lint to be disabled.
  • Eliminate enum use - This is the current state of affairs. Prohibit the introduction of any new enum and replace all enums in the codebase with TypeScript objects. Prohibit disabling of the lint.

Decision Outcome​

Chosen option: Deprecate enum use

Positive Consequences​

  • Allows for cases where autogenerated code introduces an enum by necessity.
  • Literals (e.g. 1) convert to the enum-like type with full type safety.
  • Works with mapped types such as Record<T, U> and discriminated unions.
  • Developers receive a warning in their IDE to discourage new enums.
  • The warning can direct them to our contributing docs, where they can learn typesafe alternatives.
  • Our compiled code size decreases when enums are replaced.
  • If all teams eliminate enums in practice, the warning can be increased to an error.

Negative Consequences​

  • Unnecessary usage may persist indefinitely on teams carrying a high tech debt.
  • The lint increased the number of FIXME comments in the code by about 10%.
  • Enum-likes cannot be referenced by angular templates

Plan​

  • Update contributing docs with patterns and best practices for enum replacement.
  • Update the reporting level of the lint to "warning".