Mastering Type Assertion in TypeScript

Updated: January 8, 2024 By: Guest Contributor Post a comment


TypeScript’s type system is both powerful and complex, allowing developers to write safer and more predictable code. One particular feature of this type system is type assertion, which tells the compiler to consider an entity as a different type than the one it has inferred.

Getting Started with Type Assertions

To begin using type assertion, it’s important to recognize its syntax and basic usage. In TypeScript, you can assert a type using the angle-bracket syntax or the as keyword.


let someValue: any = 'This is a string';
let strLength: number = (someValue).length;
// or using 'as' syntax
let strLengthAs: number = (someValue as string).length;

Note that type assertion does not perform any special checking or restructuring of data. It has no runtime impact; it’s purely a compile-time construct.

Type Assertions with Objects

Assertions are significantly more useful when dealing with objects or complex types.

interface Person {
    name: string;
    age?: number;

let person = {} as Person; = 'Alice';
// person.age = 'unknown'; // Error: Type 'string' is not assignable to type 'number'.

This indicates to the TypeScript compiler what the shape of person is supposed to be, enforcing the correct property types.

Advanced Type Assertions

Moving to more complex scenarios, type assertions can be used to work with union types and type guards.

function getSmallPet(): Fish | Bird {
    // ...

let pet = getSmallPet();
if ((pet as Fish).swim) {
    (pet as Fish).swim();
} else if ((pet as Bird).fly) {
    (pet as Bird).fly();

Type assertions can also be chained in complex control flow situations to narrow down the type as you refine your logic.

Assertion vs Casting

It’s crucial to note that type assertion is not the same thing as casting in languages like Java or C#. Casting often implies some level of data transformation, while assertion is purely a compile-time signal to the TypeScript’s type checker. There’s no runtime check or conversion that happens when you use a type assertion in TypeScript.

Code Example:

let value: any = '123';
// Casting: Runtime conversion from string to number in JavaScript
// parseInt will be run on the 'value' at runtime
let numberValue1: number = parseInt(value);
// Assertion: Compile-time reassurance to TypeScript about the type
// No change happens at runtime here
let numberValue2: number = value as number;

Type Assertion Best Practices

Type assertions should be used judiciously. Overusing them can lead to a false sense of security and potentially undermine the benefits of TypeScript’s type system.


// Prefer
let someValue: any = 'This is a string';
let strLength: number = someValue.length;
// Over
let forcedStrLength: number = (someValue).length;

It’s also a good practice to perform appropriate checks before asserting types to avoid runtime errors.


TypeScript’s type assertion can be a powerful tool for developers, allowing you to provide more information to the compiler for effective type checking. Remember to use it wisely, in conjunction with type guards and proper programming patterns to exploit the full capabilities of TypeScript’s type system without losing the safety it provides.