Type alias for unions in Typescript - Deep Dive

Overview - Type alias for unions

What is it?

A type alias for unions in TypeScript lets you create a new name for a group of types combined with the '|' symbol. This means a value can be one of several types under a single alias. It helps make code easier to read and reuse by giving a meaningful name to multiple possible types.

Why it matters

Without type aliases for unions, you would have to repeat complex union types everywhere, making code harder to read and maintain. This concept helps catch errors early by clearly defining what types a value can be, improving code safety and developer confidence.

Where it fits

Before learning this, you should understand basic TypeScript types and the union type operator '|'. After this, you can learn about advanced type features like intersection types, type guards, and conditional types.

Mental Model

Core Idea

A type alias for unions is a simple label that groups multiple types so a value can be any one of them under a single name.

Think of it like...

It's like a TV remote control that can operate different brands of TVs; the remote is the alias, and the brands are the types it can control.

TypeAlias = TypeA | TypeB | TypeC

Value: can be TypeA or TypeB or TypeC

┌─────────────┐
│ TypeAlias   │
│─────────────│
│ TypeA      │
│ TypeB      │
│ TypeC      │
└─────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding basic union types

Concept: Learn what union types are and how to write them using the '|' symbol.

In TypeScript, a union type means a value can be one of several types. For example, 'string | number' means the value can be a string or a number. Example: let value: string | number; value = 'hello'; // valid value = 42; // valid value = true; // error

Result

The variable 'value' accepts either a string or a number but not other types.

Understanding union types is the foundation for grouping multiple types under one name.

2

Foundation

Creating simple type aliases

Concept: Learn how to create a type alias to name a single type for reuse.

A type alias gives a new name to a type using the 'type' keyword. Example: type Name = string; let userName: Name; userName = 'Alice'; // valid userName = 123; // error

Result

The alias 'Name' represents the string type, making code clearer.

Type aliases simplify code by giving meaningful names to types.

3

Intermediate

Combining type aliases with unions

🤔Before reading on: do you think a type alias can represent multiple types combined with '|'? Commit to yes or no.

Concept: Learn how to create a type alias that represents a union of multiple types.

You can combine union types with type aliases to create a single name for multiple types. Example: type ID = string | number; let userId: ID; userId = 'abc123'; // valid userId = 456; // valid userId = true; // error

Result

The alias 'ID' represents either a string or a number, making it easier to reuse this union type.

Knowing that type aliases can hold unions helps organize and simplify complex type definitions.

4

Intermediate

Using union aliases in functions

🤔Before reading on: do you think a function parameter typed with a union alias can accept any of the union's types? Commit to yes or no.

Concept: Learn how to use union type aliases as function parameter types to accept multiple types safely.

Functions can use union aliases to accept different types of inputs. Example: type Input = string | number; function printValue(value: Input) { console.log(value); } printValue('hello'); // prints 'hello' printValue(100); // prints 100 printValue(true); // error

Result

The function accepts either a string or number, improving flexibility while keeping type safety.

Using union aliases in functions makes code flexible without losing the benefits of type checking.

5

Intermediate

Extending union aliases with other types

Concept: Learn how to combine union aliases with other types or aliases to build more complex types.

You can create new union aliases by combining existing aliases or types. Example: type Status = 'success' | 'error'; type Response = Status | number; let res1: Response = 'success'; // valid let res2: Response = 404; // valid let res3: Response = true; // error

Result

The 'Response' alias can be either a status string or a number, showing how unions can grow.

Building union aliases from smaller parts helps manage complex type systems in large codebases.

6

Advanced

Type narrowing with union aliases

🤔Before reading on: do you think TypeScript automatically knows which union type a value is inside a function? Commit to yes or no.

Concept: Learn how to safely work with union aliases by checking the actual type at runtime (type narrowing).

When a value can be multiple types, you often need to check its type before using it. Example: function process(input: string | number) { if (typeof input === 'string') { console.log(input.toUpperCase()); } else { console.log(input.toFixed(2)); } } process('hello'); // prints 'HELLO' process(3.1415); // prints '3.14'

Result

The function safely handles both string and number inputs by checking the type first.

Understanding type narrowing is key to using union aliases safely and avoiding runtime errors.

7

Expert

Advanced union alias patterns and pitfalls

🤔Before reading on: do you think union aliases can cause confusing errors if types overlap or are too broad? Commit to yes or no.

Concept: Explore complex cases where union aliases interact with other types, and learn how to avoid common pitfalls.

