Type assertions are not explained (despite being used)

[mcclure]

Tonight I looked at the Typescript handbook (it was linked on typescriptlang.org). I was specifically wanting to understand the meaning of a piece of code I had found on StackOverflow: var canvas = <HTMLCanvasElement> document.getElementById("mycanvas");

When I looked in the handbook-- the only piece of user-facing documentation for Typescript right now, it looks like-- I found the angle brackets were not documented. Weirder, very early in the handbook, the angle brackets are used. However they are not at that point explained. I want to highlight the code:

interface Shape {
    color: string;
}

interface Square extends Shape {
    sideLength: number;
}

let square = <Square>{};
square.color = "blue";
square.sideLength = 10;

The <> is obviously some kind of cast operator. However, after looking at this code I have many questions:

• Does <> merely type-check? Or does it coerce (convert)?
• Is <> safe? What happens if the conversion is illegal?
• Can I use <> on "primitive" types such as number and string?

A friend helped me find section 4.16 of the spec (which is hard to find because it is named "type assertions", not something familiar like "casting"), which sort of explains <>, but I am still a little confused. This really should be explained in the handbook.

I think when you drop the above code in, since it is the first use of the <> construct, you should take the time to explain it. I think it is especially important to explain it because this code seems to do something "funny". That is, it looks to me like that code is doing something illegal. let square:Square = {}; is not legal, because color and sideLength are non-optional. But the allows it to occur, even though it is unsafe and code using could throw an exception. If explained correctly, this helps the user understand an important element of writing Typescript (that <>s violate the typesystem and make your program unsafe). However if not explained, it could (1) teach readers of the handbook bad practice-- since you're flat out instructing them in a pattern which subverts the typesystem; and (2) create confusion when reading other parts of the guide (I had trouble understanding the "optional types" section when I read it because I had first read this bit of early sample code where two non-optional types are not specified).

[DanielRosenwasser]

Thanks for the heads up @mcclure, we should definitely add a section for this. We're currently amending the handbook.

[mcclure]

Thanks

[mhegazy]

@mcclure you might microsoft/TypeScript#5853 has some explanation until we have the new topic added.

[DanielRosenwasser]

This should be up when the docs on the site get updated.