Hemanta Sundaray

Understanding Type Predicates in TypeScript

Avatar of Hemanta Sundaray

Hemanta Sundaray

Published

A type predicate is a special function return type that acts as a user-defined type guard, allowing you to create custom logic for narrowing types. It uses the syntax parameter is Type to tell TypeScript that if the function returns true, the parameter should be treated as the specified type.

Type predicates solve a key limitation with regular boolean functions. (A boolean function is simply a function that returns either true or false.)

Let’s break this down using an example.

Below, we have two functions:

  1. isPerson: A helper function that checks if an age property is present inside the item and returns true or false accordingly.
  2. processItem: Processes an item that could be either a Person or a Product. Inside, we use isPerson to narrow the item's type.
TypeScript
interface 
interface Person
Person {
  
Person.name: string
name: string;
  
Person.age: number
age: number;
}


interface 
interface Product
Product {
  
Product.name: string
name: string;
  
Product.price: number
price: number;
}


type 
type PersonOrProduct = Person | Product
PersonOrProduct = 
interface Person
Person | 
interface Product
Product;


function 
function isPerson(item: PersonOrProduct): boolean
isPerson(
item: PersonOrProduct
item: 
type PersonOrProduct = Person | Product
PersonOrProduct): boolean {
  return "age" in 
item: PersonOrProduct
item;
}


function 
function processItem(item: PersonOrProduct): void
processItem(
item: PersonOrProduct
item: 
type PersonOrProduct = Person | Product
PersonOrProduct) {
  if (
function isPerson(item: PersonOrProduct): boolean
isPerson(
item: PersonOrProduct
item)) {
    
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log(`Person: ${
item: PersonOrProduct
item.
name: string
name}, Age: ${
item: PersonOrProduct
item.age}`);
Error ts(2339)  ― Property 'age' does not exist on type 'PersonOrProduct'.
  Property 'age' does not exist on type 'Product'.
  }
}

This code produces an error, but why? The logic inside isPerson is perfectly sound.

The problem is that to the TypeScript compiler, the isPerson function is a "black box." It knows the function takes a PersonOrProduct and returns a boolean, but it has no idea that the true or false value is related to the type of item.

So, even inside the if (isPerson(item)) block, TypeScript's understanding of the item variable has not changed. It still thinks item is a PersonOrProduct, and it correctly points out that you can't safely access .age on a PersonOrProduct.

So, how do we fix this?

This is exactly the problem that type predicates are designed to solve.

We fix it by changing only the return type of our isPerson function:

Typescript
function 
function isPerson(item: PersonOrProduct): item is Person
isPerson(
item: PersonOrProduct
item: 
type PersonOrProduct = Person | Product
PersonOrProduct): 
item: PersonOrProduct
item is 
interface Person
Person {
  return "age" in 
item: PersonOrProduct
item;
}

The only difference is the return type: item is Person. This is the type predicate.

It's a special signature that makes a direct promise to the TypeScript compiler:

"Hey, TypeScript! This function returns a boolean. If it returns true, I personally guarantee that the argument passed is of type Person."

Now, TypeScript can use this extra information to perform type narrowing, and our processItem function works perfectly:

TypeScript
function 
function processItem(item: PersonOrProduct): void
processItem(
item: PersonOrProduct
item: 
type PersonOrProduct = Person | Product
PersonOrProduct) {
  if (
function isPerson(item: PersonOrProduct): item is Person
isPerson(
item: PersonOrProduct
item)) {
    // AT COMPILE-TIME, TypeScript sees this `if` block.
    // It says: "The developer used a function with the promise `item is Person`.
    // Since I'm inside the 'true' part of the `if` statement,
    // I will honor that promise and treat `item` as a `Person` here."
    
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log(`Person: ${
item: Person
item.
Person.name: string
name}, Age: ${
item: Person
item.
Person.age: number
age}`); // ✅ So this is allowed.
  } else {
    // TypeScript also says: "If the promise was not fulfilled (the function
    // returned false), then `item` cannot be a `Person`.
    // Since the original type was `Person | Product`, it must be a `Product`."
    
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log(`Product: ${
item: Product
item.
Product.name: string
name}, Price: $${
item: Product
item.
Product.price: number
price}`); // ✅ So this is allowed.
  }
}

TAGS:

TypeScript
Understanding Type Predicates in TypeScript