Sometimes union aliases include overlapping types or too broad types, causing unexpected behavior. Example: type A = { kind: 'a'; value: number }; type B = { kind: 'b'; value: string }; type AB = A | B; function handle(ab: AB) { if (ab.kind === 'a') { console.log(ab.value + 1); // safe } else { console.log(ab.value.toUpperCase()); // safe } } // Pitfall: if 'kind' is missing or wrong, TypeScript can't narrow correctly. // Also, very broad unions like 'string | number | boolean' can make code harder to maintain.

Result

Properly discriminated unions allow safe type narrowing; careless unions can cause bugs or confusing errors.

Knowing how to design union aliases with discriminants and avoid overly broad unions prevents subtle bugs in large projects.

Under the Hood

TypeScript uses union aliases as compile-time constructs that represent multiple possible types. At runtime, these aliases do not exist; they help the compiler check that values match one of the allowed types. When you use type narrowing, TypeScript inserts checks to ensure safe access to properties or methods specific to each type in the union.

Why designed this way?

Type aliases for unions were designed to improve code readability and maintainability by naming complex type combinations. They allow developers to express flexible APIs while keeping strong type safety. Alternatives like interfaces or classes are more rigid, so unions provide a lightweight way to handle multiple types without extra runtime overhead.

┌───────────────┐
│ Type Alias    │
│ (compile-time)│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Union Types   │
│ (string |     │
│  number | ... │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Runtime Value │
│ (string or    │
│  number)      │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a union alias create a new type at runtime? Commit to yes or no.

Common Belief: A union type alias creates a new type that exists at runtime and can be checked with 'instanceof'.

Reality: Type aliases, including unions, are erased during compilation and do not exist at runtime. You cannot use 'instanceof' to check them.

Why it matters: Believing this leads to runtime errors when trying to check types with 'instanceof' instead of using type guards like 'typeof' or discriminants.

Quick: Can you assign any type to a union alias if one of the union types matches? Commit to yes or no.

Common Belief: If a union alias includes a type, you can assign any value of that type without restrictions.

Reality: You can only assign values that exactly match one of the union types. Extra properties or incompatible types cause errors.

Why it matters: Ignoring this causes type errors or unexpected bugs when values don't strictly conform to the union types.

Quick: Does TypeScript automatically know which union type a value is without checks? Commit to yes or no.

Common Belief: TypeScript always knows the exact type inside a union without needing explicit checks.

Reality: TypeScript requires explicit type narrowing (like 'typeof' or discriminants) to safely use union types.

Why it matters: Assuming automatic knowledge leads to unsafe code and compiler errors when accessing properties.

Quick: Can overly broad union aliases improve code clarity? Commit to yes or no.

Common Belief: Making union aliases very broad (like including many types) always makes code more flexible and clear.

Reality: Overly broad unions can make code confusing, harder to maintain, and increase bugs due to unclear type expectations.

Why it matters: This misconception leads to poor type design and harder-to-debug code.

Expert Zone

1

Discriminated unions use a common property to let TypeScript narrow types precisely, avoiding unsafe casts.

2

Union aliases can interact with generics and conditional types to create powerful, flexible type systems.

3

Excessive use of union aliases without clear design can degrade editor performance and slow down type checking.

When NOT to use

Avoid union aliases when types require complex behavior or methods; prefer classes or interfaces with inheritance. Also, do not use very broad unions that reduce type safety; instead, use more specific types or branded types.

Production Patterns

In real-world code, union aliases are used for API response types, event payloads, and configuration options. Discriminated unions are common for state machines and Redux actions to ensure safe and clear state handling.

Connections

Algebraic Data Types (ADTs)

Type aliases for unions are a form of ADTs used in functional programming.

Understanding union aliases helps grasp ADTs, which model data that can be one of several forms, improving reasoning about program states.

Polymorphism in Object-Oriented Programming

Union types provide a lightweight alternative to polymorphism by allowing multiple types without inheritance.

Knowing union aliases clarifies how TypeScript handles multiple types without classical polymorphism, offering flexibility with type safety.

Set Theory in Mathematics

Union types correspond to the union operation in set theory, combining multiple sets of values.

Recognizing union types as set unions helps understand their behavior and constraints, linking programming types to mathematical concepts.

Common Pitfalls

#1 Assigning a value not included in the union alias.

Wrong approach:

type ID = string | number;
let userId: ID;
userId = true; // Error: boolean not in union

Correct approach:

type ID = string | number;
let userId: ID;
userId = 'abc'; // valid
userId = 123; // valid

Root cause:

Misunderstanding that union aliases restrict values to only the listed types.

#2 Trying to check union types at runtime with 'instanceof'.

Wrong approach:

type ID = string | number;
function isString(id: ID) {
return id instanceof String; // always false
}

Correct approach:

function isString(id: ID) {
return typeof id === 'string';
}

Root cause:

Confusing compile-time types with runtime objects; 'instanceof' works only with class instances.

#3 Not narrowing union types before accessing specific properties.

Wrong approach:

type A = { kind: 'a'; value: number } | { kind: 'b'; value: string };
function printValue(obj: A) {
console.log(obj.value.toUpperCase()); // Error if obj is kind 'a'
}

Correct approach:

function printValue(obj: A) {
if (obj.kind === 'b') {
console.log(obj.value.toUpperCase());
} else {
console.log(obj.value.toFixed(2));
}
}

Root cause:

Assuming TypeScript knows the exact type without explicit checks.

Key Takeaways

Type aliases for unions let you name a group of types combined with '|', making code clearer and reusable.

They exist only at compile time to help TypeScript check that values match one of the allowed types.

Using union aliases with type narrowing ensures safe access to properties and methods specific to each type.

Designing discriminated unions with a common property helps TypeScript narrow types precisely and avoid bugs.

Avoid overly broad unions and runtime type checks with 'instanceof'; use type guards and specific types instead.