Skip to main content

Using TypeScript Switch Statements Effectively

You're handling user permissions and need to check the role before granting access. You could write a chain of if-else statements, but with five different roles, your code quickly becomes hard to read and maintain. Switch statements give you a cleaner way to handle multiple discrete values, and when you combine them with TypeScript's type system, you get compile-time safety that catches bugs before they reach production.

This guide covers practical patterns for using switch statements with strings, enums, and union types, along with type safety techniques and performance considerations you'll actually use in real applications.

Understanding TypeScript Switch Basics​

A switch statement evaluates an expression once, then compares it against multiple case values. When a match is found, the corresponding code block executes:

function getStatusMessage(status: number): string {
  switch (status) {
    case 200:
      return 'Success';
    case 404:
      return 'Not found';
    case 500:
      return 'Server error';
    default:
      return 'Unknown status';
  }
}

Each case compares the switch expression using strict equality (===). When you're checking the same value against multiple possibilities, a switch is typically more readable than an if-else chain and can be optimized better by JavaScript engines. For simple boolean conditions or quick value assignments, you might prefer the ternary operator instead.

Implementing Type-Safe Switch Statements​

Type safety is one of TypeScript's main strengths, and it's crucial in switch statements. Using union types with switch statements is typical, but ensuring all possibilities are covered is key to avoiding errors. For example:

type Color = 'red' | 'green' | 'blue';

function getColorMessage(color: Color): string {
  switch (color) {
    case 'red':
      return 'The color is red';
    case 'green':
      return 'The color is green';
    case 'blue':
      return 'The color is blue';
    default:
      // Exhaustiveness check: If all cases are handled, color is type 'never' here
      // If you add a new color to the type, TypeScript will error here
      const _exhaustiveCheck: never = color;
      return _exhaustiveCheck;
  }
}

The never type in the default case creates an exhaustiveness check. Here's how it works: if all possible values are handled in the case statements above, TypeScript narrows the type of color to never by the time it reaches the default case (since there are no remaining possibilities).

If you later add 'yellow' to the Color type but forget to add a case for it, color won't be fully narrowed to never, and TypeScript will throw an error like "Type 'string' is not assignable to type 'never'". This catches incomplete switch statements at compile time, not runtime.

For more complex applications, consider using Convex to manage your data flow with strong typing throughout your application.

Handling Multiple Cases in TypeScript Switch Statements​

Sometimes, different cases need similar handling. TypeScript allows for grouping cases together easily. For example:

type Day = 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday';

function getDayType(day: Day): string {
  switch (day) {
    case 'Saturday':
    case 'Sunday':
      return 'Weekend';

    case 'Monday':
    case 'Tuesday':
    case 'Wednesday':
    case 'Thursday':
    case 'Friday':
      return 'Weekday';

    default:
      // Exhaustiveness check
      const exhaustiveCheck: never = day;
      return exhaustiveCheck;
  }
}

Notice how cases are grouped without any break statements between them. This intentional "fall-through" behavior allows multiple case values to share the same code block. TypeScript's compiler helps ensure that all possible values of the Day type are handled.

For complex data filtering scenarios like this, you might also consider using Convex's complex filtering capabilities, which offer TypeScript-based filtering with database-level performance.

This approach significantly simplifies your code compared to equivalent if else chains, making it more readable and maintainable.

Working with String Literals in TypeScript Switch Statements​

String literals are one of the most common values you'll switch on in real applications. When handling API responses, processing user input, or routing based on action types, string-based switches provide excellent readability:

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';

function handleRequest(method: HttpMethod, url: string): void {
  switch (method) {
    case 'GET':
      console.log(`Fetching data from ${url}`);
      break;

    case 'POST':
      console.log(`Creating new resource at ${url}`);
      break;

    case 'PUT':
      console.log(`Updating resource at ${url}`);
      break;

    case 'DELETE':
      console.log(`Deleting resource at ${url}`);
      break;

    default:
      const _exhaustiveCheck: never = method;
      throw new Error(`Unsupported method: ${_exhaustiveCheck}`);
  }
}

TypeScript's string literal types combine well with switch statements because they give you autocomplete for case values and prevent typos. If you accidentally type case 'GETT':, TypeScript catches it immediately.

For state machines or action reducers, you'll often switch on string action types:

type Action =
  | { type: 'INCREMENT'; amount: number }
  | { type: 'DECREMENT'; amount: number }
  | { type: 'RESET' };

