typescript-discriminated-unions

Discriminated Unions

Apply the TypeScript Style Guide's discriminated-union conventions in the context of the current task.

Workflow

1. Inspect the consuming repository's conventions and configuration.
2. Let explicit repository conventions take precedence over this opinionated guidance.
3. Apply, review, or explain only the guidance relevant to the task.
4. State important tradeoffs when the appropriate model depends on context or judgment.

Boundaries

• Use discriminated unions for mutually exclusive variants that require different data.
• Do not force a discriminated union when properties may independently be absent or when only a value changes.
• Keep TypeScript and ESLint responsible for checks they can enforce automatically.
• Do not introduce unrelated TypeScript Style Guide conventions merely because this skill is active.

Discriminated Unions {#discriminated-unions}

If there's only one TypeScript feature to choose from, embrace discriminated unions.

A discriminated union is a union of object types that share a property with distinct literal values. Checking that property narrows the value to the matching variant.

Use discriminated unions when variants are mutually exclusive and each variant requires different data. Keep properties optional when they may independently be absent, and use a literal union when only the value changes.

Prefer a shared literal discriminator when variants represent named states or modes and you control their shape. Use optional never properties only when property presence is itself the natural distinction and adding a discriminator would make the API less clear.

Discriminated unions are a powerful concept to model complex data structures and improve type safety, leading to clearer and less error-prone code.
You may encounter discriminated unions under different names, such as tagged unions or sum types, in languages such as C, Haskell, and Rust (in conjunction with pattern-matching).