> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript 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.
```typescript theme={"dark"}
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.
```typescript theme={"dark"}
// 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.
```typescript theme={"dark"}
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.
Tired of Poor TypeScript Skills? Fix That With Deep Grasping!
Learn More
