Custom type guard functions in Typescript - Deep Dive

Overview - Custom type guard functions

What is it?

Custom type guard functions are special functions in TypeScript that help the program know the exact type of a value during runtime. They return true or false based on whether the value matches a specific type, and they tell TypeScript about this type check. This helps the program use the value safely with the right type information. They are written by the programmer to check types beyond what TypeScript can infer automatically.

Why it matters

Without custom type guards, TypeScript might not know the exact type of a value when it comes from uncertain sources like user input or external data. This can cause errors or force the programmer to write unsafe code. Custom type guards let the program check types clearly and safely, preventing bugs and making the code easier to understand and maintain.

Where it fits

Before learning custom type guards, you should understand basic TypeScript types, type narrowing, and the built-in type guards like 'typeof' and 'instanceof'. After mastering custom type guards, you can explore advanced type manipulation, discriminated unions, and writing safer complex applications.

Mental Model

Core Idea

A custom type guard is a function that checks a value at runtime and tells TypeScript the value’s type if the check passes.

Think of it like...

It's like a security guard at a club entrance who checks if a person has the right ID before letting them in. The guard confirms the person's identity, so the club knows who is inside.

┌─────────────────────────────┐
│        Input value          │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Custom Type Guard Function   │
│ (returns true/false + tells  │
│  TypeScript about the type)  │
└─────────────┬───────────────┘
              │
      true ┌──┴──┐ false
            │     │
            ▼     ▼
  ┌─────────────────────┐  ┌─────────────────────┐
  │ TypeScript treats    │  │ TypeScript treats    │
  │ value as specific    │  │ value as unknown or  │
  │ type inside block    │  │ other types outside  │
  └─────────────────────┘  └─────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding basic type guards

Concept: Learn what type guards are and how TypeScript uses them to narrow types.

Type guards are expressions or functions that check the type of a variable at runtime. For example, using 'typeof' or 'instanceof' helps TypeScript know if a variable is a string, number, or an instance of a class. This lets you safely use properties or methods specific to that type.

Result

TypeScript narrows the variable's type inside conditional blocks, preventing type errors.

Understanding built-in type guards is essential because custom type guards build on this idea to handle more complex or user-defined types.

2

Foundation

Recognizing the need for custom guards

Concept: See why built-in guards are not enough for complex or user-defined types.

Sometimes, you have types like interfaces or unions that TypeScript cannot narrow with 'typeof' or 'instanceof'. For example, checking if an object matches a specific interface requires a custom check. This is where custom type guard functions come in.

Result

You realize that to safely work with complex types, you need to write your own functions that tell TypeScript about the type.

Knowing the limits of built-in guards motivates learning custom guards to write safer and clearer code.

3

Intermediate

Writing a basic custom type guard

🤔Before reading on: do you think a custom type guard returns a boolean or the value itself? Commit to your answer.

Concept: Learn the syntax and structure of a custom type guard function that returns a boolean and uses 'value is Type' in the return type.

A custom type guard is a function that returns a boolean and has a special return type syntax: 'value is Type'. For example: function isString(value: unknown): value is string { return typeof value === 'string'; } This tells TypeScript that if the function returns true, 'value' is a string.

Result

TypeScript narrows the type of 'value' to 'string' inside the 'if' block where 'isString(value)' is true.

Understanding the 'value is Type' return type is key because it connects runtime checks with compile-time type information.

4

Intermediate

Using custom guards with union types

🤔Before reading on: do you think custom guards can narrow union types to one member? Commit to your answer.

Concept: Apply custom type guards to narrow union types safely by checking discriminating properties or conditions.

Suppose you have a union type like: interface Cat { meow: () => void; } interface Dog { bark: () => void; } type Pet = Cat | Dog; You can write a custom guard: function isCat(pet: Pet): pet is Cat { return (pet as Cat).meow !== undefined; } Then inside 'if (isCat(pet))', TypeScript knows 'pet' is a 'Cat'.

Result

You can safely call 'pet.meow()' inside the 'if' block without errors.

Custom guards let you safely work with complex unions by telling TypeScript exactly which type you have.

5

Intermediate

Combining multiple custom guards

🤔Before reading on: do you think multiple custom guards can be combined in one condition? Commit to your answer.

Concept: Learn how to use multiple custom type guards together to narrow types step-by-step.

