Frontend Engineering | VoidX Academy

12. Union, Literal Types & Type Narrowing

Handling Dynamic Data Safely

Real applications don't always deal with single, predictable data types. An API might return a string if it succeeds, but a number (like a 404 status code) if it fails. We need a way to tell TypeScript that a variable can legitimately be more than one thing.

Union Types

A Union Type allows you to combine multiple types together. You use the pipe character | (meaning "OR") to define it.

// This variable is allowed to be a string OR a number
let dynamicId: string | number;

dynamicId = 101; // Valid!
dynamicId = "USER_101"; // Valid!
// dynamicId = true; // ERROR: Type 'boolean' is not assignable to type 'string | number'.

Literal Types

Sometimes defining a variable as a `string` is too broad. If you have a user role system, the role shouldn't just be any string (like "banana"); it should only be specific, exact strings. These are called Literal Types.

// This variable can only ever hold one of these exact three strings
type Role = "admin" | "editor" | "user";

let myRole: Role = "admin"; // Valid
// myRole = "superadmin"; // ERROR: Type '"superadmin"' is not assignable to type 'Role'.

// You can do this with numbers too!
type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;

The Problem with Unions

Unions are flexible, but they introduce a problem. If TypeScript knows a variable is string | number, it will stop you from using string-specific methods on it, because what if it happens to be a number at runtime? It would crash!

function printId(id: string | number) {
  // ERROR: Property 'toUpperCase' does not exist on type 'number'.
  // TS protects you because 'id' MIGHT be a number right now.
  // console.log(id.toUpperCase()); 
}

Type Narrowing (The Solution)

To safely interact with a union type, you must narrow it down to a specific type using standard JavaScript logic (like `if` statements). TypeScript is incredibly smart—it reads your `if` statements and automatically narrows the type inside that block of code.

function printId(id: string | number) {
  // TYPE GUARD: We check the type at runtime
  if (typeof id === "string") {
    // Magic! Inside this block, TS knows 'id' is 100% a string.
    // Autocomplete for string methods will work perfectly here.
    console.log(id.toUpperCase());
  } else {
    // If it wasn't a string, TS logically deduces it MUST be a number in this 'else' block.
    console.log("Your numerical ID is:", id.toFixed(2));
  }
}

12. Union, Literal Types & Type Narrowing

Handling Dynamic Data Safely

Union Types

A Union Type allows you to combine multiple types together. You use the pipe character | (meaning "OR") to define it.

// This variable is allowed to be a string OR a number
let dynamicId: string | number;

dynamicId = 101; // Valid!
dynamicId = "USER_101"; // Valid!
// dynamicId = true; // ERROR: Type 'boolean' is not assignable to type 'string | number'.

Literal Types

// This variable can only ever hold one of these exact three strings
type Role = "admin" | "editor" | "user";

let myRole: Role = "admin"; // Valid
// myRole = "superadmin"; // ERROR: Type '"superadmin"' is not assignable to type 'Role'.

// You can do this with numbers too!
type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;

The Problem with Unions

function printId(id: string | number) {
  // ERROR: Property 'toUpperCase' does not exist on type 'number'.
  // TS protects you because 'id' MIGHT be a number right now.
  // console.log(id.toUpperCase()); 
}

Type Narrowing (The Solution)

function printId(id: string | number) {
  // TYPE GUARD: We check the type at runtime
  if (typeof id === "string") {
    // Magic! Inside this block, TS knows 'id' is 100% a string.
    // Autocomplete for string methods will work perfectly here.
    console.log(id.toUpperCase());
  } else {
    // If it wasn't a string, TS logically deduces it MUST be a number in this 'else' block.
    console.log("Your numerical ID is:", id.toFixed(2));
  }
}

12. Union, Literal Types & Type Narrowing

Handling Dynamic Data Safely

Union Types

Literal Types

The Problem with Unions

Type Narrowing (The Solution)

Knowledge Check

12. Union, Literal Types & Type Narrowing

Handling Dynamic Data Safely

Union Types

Literal Types

The Problem with Unions

Type Narrowing (The Solution)

Knowledge Check