Union Type

A union type lets a variable or parameter accept one of several defined types. In TypeScript, it is useful when a function must handle different concrete entities through one code path without creating a misleading shared base interface. The compiler narrows the type as needed, but runtime logic may still need explicit type context.

Expanded Definition

A union type is a type system construct that allows a value, parameter, or return type to be one of several declared alternatives. In TypeScript and similar languages, it is used when a single code path must handle more than one concrete shape without pretending those shapes share a common base interface. That distinction matters because a union describes variability explicitly, while inheritance or shared interfaces imply common capabilities that may not really exist.

The boundary is important: a union type does not merge its members into one new structure, and it does not guarantee that every operation is valid across all options. The compiler can narrow the type after checks such as discriminants, property tests, or control flow analysis, but the runtime still depends on the actual value received. Guidance on narrowing is well established in the TypeScript language model, and the official TypeScript narrowing documentation is the clearest source for how that behaves in practice.

Practitioners commonly misunderstand union types by assuming they create flexibility without cost. In reality, they shift part of the burden into validation and branch logic, especially when the code must preserve safety across multiple representations.

Examples and Use Cases

Union types appear whenever one interface must support multiple valid inputs or outcomes without collapsing them into an overly generic abstraction.

• A function may accept string or number when either identifier format is valid.
• An API response may return Success or Error objects, with a discriminant field used to narrow the result.
• A parser may accept a literal value or a structured configuration object, letting one entry point support both simple and advanced usage.
• A UI component may accept several prop shapes, where the chosen shape controls which fields are required.
• A security workflow may represent an authentication outcome as one of several states instead of forcing a shared object with many optional fields.

The main tradeoff is expressiveness versus complexity. Union types improve precision, but the more variants a developer adds, the more careful the runtime checks and test coverage must become. That is especially true when the union is wide enough that the code path must branch on subtle structural differences rather than obvious tags.

Security Implications

Union types influence security when they define how untrusted or ambiguous data is processed. If developers assume that a union member has properties or methods shared by all members, they can introduce unsafe access, missed validation, or incorrect business logic. Those failures are often subtle because the type checker may be satisfied after an incomplete narrowing step, while the runtime object still differs from the expected case.

A common failure mode is treating a union as though it were a single coherent object with optional fields. That pattern can hide invalid states, cause fragile authorization decisions, or skip checks that should only apply to one branch of the union. In practice, the observable symptoms are often inconsistent validation errors, broken edge cases, or code paths that behave correctly in tests but fail when new input variants appear.

For security-sensitive code, the key concern is not the type keyword itself but the discipline around narrowing, default handling, and exhaustive case coverage. When those are weak, the program can drift into unsafe assumptions even though the static types still look reasonable.

Domain and Governance Relevance

Union types matter in software engineering because they formalise uncertainty instead of hiding it. That makes them useful in APIs, protocol handlers, parsers, and state machines where multiple valid shapes must coexist. The governance question is whether the union is the right model for the domain, or whether it is being used to avoid designing a clearer contract.

In security and identity-adjacent systems, union types can be helpful when a workflow must distinguish between distinct entity classes, credential states, or response outcomes. The important governance change is that reviewers should expect explicit handling of each branch, not a presumed common path. That improves auditability, but only if the codebase treats narrowing and exhaustiveness as required design constraints rather than incidental implementation details.

For NHIMG readers, the relevant lesson is architectural rather than domain-specific: when a type system permits multiple shapes, the real control is whether every branch is understood, validated, and handled intentionally. A union type is therefore a precision tool, not a security control on its own.

Related resources from NHI Mgmt Group

• What breaks when organisations treat all keys as the same type of credential?
• What breaks when content-type confusion affects workflow file handling?
• Why do NHI controls matter in SOC 2 Type 2 assessments?
• When should organisations start planning for SOC 2 Type 2?