Classes

when comparing types that have private and protected members, we treat these types differently. For two types to be considered compatible, if one of them has a private member, then the other must have a private member that originated in the same declaration. The same applies to protected members.

TypeScript accessibility modifiers like public or private can’t be used on private fields.

When it comes to properties, TypeScript’s private modifiers are fully erased – that means that while the data will be there, nothing is encoded in your JavaScript output about how the property was declared. At runtime, it acts entirely like a normal property. That means that when using the private keyword, privacy is only enforced at compile-time/design-time, and for JavaScript consumers, it’s entirely intent-based.

Parameter properties

class Octopus {
  readonly numberOfLegs: number = 8;
  constructor(readonly name: string) {}
}
let dad = new Octopus("Man with the 8 strong legs");
dad.name;

Abstract class

Using a class as an interface

A class declaration creates two things: a type representing instances of the class and a constructor function. Because classes create types, you can use them in the same places you would be able to use interfaces.

Enums

Enums are one of the few features TypeScript has which is not a type-level extension of JavaScript. TypeScript provides both numeric and string-based enums.

While string enums don’t have auto-incrementing behavior, string enums have the benefit that they “serialize” well.

Technically enums can be mixed with string and numeric members, but it’s not clear why you would ever want to do so

Union enums and enum member types

Generics

Generic function

interface GenericIdentityFn<T> {
  (arg: T): T;
}
function identity<T>(arg: T): T {
  return arg;
}
let myIdentity: GenericIdentityFn<number> = identity;

Generic types (interfaces)

interface GenericIdentityFn {
  <T>(arg: T): T;
}
function identity<T>(arg: T): T {
  return arg;
}
let myIdentity: GenericIdentityFn = identity;

Generic Classes

As we covered in our section on classes, a class has two sides to its type: the static side and the instance side. Generic classes are only generic over their instance side rather than their static side, so when working with classes, static members can not use the class’s type parameter.

Generic Contrains

Advanced Types

Type Guards and Differentiating Types

As we mentioned, you can only access members that are guaranteed to be in all the constituents of a union type.

let pet = getSmallPet();
// You can use the 'in' operator to check
if ("swim" in pet) {
  pet.swim();
}
// However, you cannot use property access
if (pet.fly) {
}

To get the same code working via property accessors, we’ll need to use a type assertion:

let pet = getSmallPet();
let fishPet = pet as Fish;
let birdPet = pet as Bird;
if (fishPet.swim) {
  fishPet.swim();
} else if (birdPet.fly) {
  birdPet.fly();
}

User-Defined Type Guards

It just so happens that TypeScript has something called a type guard. A type guard is some expression that performs a runtime check that guarantees the type in some scope.

To define a type guard, we simply need to define a function whose return type is a type predicate:

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

pet is Fish is our type predicate in this example. A predicate takes the form parameterName is Type , where parameterName must be the name of a parameter from the current function signature.

Any time isFish is called with some variable, TypeScript will narrow that variable to that specific type if the original type is compatible.

// Both calls to 'swim' and 'fly' are now okay.
let pet = getSmallPet();
if (isFish(pet)) {
  pet.swim();
} else {
  pet.fly();
}

Notice that TypeScript not only knows that pet is a Fish in the if branch; it also knows that in the else branch, you don’t have a Fish, so you must have a Bird.

Using the in operator

The in operator also acts as a narrowing expression for types.
For a n in x expression, where n is a string literal or string literal type and x is a union type, the “true” branch narrows to types which have an optional or required property n, and the “false” branch narrows to types which have an optional or missing property n.

function move(pet: Fish | Bird) {
  if ("swim" in pet) {
    return pet.swim();
  }
  return pet.fly();
}

typeof and instanceof type guards

function padLeft(value: string, padding: string | number) {
  if (typeof padding === "number") {
    return Array(padding + 1).join(" ") + value;
  }
  if (typeof padding === "string") {
    return padding + value;
  }
  throw new Error(`Expected string or number, got '${padding}'.`);
}

