TypeScript Type Guards

Narrow union types safely using type guards, assertion functions, and control flow

When to Use

• Narrowing union types to access type-specific properties
• Validating unknown data from APIs or user input
• Replacing unsafe type assertions (

  as

  ) with safe runtime checks
• Creating reusable narrowing functions for domain types

Instructions

1. typeof

   guard for primitives:

function format(value: string | number): string {
  if (typeof value === 'string') {
    return value.toUpperCase(); // Narrowed to string
  }
  return value.toFixed(2); // Narrowed to number
}

2. instanceof

   guard for class instances:

function handleError(error: Error | string): string {
  if (error instanceof Error) {
    return error.message; // Narrowed to Error
  }
  return error; // Narrowed to string
}

3. Custom type guard with

   is

   predicate:

interface Cat {
  meow(): void;
}
interface Dog {
  bark(): void;
}

function isCat(animal: Cat | Dog): animal is Cat {
  return 'meow' in animal;
}

function interact(animal: Cat | Dog) {
  if (isCat(animal)) {
    animal.meow(); // Narrowed to Cat
  } else {
    animal.bark(); // Narrowed to Dog
  }
}

4. Narrowing with

   in

   operator:

type ApiResponse = { status: 'success'; data: User } | { status: 'error'; message: string };

function handle(response: ApiResponse) {
  if ('data' in response) {
    console.log(response.data); // Narrowed to success variant
  }
}

5. Assertion function — narrows or throws:

function assertDefined<T>(value: T | null | undefined, name: string): asserts value is T {
  if (value == null) {
    throw new Error(`Expected ${name} to be defined`);
  }
}

function process(user: User | null) {
  assertDefined(user, 'user');
  // user is narrowed to User after this line
  console.log(user.name);
}

6. Narrow

   unknown

   values safely:

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function isUser(value: unknown): value is User {
  return isRecord(value) && typeof value.id === 'string' && typeof value.email === 'string';
}

7. Array filtering with type guards:

const items: (string | null)[] = ['a', null, 'b', null, 'c'];

// Without type guard: (string | null)[]
const filtered = items.filter((x) => x !== null);

// With type guard: string[]
const filtered = items.filter((x): x is string => x !== null);

8. Discriminated union narrowing:

type Shape = { kind: 'circle'; radius: number } | { kind: 'rect'; width: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'rect':
      return shape.width * shape.height;
  }
}

Details

Type guards are runtime checks that TypeScript uses to narrow types in subsequent code. They bridge the gap between TypeScript's static type system and JavaScript's dynamic runtime.

Control flow analysis: TypeScript tracks type narrowing through

if/else

switch

return

throw

is

boolean

x is Type

is

true

Assertion functions (

asserts x is T

asserts

is

• is

  — used in conditions (

  if

  ,

  filter

  ). Returns boolean.

• asserts

  — used as a statement. Throws on failure. Narrows for subsequent code.

Truthiness narrowing: TypeScript narrows

if (value)

null

undefined

0

''

false

!= null

0

''

Trade-offs:

• Custom type guards with

  is

  put the burden of correctness on the developer — an incorrect guard silently misnarrows

• instanceof

  does not work across iframes, realms, or serialized objects
• Assertion functions cannot be used in expression position — they must be standalone statements
• Deep narrowing of nested objects requires multiple guard calls or a comprehensive validation library like Zod

Source

https://typescriptlang.org/docs/handbook/2/narrowing.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.