3.2 Primitive Types

The primitive types are the Number, Boolean, String, Symbol, Void, Null, and Undefined types and all user defined enum types.

3.2.1 The Number Type

The Number primitive type corresponds to the similarly named JavaScript primitive type and represents double-precision 64-bit format IEEE 754 floating point values.

The number keyword references the Number primitive type and numeric literals may be used to write values of the Number primitive type.

For purposes of determining type relationships (section 3.11) and accessing properties (section 4.13), the Number primitive type behaves as an object type with the same properties as the global interface type ‘Number’.

Some examples:

var x: number;          // Explicitly typed  
var y = 0;              // Same as y: number = 0  
var z = 123.456;        // Same as z: number = 123.456  
var s = z.toFixed(2);   // Property of Number interface

3.2.2 The Boolean Type

The Boolean primitive type corresponds to the similarly named JavaScript primitive type and represents logical values that are either true or false.

The boolean keyword references the Boolean primitive type and the true and false literals reference the two Boolean truth values.

For purposes of determining type relationships (section 3.11) and accessing properties (section 4.13), the Boolean primitive type behaves as an object type with the same properties as the global interface type ‘Boolean’.

Some examples:

var b: boolean;         // Explicitly typed  
var yes = true;         // Same as yes: boolean = true  
var no = false;         // Same as no: boolean = false

3.2.3 The String Type

The String primitive type corresponds to the similarly named JavaScript primitive type and represents sequences of characters stored as Unicode UTF-16 code units.

The string keyword references the String primitive type and string literals may be used to write values of the String primitive type.

For purposes of determining type relationships (section 3.11) and accessing properties (section 4.13), the String primitive type behaves as an object type with the same properties as the global interface type ‘String’.

Some examples:

var s: string;          // Explicitly typed  
var empty = "";         // Same as empty: string = ""  
var abc = 'abc';        // Same as abc: string = "abc"  
var c = abc.charAt(2);  // Property of String interface

3.2.4 The Symbol Type

The Symbol primitive type corresponds to the similarly named JavaScript primitive type and represents unique tokens that may be used as keys for object properties.

The symbol keyword references the Symbol primitive type. Symbol values are obtained using the global object ‘Symbol’ which has a number of methods and properties and can be invoked as a function. In particular, the global object ‘Symbol’ defines a number of well-known symbols (2.2.3) that can be used in a manner similar to identifiers. Note that the ‘Symbol’ object is available only in ECMAScript 2015 environments.

For purposes of determining type relationships (section 3.11) and accessing properties (section 4.13), the Symbol primitive type behaves as an object type with the same properties as the global interface type ‘Symbol’.

Some examples:

var secretKey = Symbol();  
var obj = {};  
obj[secretKey] = "secret message";  // Use symbol as property key  
obj[Symbol.toStringTag] = "test";   // Use of well-known symbol

3.2.5 The Void Type

The Void type, referenced by the void keyword, represents the absence of a value and is used as the return type of functions with no return value.

The only possible values for the Void type are null and undefined. The Void type is a subtype of the Any type and a supertype of the Null and Undefined types, but otherwise Void is unrelated to all other types.

NOTE: We might consider disallowing declaring variables of type Void as they serve no useful purpose. However, because Void is permitted as a type argument to a generic type or function it is not feasible to disallow Void properties or parameters.

3.2.6 The Null Type

The Null type corresponds to the similarly named JavaScript primitive type and is the type of the null literal.

The null literal references the one and only value of the Null type. It is not possible to directly reference the Null type itself.

The Null type is a subtype of all types, except the Undefined type. This means that null is considered a valid value for all primitive types, object types, union types, intersection types, and type parameters, including even the Number and Boolean primitive types.

Some examples:

var n: number = null;   // Primitives can be null  
var x = null;           // Same as x: any = null  
var e: Null;            // Error, can't reference Null type

3.2.7 The Undefined Type

The Undefined type corresponds to the similarly named JavaScript primitive type and is the type of the undefined literal.

The undefined literal denotes the value given to all uninitialized variables and is the one and only value of the Undefined type. It is not possible to directly reference the Undefined type itself.

The undefined type is a subtype of all types. This means that undefined is considered a valid value for all primitive types, object types, union types, intersection types, and type parameters.

Some examples:

var n: number;          // Same as n: number = undefined  
var x = undefined;      // Same as x: any = undefined  
var e: Undefined;       // Error, can't reference Undefined type

3.2.8 Enum Types

Enum types are distinct user defined subtypes of the Number primitive type. Enum types are declared using enum declarations (section 9.1) and referenced using type references (section 3.8.2).

Enum types are assignable to the Number primitive type, and vice versa, but different enum types are not assignable to each other.

3.2.9 String Literal Types

Specialized signatures (section 3.9.2.4) permit string literals to be used as types in parameter type annotations. String literal types are permitted only in that context and nowhere else.

All string literal types are subtypes of the String primitive type.

TODO: Update to reflect expanded support for string literal types.