function counterReducer(state: number, action: Action): number {
  switch (action.type) {
    case 'INCREMENT':
      // TypeScript knows action.amount exists here
      return state + action.amount;

    case 'DECREMENT':
      return state - action.amount;

    case 'RESET':
      return 0;

    default:
      const _exhaustiveCheck: never = action;
      return _exhaustiveCheck;
  }
}

Notice how TypeScript narrows the action type in each case based on the type property. This is called discriminated union type narrowing, and it's one of the most powerful patterns you can use with switch statements. You can read more about this pattern in our discriminated union guide.

Using Enums with Switch Statements​

Enums are great for defining a set of named values, making switch statements clearer and easier to maintain. Here's how to use enums with switch statements:

enum UserRole {
  Admin,
  Moderator,
  User,
}

function getPermissions(role: UserRole): string {
  switch (role) {
    case UserRole.Admin:
      return 'Admin permissions';
    case UserRole.Moderator:
      return 'Moderator permissions';
    case UserRole.User:
      return 'User permissions';
    default:
        // This exhaustiveness check ensures all enum values are handled
      const _exhaustiveCheck: never = role;
      return _exhaustiveCheck;
  }
}

// Usage
const adminPermissions = getPermissions(UserRole.Admin);
console.log(adminPermissions); // ['read', 'write', 'delete', 'manage_users']

Using string-based enums (like Admin = 'ADMIN') instead of numeric enums makes debugging easier since the values appear clearly in logs and network requests. This approach works especially well when integrating with Convex's type system, where you can define schema types that match your enum values for end-to-end type safety.

When working with complex data models, consider using the argument validation techniques from Convex to ensure your enums are properly validated throughout your application.

Improving Switch Statement Performance​

When dealing with many cases, switch statements can be more efficient than if-else chains because they can be optimized by the JavaScript engine. For situations where performance is important, consider using lookup tables instead. For example:

type Day = 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday';

// Object lookup approach
const DAY_TYPES: `Record<Day, string>` = {
  'Saturday': 'Weekend',
  'Sunday': 'Weekend',
  'Monday': 'Weekday',
  'Tuesday': 'Weekday',
  'Wednesday': 'Weekday',
  'Thursday': 'Weekday',
  'Friday': 'Weekday'
};

function getDayType(day: Day): string {
  return DAY_TYPES[day];
}

This approach using Record<K, V> eliminates the need for multiple comparisons and can be significantly faster for large sets of values. TypeScript ensures that our object contains all possible values from the Day type, maintaining type safety.

For data-heavy applications, consider using Convex's query optimization techniques, which automatically optimize database queries rather than requiring manual performance tuning in your client code.

When benchmarking on typical browsers, object lookups can be 2-10x faster than switch statements for large sets of values, though the difference is negligible for small sets with fewer than 10 cases.

Return vs Break: When to Use Each​

You'll notice some switch statements use break while others use return. Understanding when to use each is important for writing clear code.

Use return when the switch statement is the only logic in your function and you want to immediately exit with a value:

function getPermissionLevel(role: 'admin' | 'user' | 'guest'): number {
  switch (role) {
    case 'admin':
      return 3;
    case 'user':
      return 2;
    case 'guest':
      return 1;
    default:
      return 0;
  }
  // No code here will ever execute
}

Using return is cleaner in this case because you don't need break statements, and it's clear that each case terminates the function immediately.

Use break when you need to execute additional code after the switch statement:

function processOrder(status: 'pending' | 'processing' | 'shipped'): void {
  let message = '';
  let priority = 0;

  switch (status) {
    case 'pending':
      message = 'Order received';
      priority = 1;
      break;

    case 'processing':
      message = 'Order is being prepared';
      priority = 2;
      break;

    case 'shipped':
      message = 'Order has been shipped';
      priority = 3;
      break;
  }

  // This code runs after the switch completes
  console.log(`${message} (Priority: ${priority})`);
  logToDatabase(status, message);
}

Here, break exits the switch but allows the function to continue executing the logging code afterward. If you used return instead, the logging code would never run.

The choice is straightforward: use return when you're done with the function, use break when you have more work to do after the switch.

Managing Fall-Through in Switch Statements​

Fall-through happens when a case doesn't have a break or return statement, causing execution to continue into the next case. Sometimes this is intentional, but it's often a bug.

Intentional Fall-Through​

When you want multiple cases to share logic, you can intentionally omit the break:

