Rules for the use of angle brackets in TypeScript

Question

What are the general rules that dictate when, where, how and why angle brackets, i.e. <...>, should be used in TypeScript?

While I think I understand many individual uses of these brackets, I have a hard time seeing general patterns for their use: they sometimes seem to be prepended before things, sometimes appended after things; sometimes they are used for generics, sometimes for specific types; sometimes they appear where I might have expected the colon syntax to be used.

I'd like to have a concise but exhaustive/universal explanation of what the brackets mean, their exact syntax, when they should be used, when they shouldn't be used, etc.

Answer 1

With questions like this, I'd recommend reading the spec, especially the Grammar section. Syntax like < something > is used in

1. Type Parameters

   • Defined as < TypeParameterList > in section 3.6.1

   • Used with declarations and call signatures of classes, interfaces, functions and more

     function heat<T>(food: T): T { return food; }           //^^^^^ Type parameter list  class Pizza<T, E extends Cheese> { toppingA: T; toppingB: E }          //^^^^^^^^^^^^^^^^^^^^ Type parameter list 

2. Type Arguments

   • Defined as < TypeArgumentList > in section 3.6.2

   • Used with references to generic types and calls to generic functions

     var pizza: Pizza<Pepperoni, Mozzarella>;                //^^^^^^^^^^^^^^^^^^^^^^ Type argument list pizza = heat<{ toppingA: Pepperoni, toppingB: Mozzarella}>(ingredients)             //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type argument list 

     Update 2018-07-01: As of version 2.9, generic type arguments can also be used in JSX elements and tagged templates.

      <MenuItem<Pizza> toppings={[Pepperoni, Mozzarella]} />         //^^^^^^^ Type argument list   const ratingHtml = escapeUserInput<string | number> `Customer ${feedback.customer.username} rated this pizza with <b>${feedback.rating}</b>/10!`                                   //^^^^^^^^^^^^^^^^ Type argument list 

3. Type Assertions

   • Defined and used as < Type > UnaryExpression where UnaryExpression comes from EcmaScript standard in section 4.16

     var ingredients = {     toppingA: new Pepperoni,     toppingB: <Mozzarella> fridge.takeSomeCheese()             //^^^^^^^^^^^^ Type assertion }; 

4. JSX expressions (when enabled)

   • Not documented in the spec, but should follow the the syntax of JSX, which is basically an expression like

     <JSXElementName JSXAttributes(optional)> JSXChildren(optional) </JSXElementName> 

     or

     <JSXElementName JSXAttributes(optional) />