Custom type guard functions in Typescript - Step-by-Step Execution

Concept Flow - Custom type guard functions

Call function with unknown type

↓

Check condition inside function

↓

Return true

↓

TypeScript narrows type

↓

Use narrowed type safely

The function checks a condition to confirm a type, returns true or false, and TypeScript uses this to narrow the variable's type.

Execution Sample

Typescript

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

const input: unknown = 'hello';
if (isString(input)) {
  console.log(input.toUpperCase());
}

This code defines a custom type guard to check if a value is a string, then safely uses string methods after the check.

Execution Table

Step	Action	Input Value	Condition Result	Return Value	TypeScript Type After
1	Call isString with input='hello'	'hello'	typeof 'hello' === 'string' is true	true	input is string
2	Inside if block, use input.toUpperCase()	'hello'	N/A	N/A	input treated as string
3	Output result of input.toUpperCase()	'hello'	N/A	N/A	Output: 'HELLO'
4	If input was not string, isString would return false	e.g. 123	false	false	input remains unknown
5	Outside if block, input type not narrowed	e.g. 123	N/A	N/A	input is unknown

💡 Execution stops after safely using input as string inside if block or skipping if not string.

Variable Tracker

Variable	Start	After Step 1	After Step 2	Final
input	unknown ('hello')	'hello' (checked)	'hello' (narrowed to string)	'hello' (used as string)
isString(input)	N/A	true	N/A	N/A

Key Moments - 3 Insights

Why does TypeScript allow calling string methods on input inside the if block?

Because the custom type guard returned true at step 1, TypeScript narrows input's type to string inside the if block, allowing string methods safely.

What happens if the input is not a string?

At step 4, the type guard returns false, so TypeScript keeps input as unknown outside the if block, preventing unsafe string method calls.

Why do we write 'value is string' in the function signature?

This syntax tells TypeScript that when the function returns true, the input value can be treated as a string, enabling type narrowing.

Visual Quiz - 3 Questions

Look at the execution table, what is the type of 'input' after step 1?

A number

B unknown

C string

D boolean

💡 Hint

Check the 'TypeScript Type After' column in row 1.

At which step does the function return false for a non-string input?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Look for the row where the return value is false in the execution table.

If the type guard function always returned true, what would happen to the type of 'input'?

A It would always be narrowed to string

B It would remain unknown

C It would become number

D It would cause a compile error

💡 Hint

Refer to how TypeScript narrows types when the guard returns true in the execution table.

Concept Snapshot

Custom type guard functions use the syntax 'value is Type' in the return type.
They return true if the value matches the type, false otherwise.
TypeScript uses this to narrow variable types inside conditional blocks.
This allows safe use of properties and methods specific to the narrowed type.
Example: function isString(value: unknown): value is string { return typeof value === 'string'; }

Full Transcript

This visual execution shows how a custom type guard function works in TypeScript. The function is called with a value of unknown type. Inside the function, a condition checks if the value is a string. If true, the function returns true, and TypeScript narrows the variable's type to string in the if block. This allows safe use of string methods like toUpperCase. If the function returns false, TypeScript keeps the type as unknown outside the if block, preventing unsafe operations. The key is the special return type syntax 'value is string' which tells TypeScript how to narrow types based on the function's result.

Practice

1. What is the main purpose of a custom type guard function in TypeScript?

easy

A. To declare a new type alias

B. To convert a value from one type to another

C. To check if a value matches a specific type and help TypeScript narrow types

D. To throw an error when a type mismatch occurs

Solution

1. Step 1: Understand what a type guard does

   A type guard checks if a value is of a certain type at runtime.

2. Step 2: Recognize the benefit in TypeScript

   It helps TypeScript narrow the type, making code safer and clearer.

3. Final Answer:

   To check if a value matches a specific type and help TypeScript narrow types -> Option C

4. Quick Check:

   Type guard = check type + narrow [OK]

Hint: Type guards confirm type and help TypeScript narrow it [OK]

Common Mistakes:

• Thinking type guards convert types
• Confusing type guards with error handling
• Believing type guards declare new types

