4.24 Type Guards

Type guards are particular expression patterns involving the ‘typeof’ and ‘instanceof’ operators that cause the types of variables or parameters to be narrowed to more specific types. For example, in the code below, knowledge of the static type of ‘x’ in combination with a ‘typeof’ check makes it safe to narrow the type of ‘x’ to string in the first branch of the ‘if’ statement and number in the second branch of the ‘if’ statement.

function foo(x: number | string) {  
    if (typeof x === "string") {  
        return x.length;  // x has type string here  
    }  
    else {  
        return x + 1;     // x has type number here  
    }  
}

The type of a variable or parameter is narrowed in the following situations:

• In the true branch statement of an ‘if’ statement, the type of a variable or parameter is narrowed by a type guard in the ‘if’ condition when true, provided no part of the ‘if’ statement contains assignments to the variable or parameter.
• In the false branch statement of an ‘if’ statement, the type of a variable or parameter is narrowed by a type guard in the ‘if’ condition when false, provided no part of the ‘if’ statement contains assignments to the variable or parameter.
• In the true expression of a conditional expression, the type of a variable or parameter is narrowed by a type guard in the condition when true, provided no part of the conditional expression contains assignments to the variable or parameter.
• In the false expression of a conditional expression, the type of a variable or parameter is narrowed by a type guard in the condition when false, provided no part of the conditional expression contains assignments to the variable or parameter.
• In the right operand of a && operation, the type of a variable or parameter is narrowed by a type guard in the left operand when true, provided neither operand contains assignments to the variable or parameter.
• In the right operand of a || operation, the type of a variable or parameter is narrowed by a type guard in the left operand when false, provided neither operand contains assignments to the variable or parameter.

A type guard is simply an expression that follows a particular pattern. The process of narrowing the type of a variable x by a type guard when true or when false depends on the type guard as follows:

• A type guard of the form x instanceof C, where x is not of type Any, C is of a subtype of the global type ‘Function’, and C has a property named ‘prototype’
  • when true, narrows the type of x to the type of the ‘prototype’ property in C provided it is a subtype of the type of x, or, if the type of x is a union type, removes from the type of x all constituent types that aren’t subtypes of the type of the ‘prototype’ property in C, or
  • when false, has no effect on the type of x.
• A type guard of the form typeof x === s, where s is a string literal with the value ‘string’, ‘number’, or ‘boolean’,
  • when true, narrows the type of x to the given primitive type provided it is a subtype of the type of x, or, if the type of x is a union type, removes from the type of x all constituent types that aren’t subtypes of the given primitive type, or
  • when false, removes the primitive type from the type of x.
• A type guard of the form typeof x === s, where s is a string literal with any value but ‘string’, ‘number’, or ‘boolean’,
  • when true, if x is a union type, removes from the type of x all constituent types that are subtypes of the string, number, or boolean primitive type, or
  • when false, has no effect on the type of x.
• A type guard of the form typeof x !== s, where s is a string literal,
  • when true, narrows the type of x by typeof x === s when false, or
  • when false, narrows the type of x by typeof x === s when true.
• A type guard of the form !expr
  • when true, narrows the type of x by expr when false, or
  • when false, narrows the type of x by expr when true.
• A type guard of the form expr1 && expr2
  • when true, narrows the type of x by expr₁ when true and then by expr₂ when true, or
  • when false, narrows the type of x to T₁ | T₂, where T₁ is the type of x narrowed by expr₁ when false, and T₂ is the type of x narrowed by expr₁ when true and then by expr₂ when false.
• A type guard of the form expr1 || expr2
  • when true, narrows the type of x to T₁ | T₂, where T₁ is the type of x narrowed by expr₁ when true, and T₂ is the type of x narrowed by expr₁ when false and then by expr₂ when true, or
  • when false, narrows the type of x by expr₁ when false and then by expr₂ when false.
• A type guard of any other form has no effect on the type of x.

In the rules above, when a narrowing operation would remove all constituent types from a union type, the operation has no effect on the union type.

Note that type guards affect types of variables and parameters only and have no effect on members of objects such as properties. Also note that it is possible to defeat a type guard by calling a function that changes the type of the guarded variable.

TODO: Document user defined type guard functions.

In the example

function isLongString(obj: any) {  
    return typeof obj === "string" && obj.length > 100;  
}

the obj parameter has type string in the right operand of the && operator.

In the example

function processValue(value: number | (() => number)) {  
    var x = typeof value !== "number" ? value() : value;  
    // Process number in x  
}

the value parameter has type () => number in the first conditional expression and type number in the second conditional expression, and the inferred type of x is number.

In the example

function f(x: string | number | boolean) {  
    if (typeof x === "string" || typeof x === "number") {  
        var y = x;  // Type of y is string | number  
    }  
    else {  
        var z = x;  // Type of z is boolean  
    }  
}

the type of x is string | number | boolean in the left operand of the || operator, number | boolean in the right operand of the || operator, string | number in the first branch of the if statement, and boolean in the second branch of the if statement.

In the example

class C {  
    data: string | string[];  
    getData() {  
        var data = this.data;  
        return typeof data === "string" ? data : data.join(" ");  
    }  
}

the type of the data variable is string in the first conditional expression and string[] in the second conditional expression, and the inferred type of getData is string. Note that the data property must be copied to a local variable for the type guard to have an effect.

In the example

class NamedItem {  
    name: string;  
}
function getName(obj: Object) {  
    return obj instanceof NamedItem ? obj.name : "unknown";  
}

the type of obj is narrowed to NamedItem in the first conditional expression, and the inferred type of the getName function is string.