.TS File Format – Types

Annotations

A type follows a name after a colon. Annotations are optional wherever the compiler can work the type out, and a name with no annotation and no way to infer it is an error under noImplicitAny.

VariableDeclaration:  Name [!] [: Type] [= Expression]
Type:                 PrimitiveName | TypeReference | ObjectType | ArrayType | TupleType
                      | LiteralType | FunctionType | ConstructorType
                      | UnionType | IntersectionType | KeyofType | TypeofType
                      | IndexedAccessType | ConditionalType | MappedType
                      | TemplateLiteralType | ( Type )

let count: number = 1;
let name = "Ada";              // string, inferred
function double(n: number): number { return n * 2; }

Primitive types

The capitalised names String, Number, Boolean and so on are the wrapper object types. A primitive can be assigned to one, but not the other way round, so the lower-case names are the ones to use.

Without strictNullChecks, null and undefined can be assigned to every type.

Special types

let a: any = 1;
a.foo.bar();                 // no error, and a crash at run time

let u: unknown = "x";
u.toUpperCase();             // error
if (typeof u === "string") {
  u.toUpperCase();           // fine
}

function fail(message: string): never {
  throw new Error(message);
}

type Callback = () => void;
const cb: Callback = () => 42;       // fine: the result is ignored

function nothing(): void {
  return 42;                         // error
}

void behaves differently depending on where it appears. A function declared with void as its own return type may not return a value, but a function type returning void accepts functions that return anything, and the caller just ignores the result. Since 5.1 a function declared to return undefined needs no return statement.

In unions and intersections, never disappears from a union and unknown disappears from an intersection, while unknown absorbs a union and never absorbs an intersection. any absorbs both.

Object types

An object type lists members, separated by semicolons, commas or line breaks. It is written inline or named with type or interface.

ObjectType:   { {Member (; | , | newline)} }
Member:       [readonly] Name [?] : Type
              | Name [?] ( Parameters ) [: Type]
              | ( Parameters ) : Type
              | new ( Parameters ) : Type
              | [readonly] [ Name : KeyType ] : Type
              | get Name ( ) : Type
              | set Name ( Name : Type )

interface Point {
  readonly x: number;
  y?: number;
}

const p: Point = { x: 1 };
p.x = 2;                    // error: read-only

interface Mutable { x: number }
const m: Mutable = p;       // allowed: readonly is not checked here
m.x = 2;                    // and this changes p

interface Scores {
  [name: string]: number;
  length: number;             // must match the string signature
}

interface Bad {
  [key: string]: number;
  name: string;               // error: string is not assignable to number
}

interface Mixed {
  [index: number]: string;    // numeric keys must fit the string signature
  [key: string]: string | number;
}

interface Attributes {
  [attribute: `data-${string}`]: string;
}

interface Options { port: number }

const a: Options = { port: 80, host: "x" };  // error: host is unknown

const value = { port: 80, host: "x" };
const b: Options = value;                    // fine

Arrays

T[] and Array<T> are the same type. readonly T[] and ReadonlyArray<T> have no mutating methods. A mutable array can be assigned to a read-only array, but not the reverse.

const list: number[] = [1, 2];
const view: readonly number[] = list;
view.push(3);                   // error
const back: number[] = view;    // error

const mixed = [1, "a"];         // (string | number)[]

Tuples

A tuple is an array of a known length, with a type for each position. Each element may be optional or a rest element, and each may have a label for readability. Labels do not affect the type.

TupleType:     [readonly] [ [Element {, Element}] ]
Element:       [Label :] Type [?]  |  [Label :] ... Type

Optional elements cannot come before required ones, and a tuple may have only one rest element. A tuple can be spread into another with ...T.

Literal types

A literal can be used as a type containing just that value: strings, numbers, negative numbers, BigInts and true or false. A union of them makes an enumeration of allowed values.

type Align = "left" | "right" | "centre";
type Bit = 0 | 1;
type Sign = -1 | 1;
type Big = 10n;

let a = "x";       // string: a let can change
const b = "x";     // "x": a const cannot

const o = { k: "x" };         // { k: string }
const c = { k: "x" } as const; // { readonly k: "x" }

This is called widening. A let, a parameter or a property initialised from a literal gets the general type, and a const keeps the literal. To keep the literal, use as const, or an annotation.

A variable with no annotation and no initialiser starts as any, and the compiler then tracks each assignment. let a; followed by a = 1 makes a a number until the next assignment. An empty array literal does the same, and its element type grows with each push.

Structural typing

TypeScript compares types by their shape, not by name or by where they were declared. A value fits a type if it has the members that type requires, and may have others (Handbook: Type Compatibility).

class Cat { name = "Tom" }
class Ship { name = "Queen Mary" }

const c: Cat = new Ship();    // fine: the shapes match

class Vault { private code = 1 }
class Safe  { private code = 1 }

const v: Vault = new Safe();  // error: private members come from different classes

interface Animal { name: string }
interface Dog extends Animal { bark(): void }

type WithProperty = { handle: (a: Animal) => void };
type WithMethod   = { handle(a: Animal): void };

const dogHandler = { handle: (d: Dog) => {} };

const p: WithProperty = dogHandler;  // error under strictFunctionTypes
const m: WithMethod   = dogHandler;  // allowed: methods are bivariant