function processStatus(status: 'new' | 'inProgress' | 'onHold' | 'complete'): string {
  let message = '';

  switch (status) {
    case 'new':
      message += 'Task has been created. ';
      // Intentional fall-through: new tasks also need work

    case 'inProgress':
      message += 'Work is required. ';
      break;

    case 'onHold':
      message += 'Task is waiting for input. ';
      break;

    case 'complete':
      message += 'No action needed. ';
      break;

    default:
      const exhaustiveCheck: never = status;
      return exhaustiveCheck;
  }

  return message;
}

console.log(processStatus('new')); // "Task has been created. Work is required."
console.log(processStatus('inProgress')); // "Work is required."

When you use intentional fall-through, always add a comment explaining why there's no break. Future you (or your teammates) will appreciate the clarity.

Watch Out for Accidental Fall-Through​

Forgetting a break statement is one of the most common switch-related bugs. Here's a realistic example:

// BAD: Missing break causes a bug
function applyDiscount(userType: 'premium' | 'standard' | 'trial'): number {
  let discount = 0;

  switch (userType) {
    case 'premium':
      discount = 0.20;
      // Oops! Forgot break here

    case 'standard':
      discount = 0.10;
      break;

    case 'trial':
      discount = 0;
      break;
  }

  return discount;
}

// This returns 0.10 instead of 0.20 because it falls through to 'standard'
console.log(applyDiscount('premium')); // 0.10 (wrong!)

You can catch these bugs automatically by enabling the noFallthroughCasesInSwitch compiler option in your tsconfig.json:

{
  "compilerOptions": {
    "noFallthroughCasesInSwitch": true
  }
}

With this flag enabled, TypeScript will error on any non-empty case that doesn't end with break, return, or throw. If you do want fall-through, you'll need to add a comment to make it explicit.

For complex state management, you might also explore Convex's state management approach, which provides typed data management with less error-prone state handling.

Using Switch Statements with Union Types​

With union types, switch statements can help narrow down types within each case, ensuring type safety and reducing errors. For example:

// Define a discriminated union type for different shapes
type Circle = {
  kind: 'circle';
  radius: number;
};

type Rectangle = {
  kind: 'rectangle';
  width: number;
  height: number;
};

type Triangle = {
  kind: 'triangle';
  base: number;
  height: number;
};

// Union type combining all shapes
type Shape = Circle | Rectangle | Triangle;

// Function to calculate area using switch for type narrowing
function calculateArea(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      // TypeScript knows shape is Circle here
      return Math.PI * shape.radius * shape.radius;

    case 'rectangle':
      // TypeScript knows shape is Rectangle here
      return shape.width * shape.height;

    case 'triangle':
      // TypeScript knows shape is Triangle here
      return (shape.base * shape.height) / 2;

    default:
      // Exhaustiveness check ensures all shape types are handled
      const exhaustiveCheck: never = shape.kind;
      throw new Error(`Unhandled shape kind: ${exhaustiveCheck}`);
  }
}

// Usage examples
const circle: Circle = { kind: 'circle', radius: 5 };
console.log(calculateArea(circle)); // 78.53981633974483

const rectangle: Rectangle = { kind: 'rectangle', width: 4, height: 6 };
console.log(calculateArea(rectangle)); // 24

In this example, the kind property acts as a discriminant, allowing TypeScript to narrow the type inside each case block. This type narrowing means you get full autocomplete and type-checking for the specific shape properties without any manual type assertions.

This pattern is incredibly useful for handling API responses, managing different event types, or modeling complex domain logic. The compiler guarantees you can't access properties that don't exist on the current type, and the exhaustiveness check ensures you handle all possibilities. For other type narrowing techniques, check out our guide on TypeScript typeof for runtime type guards.

For complex data modeling scenarios like this, Convex's type system can help you maintain type safety throughout your application, ensuring your discriminated union types are properly checked from the database to the UI.

Putting It All Together​

Switch statements become significantly more powerful when you combine them with TypeScript's type system. Here's what to remember:

  • Add exhaustiveness checks using never in your default case to catch incomplete switches when types change
  • Use return when you're done with the function, break when you have more code to execute afterward
  • Enable noFallthroughCasesInSwitch in your tsconfig to catch accidental fall-through bugs
  • Prefer string literal unions over plain strings for better autocomplete and typo prevention
  • Use discriminated unions when switching on objects with a discriminant property for automatic type narrowing
  • Consider object lookups for switches with many cases (10+) where performance matters

The real strength of TypeScript switch statements isn't just cleaner syntax than if-else chains. It's the compile-time guarantees you get when TypeScript can verify you've handled every possible case. This turns potential runtime errors into compiler errors you can fix before shipping.

For larger applications, Convex's TypeScript integration can provide consistent type safety across your entire stack.

Join the Discord