Type Predicate

The is keyword in TypeScript is a type predicate operator used within a function’s return type annotation to create a user-defined type guard. It instructs the TypeScript compiler’s control flow analysis to narrow the type of a specific parameter to a declared type within the caller’s scope when the function evaluates to true.

Syntax

The syntax requires the parameter name, the is keyword, and the target type. The parameter name referenced in the predicate must exactly match a parameter name in the function signature.

type BaseType = string | number;
type NarrowedType = string;

function isNarrowed(parameterName: BaseType): parameterName is NarrowedType {
    return typeof parameterName === "string";
}

Mechanics and Control Flow Analysis

The is operator bridges runtime boolean evaluation and the compile-time type system. When a function annotated with parameterName is Type is invoked in a conditional statement (such as an if block), the compiler applies the following control flow logic:

1. On true: The compiler narrows the type of the passed argument from its base type to the target type within the if branch.
2. On false: If the parameter’s base type is a union and the target type is a constituent of that union, the compiler narrows the type to the complement of the target type (e.g., if the base type is string | number and the predicate checks for string, the false branch narrows the type to number). However, if the base type is unknown or any, the false branch does not narrow to a complement type; the parameter remains unknown or any.

As of TypeScript 5.5, the compiler automatically infers type predicates for standard functions returning a boolean if the function body narrows the parameter. Explicitly declaring the is operator enforces the type narrowing contract in the function signature. This explicit declaration is necessary for interface definitions, complex logic that exceeds the compiler’s inference capabilities, or ensuring strict API stability.

// TS 5.5+: The compiler automatically infers 'val is string' based on the body.
function checkIsString(val: unknown) {
    return typeof val === "string";
}

// Explicit type predicate enforces the narrowing contract in the signature.
function verifyIsString(val: unknown): val is string {
    return typeof val === "string";
}

Class Context (this is Type)

In object-oriented patterns, the is operator can be applied to the this context of a class or interface method. This allows instance methods to narrow the type of the class instance itself within the caller’s scope.

interface Animal {
    name: string;
    isBird(): this is Bird;
}

interface Bird extends Animal {
    fly(): void;
}

Type Safety and Assertions

Explicit type predicates (parameterName is Type) are intentionally unchecked by the TypeScript compiler. They act as unsafe type assertions, meaning the compiler trusts the developer’s explicit annotation regardless of the function’s internal logic. If the function body’s implementation does not strictly guarantee the narrowed type, the compiler will not emit a type error. The responsibility lies entirely with the developer to ensure that the runtime boolean logic accurately reflects the compile-time type assertion to prevent type unsafety.

Master TypeScript with Deep Grasping Methodology!

Learn More