TypeScripttypescripttype-guardsdiscriminated-unionsproduction-ready
Exhaustive Type Guards
Type-safe discriminated union handling with exhaustive checking to catch missing cases at compile time.
// Exhaustive check helper - triggers compile error if a case is missed
function assertNever(value: never): never {
throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}
// Discriminated union types
type ApiResponse =
| { status: "loading" }
| { status: "success"; data: unknown; cachedAt?: Date }
| { status: "error"; error: Error; retryable: boolean }
| { status: "idle" };
// Type guard functions
function isSuccess(
response: ApiResponse
): response is Extract<ApiResponse, { status: "success" }> {
return response.status === "success";
}
function isError(
response: ApiResponse
): response is Extract<ApiResponse, { status: "error" }> {
return response.status === "error";
}
// Exhaustive handler
function handleResponse(response: ApiResponse): string {
switch (response.status) {
case "idle":
return "Waiting for request...";
case "loading":
return "Loading...";
case "success":
return `Data received${response.cachedAt ? " (cached)" : ""}`;
case "error":
return response.retryable
? `Error: ${response.error.message}. Retrying...`
: `Fatal: ${response.error.message}`;
default:
return assertNever(response);
}
}
// Runtime type narrowing for API payloads
interface User {
id: string;
email: string;
name: string;
}
function isUser(value: unknown): value is User {
return (
typeof value === "object" &&
value !== null &&
"id" in value &&
"email" in value &&
"name" in value &&
typeof (value as User).id === "string" &&
typeof (value as User).email === "string" &&
typeof (value as User).name === "string"
);
}
// Branded types for extra safety
type UserId = string & { readonly __brand: unique symbol };
type OrderId = string & { readonly __brand: unique symbol };
function createUserId(id: string): UserId {
if (!id.startsWith("usr_")) {
throw new Error("Invalid user ID format");
}
return id as UserId;
}title: "Exhaustive Type Guards" description: "Type-safe discriminated union handling with exhaustive checking to catch missing cases at compile time." category: "TypeScript" language: "typescript" tags: ["typescript", "type-guards", "discriminated-unions", "production-ready"] createdAt: "2025-01-08" updatedAt: "2025-01-25"
Overview
Type guards and exhaustive checking patterns that leverage TypeScript's type system to catch bugs at compile time. The assertNever pattern ensures that when you add new variants to a union type, the compiler forces you to handle them everywhere they are used.
Code
function assertNever(value: never): never {
throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}
type ApiResponse =
| { status: "loading" }
| { status: "success"; data: unknown; cachedAt?: Date }
| { status: "error"; error: Error; retryable: boolean }
| { status: "idle" };
function handleResponse(response: ApiResponse): string {
switch (response.status) {
case "idle":
return "Waiting for request...";
case "loading":
return "Loading...";
case "success":
return `Data received${response.cachedAt ? " (cached)" : ""}`;
case "error":
return response.retryable
? `Error: ${response.error.message}. Retrying...`
: `Fatal: ${response.error.message}`;
default:
return assertNever(response);
}
}Notes
- Adding a new variant to the union without handling it causes a compile-time error at the
assertNevercall - Use
ExtractandExcludeutility types to narrow union members in type guard return types - Branded types prevent accidental mixing of string IDs from different domains
- Runtime type guards (
isUser) are essential for validating data from external sources (APIs, localStorage)