You can combine guards with logical operators: if (isCat(pet) && isHappy(pet)) { // pet is Cat and happy } Each guard narrows the type further, allowing precise control over the variable's type.

Result

TypeScript understands the combined conditions and narrows types accordingly.

Knowing how to combine guards helps build complex type checks that keep code safe and readable.

6

Advanced

Custom guards with classes and interfaces

🤔Before reading on: do you think 'instanceof' can replace all custom guards for classes? Commit to your answer.

Concept: Explore when to use 'instanceof' versus custom guards for class instances and interfaces.

'instanceof' works for classes but not interfaces. For interfaces or complex shapes, custom guards check properties manually. For example: function isPerson(obj: any): obj is Person { return obj !== null && obj !== undefined && typeof obj.name === 'string' && typeof obj.age === 'number'; } This works even if 'Person' is an interface, not a class.

Result

You can safely check interface types at runtime, which 'instanceof' cannot do.

Understanding the difference between 'instanceof' and custom guards prevents bugs when working with interfaces.

7

Expert

Performance and pitfalls of custom guards

🤔Before reading on: do you think custom guards always run fast and never cause runtime errors? Commit to your answer.

Concept: Learn about performance costs and common mistakes in writing custom guards, including side effects and incorrect checks.

Custom guards run at runtime, so complex checks can slow down your program. Also, guards should be pure functions without side effects. Mistakes like accessing properties without checking existence can cause runtime errors. For example, checking 'obj.prop' without verifying 'obj' is not null can crash the program.

Result

Knowing these pitfalls helps write safe, efficient guards that don't break your app.

Recognizing performance and safety concerns in guards leads to better, more reliable code in production.

Under the Hood

Custom type guards are normal JavaScript functions that return a boolean. The special syntax 'value is Type' in the return type is a TypeScript feature that tells the compiler about the type when the function returns true. At runtime, the function runs like any other, but at compile time, TypeScript uses the return type to narrow types in the code that calls the guard.

Why designed this way?

TypeScript needed a way to let programmers define their own type checks beyond built-in ones. The 'value is Type' syntax was introduced to connect runtime checks with compile-time type safety without changing JavaScript behavior. This design keeps TypeScript compatible with JavaScript while adding powerful type narrowing.

┌───────────────┐
│ Custom Guard  │
│ Function      │
│ (runtime)     │
└──────┬────────┘
       │ returns true/false
       ▼
┌───────────────┐
│ TypeScript    │
│ Compiler      │
│ (compile-time)│
└──────┬────────┘
       │ uses 'value is Type' to narrow
       ▼
┌───────────────┐
│ Narrowed Type │
│ in code block │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a custom type guard change the runtime type of a value? Commit to yes or no.

Common Belief: A custom type guard changes the actual type of the value at runtime.

Reality: Custom type guards only check the type and inform TypeScript about it; they do not change the value or its type at runtime.

Why it matters: Believing this causes confusion and misuse, expecting guards to transform data instead of just checking it.

Quick: Can 'instanceof' always replace custom type guards? Commit to yes or no.

Common Belief: 'instanceof' can be used to check any type, so custom guards are unnecessary.

Reality: 'instanceof' only works with class instances, not interfaces or complex types, so custom guards are needed for those.

Why it matters: Relying only on 'instanceof' leads to incorrect type checks and runtime errors when working with interfaces.

Quick: Does a custom type guard guarantee no runtime errors inside its body? Commit to yes or no.

Common Belief: Custom type guards are always safe and cannot cause runtime errors.

Reality: If not carefully written, custom guards can cause runtime errors by accessing properties on undefined or null values.

Why it matters: Ignoring this can cause crashes and bugs, defeating the purpose of safe type checking.

Quick: Does TypeScript automatically infer custom type guards without explicit 'value is Type' return types? Commit to yes or no.

Common Belief: TypeScript can infer the type narrowing from any boolean function without special syntax.

Reality: Only functions with the 'value is Type' return type are recognized as type guards by TypeScript.

Why it matters: Without this syntax, TypeScript won't narrow types, leading to type errors or unsafe code.

Expert Zone

1

Custom type guards can be combined with discriminated unions to create very precise type narrowing in complex data structures.

2

Writing custom guards that check deeply nested properties requires careful null and undefined checks to avoid runtime errors.

3

TypeScript's control flow analysis uses custom guards to refine types even across multiple function calls, enabling modular type safety.

When NOT to use

Avoid custom type guards when simple built-in guards like 'typeof' or 'instanceof' suffice, as they are more efficient. For very complex validation, consider runtime validation libraries like 'io-ts' or 'zod' that provide schema-based checks and better error reporting.

Production Patterns

In production, custom type guards are often used to validate data from APIs or user input before processing. They are combined with error handling to ensure the program only works with valid data. Guards are also used in libraries to provide safer APIs and in large codebases to maintain strict type safety.

Connections

Discriminated Unions

Custom type guards build on discriminated unions by providing explicit runtime checks for union members.

Understanding custom guards deepens your ability to work with discriminated unions, making type narrowing more flexible and powerful.

Runtime Validation Libraries

Custom type guards are a manual form of runtime validation, while libraries automate and extend this process.

Knowing custom guards helps appreciate what validation libraries do under the hood and when to use each approach.

Medical Diagnostics

Both custom type guards and medical tests check for specific conditions to confirm identity or health status.

Seeing type guards as diagnostic tests helps understand their role in confirming types before proceeding safely.

Common Pitfalls

#1 Writing a custom guard that accesses properties without checking for null or undefined.

Wrong approach:

function isPerson(obj: any): obj is Person {
return typeof obj.name === 'string';
}

Correct approach:

function isPerson(obj: any): obj is Person {
return obj !== null && obj !== undefined && typeof obj.name === 'string';
}

Root cause:

Assuming the input is always an object leads to runtime errors when it is null or undefined.

#2 Omitting the 'value is Type' return type in the custom guard function.

Wrong approach:

function isString(value: unknown): boolean {
return typeof value === 'string';
}

Correct approach:

function isString(value: unknown): value is string {
return typeof value === 'string';
}

Root cause:

Not using the special return type means TypeScript does not recognize the function as a type guard.

#3 Using 'instanceof' to check interface types.

Wrong approach:

if (obj instanceof PersonInterface) { /* ... */ }

Correct approach:

if (isPerson(obj)) { /* ... */ } // where isPerson is a custom guard

Root cause:

'instanceof' only works with classes, not interfaces, so it cannot check interface types.

Key Takeaways

Custom type guard functions let you tell TypeScript about the type of a value after a runtime check.

They use a special return type syntax 'value is Type' to connect runtime checks with compile-time type safety.

Custom guards are essential for narrowing complex types like interfaces and unions that built-in guards cannot handle.

Writing safe custom guards requires careful checks to avoid runtime errors and ensure accurate type narrowing.

Understanding custom guards unlocks safer and clearer TypeScript code, especially when working with uncertain or external data.