These typeof type guards are recognized in two different forms: typeof v === "typename" and typeof v !== "typename", where "typename" must be "number", "string", "boolean", or "symbol". While TypeScript won’t stop you from comparing to other strings, the language won’t recognize those expressions as type guards.

interface Padder {
  getPaddingString(): string;
}
class SpaceRepeatingPadder implements Padder {
  constructor(private numSpaces: number) {}
  getPaddingString() {
    return Array(this.numSpaces + 1).join(" ");
  }
}
class StringPadder implements Padder {
  constructor(private value: string) {}
  getPaddingString() {
    return this.value;
  }
}
function getRandomPadder() {
  return Math.random() < 0.5
    ? new SpaceRepeatingPadder(4)
    : new StringPadder("  ");
}
let padder: Padder = getRandomPadder();
//       ^ = let padder: Padder
if (padder instanceof SpaceRepeatingPadder) {
  padder;
//       ^ = Could not get LSP result: er;>
<  /
}
if (padder instanceof StringPadder) {
  padder;
//       ^ = Could not get LSP result: er;>
<  /
}

The right side of the instanceof needs to be a constructor function, and TypeScript will narrow down to:

• the type of the function’s prototype property if its type is not any
• the union of types returned by that type’s construct signatures

in that order.

Nullable Types

By default, the type checker considers null and undefined assignable to anything. Effectively, null and undefined are valid values of every type. That means it’s not possible to stop them from being assigned to any type, even when you would like to prevent it.

The --strictNullChecks flag fixes this: when you declare a variable, it doesn’t automatically include null or undefined. You can include them explicitly using a union type

With --strictNullChecks , an optional parameter automatically adds | undefined:

function f(x: number, y?: number) {
  return x + (y ?? 0);
}
f(1, 2);
f(1);
f(1, undefined); // ok
f(1, null); // error

The same is true for optional properties.

In cases where the compiler can’t eliminate null or undefined, you can use the type assertion operator to manually remove them. The syntax is postfix !: identifier! removes null and undefined from the type of identifier

interface UserAccount {
  id: number;
  email?: string;
}
const user = getUser("admin");
user.id;
Object is possibly 'undefined'.
if (user) {
  user.email.length;
Object is possibly 'undefined'.
}
// Instead if you are sure that these objects or fields exist, the
// postfix ! lets you short circuit the nullability
user!.email!.length;

Type Alias

Type aliases create a new name for a type. Type aliases are sometimes similar to interfaces, but can name primitives, unions, tuples, and any other types that you’d otherwise have to write by hand

Aliasing doesn’t actually create a new type - it creates a new name to refer to that type.

Just like interfaces, type aliases can also be generic - we can just add type parameters and use them on the right side of the alias declaration.

type Container<T> = { value: T };

We can also have a type alias refer to itself in a property:

type Tree<T> = {
  value: T;
  left?: Tree<T>;
  right?: Tree<T>;
};
type LinkedList<Type> = Type & { next: LinkedList<Type> };

Almost all features of an interface are available in type, the key distinction is that a type cannot be re-opened to add new properties vs a interface which is always extendable. As a workaround, you can extend a type via intersections.

interface Window {
  title: string
}
interface Window {
  ts: import("typescript")
}
const src = 'const a = "Hello World"';
window.ts.transpileModule(src, {});
// a type can't be changed after created

Because an interface more closely maps how JavaScript object work by being open to extension, we recommend using an interface over a type alias when possible.

On the other hand, if you can’t express some shape with an interface and you need to use a union or tuple type, type aliases are usually the way to go.

Enum member types

As mentioned in our section on enums, enum members have types when every member is literal-initialized.

Much of the time when we talk about “singleton types”, we’re referring to both enum member types as well as numeric/string literal types, though many users will use “singleton types” and “literal types” interchangeably.

Polymorphic this types

A polymorphic this type represents a type that is the subtype of the containing class or interface.

Index Types