2. Which of the following is the correct syntax for a custom type guard function named isString that checks if a value is a string?

easy

A. function isString(value: any): value is string { return typeof value === 'string'; }

B. function isString(value: any): boolean { return typeof value === 'string'; }

C. function isString(value: any): string { return typeof value === 'string'; }

D. function isString(value: any): value is boolean { return typeof value === 'string'; }

Solution

1. Step 1: Identify the return type for a type guard

   A custom type guard returns a type predicate like value is string.

2. Step 2: Check the function body

   The function should return true if typeof value === 'string'.

3. Final Answer:

   function isString(value: any): value is string { return typeof value === 'string'; } -> Option A

4. Quick Check:

   Type guard syntax = value is Type [OK]

Hint: Type guard return type uses 'value is Type' syntax [OK]

Common Mistakes:

• Using boolean instead of type predicate as return type
• Returning wrong type predicate
• Returning the type instead of a boolean

3. What will be the output of the following TypeScript code?

function isNumber(value: any): value is number {
  return typeof value === 'number';
}

const input: any = 42;
if (isNumber(input)) {
  console.log(input.toFixed(2));
} else {
  console.log('Not a number');
}

medium

A. 42.00

B. Not a number

C. Error: toFixed is not a function

D. undefined

Solution

1. Step 1: Check the type guard function behavior

   The function isNumber returns true if value is a number.

2. Step 2: Analyze the if condition and output

   Since input is 42 (a number), the if block runs and input.toFixed(2) outputs '42.00'.

3. Final Answer:

   42.00 -> Option A

4. Quick Check:

   isNumber(42) = true, so prints 42.00 [OK]

Hint: If type guard true, use narrowed type safely [OK]

Common Mistakes:

• Assuming input is not a number
• Expecting runtime error on toFixed
• Confusing output with string conversion

4. Identify the error in this custom type guard function and choose the fix:

function isArray(value: any): value is Array {
  return Array.isArray(value);
}

medium

A. Change function name to 'isArrayType'

B. Change return type to 'value is any[]' instead of 'value is Array'

C. Add explicit type annotation to parameter 'value: unknown'

D. Replace 'Array.isArray' with 'typeof value === "array"'

Solution

1. Step 1: Understand the return type syntax

   The return type should be a type predicate with a specific type, e.g., value is any[] for arrays.

2. Step 2: Identify the incorrect type usage

   Array alone is a constructor, not a type for arrays. Use any[] or a typed array instead.

3. Final Answer:

   Change return type to 'value is any[]' instead of 'value is Array' -> Option B

4. Quick Check:

   Array type predicate = value is any[] [OK]

Hint: Use 'value is Type[]' for arrays in type guards [OK]

Common Mistakes:

• Using 'Array' instead of 'any[]' or typed array
• Changing function name unnecessarily
• Using typeof 'array' which is invalid

5. Given the following types and function, which implementation correctly narrows the type to Dog using a custom type guard?

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

type Pet = Dog | Cat;

function isDog(pet: Pet): pet is Dog {
  // Which implementation is correct?
}

hard

A. return pet.meow === undefined;

B. return pet instanceof Dog;

C. return typeof pet.bark === 'function';

D. return (pet as Dog).bark !== undefined;

Solution

1. Step 1: Understand the interfaces and type guard goal

   We want to check if pet has a bark method to confirm it's a Dog.

2. Step 2: Evaluate the implementations

   Directly accessing pet.bark or pet.meow causes TypeScript compile errors because those properties do not exist on the union type Pet.
   pet instanceof Dog does not work because Dog is an interface, not a class with a constructor.
   Using (pet as Dog).bark !== undefined compiles due to the type assertion and performs a runtime check to see if the bark property exists.

3. Final Answer:

   return (pet as Dog).bark !== undefined; -> Option D

4. Quick Check:

   Type assertion enables property check in union type guards [OK]

Hint: Use type assertion inside type guards for union property checks [OK]

Common Mistakes:

• Using instanceof with interfaces
• Directly accessing properties on union types
• Checking absence of other type's method