function pluck<T, K extends keyof T>(o: T, propertyNames: K[]): T[K][] {
  return propertyNames.map((n) => o[n]);
}
interface Car {
  manufacturer: string;
  model: string;
  year: number;
}
let taxi: Car = {
  manufacturer: "Toyota",
  model: "Camry",
  year: 2014,
};
// Manufacturer and model are both of type string,
// so we can pluck them both into a typed string array
let makeAndModel: string[] = pluck(taxi, ["manufacturer", "model"]);
// If we try to pluck model and year, we get an
// array of a union type: (string | number)[]
let modelYear = pluck(taxi, ["model", "year"]);

The compiler checks that manufacturer and model are actually properties on Car. The example introduces a couple of new type operators. First is keyof T, the index type query operator. For any type T, keyof T is the union of known, public property names of T. For example:

let carProps: keyof Car;
//         ^ = let carProps: "manufacturer" | "model" | "year"

The second operator is T[K], the indexed access operator.

Index types and index signatures

keyof and T[K] interact with index signatures. An index signature parameter type must be ‘string’ or ‘number’. If you have a type with a string index signature, keyof T will be string | number

interface Dictionary<T> {
  [key: string]: T;
}
let keys: keyof Dictionary<number>;
//     ^ = let keys: string | number
let value: Dictionary<number>["foo"];
//      ^ = let value: number

If you have a type with a number index signature, keyof T will just be number.

Mapped types

In a mapped type, the new type transforms each property in the old type in the same way.

type Partial<T> = {
  [P in keyof T]?: T[P];
};
type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};

Note that this syntax describes a type rather than a member. If you want to add members, you can use an intersection type:

// Use this:
type PartialWithNewMember<T> = {
  [P in keyof T]?: T[P];
} & { newMember: boolean }
// This is an error!
type WrongPartialWithNewMember<T> = {
  [P in keyof T]?: T[P];
  newMember: boolean;
}

Let’s take a look at the simplest mapped type and its parts:

type Keys = "option1" | "option2";
type Flags = { [K in Keys]: boolean };
// is equivalent to 
type Flags = {
  option1: boolean;
  option2: boolean;
};

type Nullable<T> = { [P in keyof T]: T[P] | null };
type Partial<T> = { [P in keyof T]?: T[P] };

Note that Readonly<T> and Partial<T> are so useful, they are included in TypeScript’s standard library along with Pick and Record:

type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};
type Record<K extends keyof any, T> = {
  [P in K]: T;
};

Readonly, Partial and Pick are homomorphic whereas Record is not. One clue that Record is not homomorphic is that it doesn’t take an input type to copy properties from.
Note that keyof any represents the type of any value that can be used as an index to an object. In otherwords, keyof any is currently equal to string | number | symbol.

Inference from mapped types

Now that you know how to wrap the properties of a type, the next thing you’ll want to do is unwrap them. Fortunately, that’s pretty easy:

function unproxify<T>(t: Proxify<T>): T {
  let result = {} as T;
  for (const k in t) {
    result[k] = t[k].get();
  }
  return result;
}
let originalProps = unproxify(proxyProps);
//  ^ = let originalProps: {
    rooms: number;
}

Conditional Types

A conditional type selects one of two possible types based on a condition expressed as a type relationship test:

T extends U ? X : Y

The type above means when T is assignable to U the type is X, otherwise the type is Y.

A conditional type T extends U ? X : Y is either resolved to X or Y, or deferred because the condition depends on one or more type variables. When T or U contains type variables, whether to resolve to X or Y, or to defer, is determined by whether or not the type system has enough information to conclude that T is always assignable to U.

Utility Types

Partial<Type>
Readonly<Type>
Record<Keys, Type>
Pick<Type, Keys>
Omit<Type, Keys>
Exclude<Type, ExcludedUnion>
Extract<Type, Union>
NonNullable<Type>
Parameters<Type>
ConstructorParameters<Type>
ReturnType<Type>
InstanceType<Type>
Required<Type>
ThisParameterType<Type>
OmitThisParameter<Type>
ThisType<Type>