Type Operators for Object Types

Remember union (|) and intersection (&), the two type operators I introduced in “Union and intersection types”? It turns out they’re not the only type operators TypeScript gives you! Let’s run through a few more type operators that come in handy for working with shapes.

type APIResponse = {
  user: {
    userId: string
    friendList: {
      count: number
      friends: {
        firstName: string
        lastName: string
      }[]
    }
  }
}

function getAPIResponse(): Promise<APIResponse> {
  // ...
}

function renderFriendList(friendList: unknown) {
  // ...
}

let response = await getAPIResponse()
renderFriendList(response.user.friendList)

type FriendList = {
  count: number
  friends: {
    firstName: string
    lastName: string
  }[]
}

type APIResponse = {
  user: {
    userId: string
    friendList: FriendList
  }
}

function renderFriendList(friendList: FriendList) {
  // ...
}

type APIResponse = {
  user: {
    userId: string
    friendList: {
      count: number
      friends: {
        firstName: string
        lastName: string
      }[]
    }
  }
}

type FriendList = APIResponse['user']['friendList']

function renderFriendList(friendList: FriendList) {
  // ...
}

type Friend = FriendList['friends'][number]

type ResponseKeys = keyof APIResponse // 'user'
type UserKeys = keyof APIResponse['user'] // 'userId' | 'friendList'
type FriendListKeys =
  keyof APIResponse['user']['friendList'] // 'count' | 'friends'

function get< 
  O extends object,
  K extends keyof O 
>(
  o: O,
  k: K
): O[K] { 
  return o[k]
}

type ActivityLog = {
  lastEvent: Date
  events: {
    id: string
    timestamp: Date
    type: 'Read' | 'Write'
  }[]
}

let activityLog: ActivityLog = // ...
let lastEvent = get(activityLog, 'lastEvent') // Date

type Get = { 
  <
    O extends object,
    K1 extends keyof O
  >(o: O, k1: K1): O[K1] 
  <
    O extends object,
    K1 extends keyof O,
    K2 extends keyof O[K1] 
  >(o: O, k1: K1, k2: K2): O[K1][K2] 
  <
    O extends object,
    K1 extends keyof O,
    K2 extends keyof O[K1],
    K3 extends keyof O[K1][K2]
  >(o: O, k1: K1, k2: K2, k3: K3): O[K1][K2][K3] 
}

let get: Get = (object: any, ...keys: string[]) => {
  let result = object
  keys.forEach(k => result = result[k])
  return result
}

get(activityLog, 'events', 0, 'type') // 'Read' | 'Write'


get(activityLog, 'bad') // Error TS2345: Argument of type '"bad"'
                        // is not assignable to parameter of type
                        // '"lastEvent" | "events"'.

The Record Type

TypeScript’s built-in Record type is a way to describe an object as a map from something to something.

Recall from the Weekday example in “Totality” that there are two ways to enforce that an object defines a specific set of keys. Record types are the first.

Let’s use Record to build a map from each day of the week to the next day of the week. With Record, you can put some constraints on the keys and values in nextDay:

type Weekday = 'Mon' | 'Tue'| 'Wed' | 'Thu' | 'Fri'
type Day = Weekday | 'Sat' | 'Sun'

let nextDay: Record<Weekday, Day> = {
  Mon: 'Tue'
}

Now, you get a nice, helpful error message right away:

Error TS2739: Type '{Mon: "Tue"}' is missing the following properties
from type 'Record<Weekday, Day>': Tue, Wed, Thu, Fri.

Adding the missing Weekdays to your object, of course, makes the error go away.

Record gives you one extra degree of freedom compared to regular object index signatures: with a regular index signature you can constrain the types of an object’s values, but the key can only be a regular string, number, or symbol; with Record, you can also constrain the types of an object’s keys to subtypes of string and number.

Mapped Types

TypeScript gives us a second, more powerful way to declare a safer nextDay type: mapped types. Let’s use mapped types to say that nextDay is an object with a key for each Weekday, whose value is a Day:

let nextDay: {[K in Weekday]: Day} = {
  Mon: 'Tue'
}

This is another way to get a helpful hint for how to fix what you missed:

Error TS2739: Type '{Mon: "Tue"}' is missing the following properties
from type '{Mon: Weekday; Tue: Weekday; Wed: Weekday; Thu: Weekday;
Fri: Weekday}': Tue, Wed, Thu, Fri.

Mapped types are a language feature unique to TypeScript. Like literal types, they’re a utility feature that just makes sense for the challenge that is statically typing JavaScript.

As you saw, mapped types have their own special syntax. And like index signatures, you can have at most one mapped type per object:

type MyMappedType = {
  [Key in UnionType]: ValueType
}

As the name implies, it’s a way to map over an object’s key and value types. In fact, TypeScript uses mapped types to implement its built-in Record type we used earlier:

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

Mapped types give you more power than a mere Record because in addition to letting you give types to an object’s keys and values, when you combine them with keyed-in types, they let you put constraints on which value type corresponds to which key name.

Let’s quickly run through some of the things you can do with mapped types.

type Account = {
  id: number
  isEmployee: boolean
  notes: string[]
}

// Make all fields optional
type OptionalAccount = {
  [K in keyof Account]?: Account[K] 
}

// Make all fields nullable
type NullableAccount = {
  [K in keyof Account]: Account[K] | null 
}

// Make all fields read-only
type ReadonlyAccount = {
  readonly [K in keyof Account]: Account[K] 
}

// Make all fields writable again (equivalent to Account)
type Account2 = {
  -readonly [K in keyof ReadonlyAccount]: Account[K] 
}

// Make all fields required again (equivalent to Account)
type Account3 = {
  [K in keyof OptionalAccount]-?: Account[K] 
}

We create a new object type OptionalAccount by mapping over Account, marking each field as optional along the way.

We create a new object type NullableAccount by mapping over Account, adding null as a possible value for each field along the way.

We create a new object type ReadonlyAccount by taking Account and making each of its fields read-only (that is, readable but not writable).

We can mark fields as optional (?) or readonly, and we can also unmark them. With the minus (–) operator—a special type operator only available with mapped types—we can undo ? and readonly, making fields required and writable again, respectively. Here we create a new object type Account2, equivalent to our Account type, by mapping over ReadonlyAccount and removing the readonly modifier with the minus (–) operator.

We create a new object type Account3, equivalent to our original Account type, by mapping over OptionalAccount and removing the optional (?) operator with the minus (–) operator.

Companion Object Pattern

The companion object pattern comes to us from Scala, and is a way to pair together objects and classes that share the same name. In TypeScript, there’s a similar pattern that’s similarly useful—we’ll also call it the companion object pattern—that we can use to pair together a type and an object.

It looks like this:

type Currency = {
  unit: 'EUR' | 'GBP' | 'JPY' | 'USD'
  value: number
}

let Currency = {
  DEFAULT: 'USD',
  from(value: number, unit = Currency.DEFAULT): Currency {
    return {unit, value}
  }
}

Remember that in TypeScript, types and values live in separate namespaces; you’ll read a little more about this in “Declaration Merging”. That means in the same scope, you can have the same name (in this example, Currency) bound to both a type and a value. With the companion object pattern, we exploit this separate namespacing to declare a name twice: first as a type, then as a value.

This pattern has a few nice properties. It lets you group type and value information that’s semantically part of a single name (like Currency) together. It also lets consumers import both at once:

import {Currency} from './Currency'

let amountDue: Currency = { 
  unit: 'JPY',
  value: 83733.10
}

let otherAmountDue = Currency.from(330, 'EUR') 

Using Currency as a type

Using Currency as a value

Use the companion object pattern when a type and an object are semantically related, with the object providing utility methods that operate on the type.

Improving Type Inference for Tuples

When you declare a tuple in TypeScript, TypeScript will be lenient about inferring that tuple’s type. It will infer the most general possible type based on what you gave it, ignoring the length of your tuple and which position holds which type:

let a = [1, true] // (number | boolean)[]

But sometimes you want inference that’s stricter, that would treat a as a fixed-length tuple and not as an array. You could, of course, use a type assertion to cast your tuple to a tuple type (more on this in “Type Assertions”). Or, you could use an as const assertion (“The const type”) to infer the tuple’s type as narrowly as possible, marking it as read-only.

What if you want to type your tuple as a tuple, but avoid a type assertion, and avoid the narrow inference and read-only modifier that as const gives you? To do that, you can take advantage of the way TypeScript infers types for rest parameters (jump back to “Using bounded polymorphism to model arity” for more about that):

function tuple< 
  T extends unknown[] 
>(
  ...ts: T 
): T { 
  return ts 
}

let a = tuple(1, true) // [number, boolean]

We declare a tuple function that we’ll use to construct tuple types (instead of using the built-in [] syntax).

We declare a single type parameter T that’s a subtype of unknown[] (meaning T is an array of any kind of type).

tuple takes a variable number of parameters, ts. Because T describes a rest parameter, TypeScript will infer a tuple type for it.

tuple returns a value of the same tuple type that it inferred ts as.

Our function returns the same argument that we passed it. The magic is all in the types.

Take advantage of this technique in order to avoid type assertions when your code uses lots of tuple types.

User-Defined Type Guards

For some kinds of boolean-returning functions, simply saying that your function returns a boolean may not be enough. For example, let’s write a function that tells you if you passed it a string or not:

function isString(a: unknown): boolean {
  return typeof a === 'string'
}

isString('a') // evaluates to true
isString([7]) // evaluates to false

So far so good. What happens if you try to use isString in some real-world code?

function parseInput(input: string | number) {
  let formattedInput: string
  if (isString(input)) {
    formattedInput = input.toUpperCase() // Error TS2339: Property 'toUpperCase'
  }                                      // does not exist on type 'number'.
}

What gives? If typeof works for regular type refinement (see “Refinement”), why doesn’t it work here?

The thing about type refinement is it’s only powerful enough to refine the type of a variable in the scope you’re in. As soon as you leave that scope, the refinement doesn’t carry over to whatever new scope you’re in. In our isString implementation, we refined the input parameter’s type to string using typeof, but because type refinement doesn’t carry over to new scopes, it got lost—all TypeScript knows is that isString returned a boolean.

What we can do is tell the typechecker that not only does isString return a boolean, but whenever that boolean is true, the argument we passed to isString is a string. To do that, we use something called a user-defined type guard:

function isString(a: unknown): a is string {
  return typeof a === 'string'
}

Type guards are a built-in TypeScript feature, and are what lets you refine types with typeof and instanceof. But sometimes, you need the ability to declare type guards yourself—that’s what the is operator is for. When you have a function that refines its parameters’ types and returns a boolean, you can use a user-defined type guard to make sure that refinement is flowed whenever you use that function.

User-defined type guards are limited to a single parameter, but they aren’t limited to simple types:

type LegacyDialog = // ...
type Dialog = // ...

function isLegacyDialog(
  dialog: LegacyDialog | Dialog
): dialog is LegacyDialog {
  // ...
}

You won’t use user-defined type guards often, but when you do, they’re awesome for writing clean, reusable code. Without them, you’d have to inline all your typeof and instanceof type guards instead of building functions like isLegacyDialog and isString to perform those same checks in a better-encapsulated, more readable way.

Distributive Conditionals

While you can express simple conditions like the examples we just looked at in a variety of ways in TypeScript—with conditional types, overloaded function signatures, and mapped types—conditional types let you do more. The reason for this is that they follow the distributive law (remember, from algebra class?). That means if you have a conditional type, then the expressions on the right are equivalent to those on the left in Table 6-1.

I know, I know, you didn’t shell out for this book to learn about math—you’re here for the types. So let’s get more concrete. Let’s say we have a function that takes some variable of type T, and lifts it to an array of type T[]. What happens if we pass in a union type for T?

type ToArray<T> = T[]
type A = ToArray<number>          // number[]
type B = ToArray<number | string> // (number | string)[]

Pretty straightforward. Now what happens if we add a conditional type? (Note that the conditional doesn’t actually do anything here because both its branches resolve to the same type T[]; it’s just here to tell TypeScript to distribute T over the tuple type.) Take a look:

type ToArray2<T> = T extends unknown ? T[] : T[]
type A = ToArray2<number> // number[]
type B = ToArray2<number | string> // number[] | string[]

Did you catch that? When you use a conditional type, TypeScript will distribute union types over the conditional’s branches. It’s like taking the conditional type and mapping (er, distributing) it over each element in the union.

Why does any of this matter? Well, it lets you safely express a bunch of common operations.

For example, TypeScript comes with & for computing what two types have in common and | for taking a union of two types. Let’s build Without<T, U>, which computes the types that are in T but not in U.

type Without<T, U> = T extends U ? never : T

You use Without like so:

type A = Without<
  boolean | number | string,
  boolean
> // number | string

Let’s walk through how TypeScript computes this type:

1. Start with the inputs:

   type A = Without<boolean | number | string, boolean>

2. Distribute the condition over the union:

   type A = Without<boolean, boolean>
          | Without<number, boolean>
          | Without<string, boolean>

3. Substitute in Without’s definition and apply T and U:

   type A = (boolean extends boolean ? never : boolean)
          | (number extends boolean ? never : number)
          | (string extends boolean ? never : string)

4. Evaluate the conditions:

   type A = never
          | number
          | string

5. Simplify:

   type A = number | string

If it wasn’t for the distributive property of conditional types, we would have ended up with never (if you’re not sure why, walk through what would happen for yourself!).

The infer Keyword

The final feature of conditional types is the ability to declare generic types as part of a condition. As a refresher, so far we’ve seen just one way to declare generic type parameters: using angle brackets (<T>). Conditional types have their own syntax for declaring generic types inline: the infer keyword.

Let’s declare a conditional type ElementType, which gets the type of an array’s elements:

type ElementType<T> = T extends unknown[] ? T[number] : T
type A = ElementType<number[]> // number

Now, let’s rewrite it using infer:

type ElementType2<T> = T extends (infer U)[] ? U : T
type B = ElementType2<number[]> // number

In this simple example ElementType is equivalent to ElementType2. Notice how the infer clause declares a new type variable, U—TypeScript will infer the type of U from context, based on what T you passed to ElementType2.

Also notice why we declared U inline instead of declaring it up front, alongside T. What would have happened if we did declare it up front?

type ElementUgly<T, U> = T extends U[] ? U : T
type C = ElementUgly<number[]> // Error TS2314: Generic type 'ElementUgly'
                               // requires 2 type argument(s).

Uh-oh. Because ElementUgly defines two generic types, T and U, we have to pass both of them in when instantiating ElementUgly. But if we do that, that defeats the point of having an ElementUgly type in the first place; it puts the burden of computing U on the caller, when we wanted ElementUgly to compute the type itself.

Honestly, this was a bit of a silly example because we already have the keying-in operator ([]) to look up the type of an array’s elements. What about a more complicated example?

type SecondArg<F> = F extends (a: any, b: infer B) => any ? B : never

// Get the type of Array.slice
type F = typeof Array['prototype']['slice']

type A = SecondArg<F> // number | undefined

So, [].slice’s second argument is a number | undefined. And we know this at compile time—try doing that in Java.

Built-in Conditional Types

Conditional types let you express some really powerful operations at the type level. That’s why TypeScript ships with a few globally available conditional types out of the box:

Exclude<T, U>

Like our Without type from before, computes those types in T that are not in U:

type A = number | string
type B = string
type C = Exclude<A, B>  // number

Extract<T, U>

Computes the types in T that you can assign to U:

type A = number | string
type B = string
type C = Extract<A, B>  // string

NonNullable<T>

Computes a version of T that excludes null and undefined:

type A = {a?: number | null}
type B = NonNullable<A['a']>  // number

ReturnType<F>

Computes a function’s return type (note that this doesn’t work as you’d expect for generic and overloaded functions):

type F = (a: number) => string
type R = ReturnType<F>  // string

InstanceType<C>

Computes the instance type of a class constructor:

type A = {new(): B}
type B = {b: number}
type I = InstanceType<A>  // {b: number}

Type Assertions

If you have a type B and A <: B <: C, then you can assert to the typechecker that B is actually an A or a C. Notably, you can only assert that a type is a supertype or a subtype of itself—you can’t, for example, assert that a number is a string, because those types aren’t related.

TypeScript gives us two syntaxes for type assertions:

function formatInput(input: string) {
  // ...
}

function getUserInput(): string | number {
  // ...
}

let input = getUserInput()

// Assert that input is a string
formatInput(input as string) 

// This is equivalent to
formatInput(<string>input) 

We use a type assertion (as) to tell TypeScript that input is a string, not a string | number as the types would have us believe. You might do this, for example, if you want to quickly test out your formatInput function and you know for sure that getUserInput returns a string for your test.

The legacy syntax for type assertions uses angle brackets. The two syntaxes are functionally equivalent.

Sometimes, two types might not be sufficiently related, so you can’t assert that one is the other. To get around this, simply assert as any (remember from “Assignability” that any is assignable to anything), then spend a few minutes in the corner thinking about what you’ve done:

function addToList(list: string[], item: string) {
  // ...
}

addToList('this is really,' as any, 'really unsafe')

Clearly, type assertions are unsafe, and you should avoid using them when possible.

Nonnull Assertions

For the special case of nullable types—that is, a type that’s T | null or T | null | undefined—TypeScript has special syntax for asserting that a value of that type is a T, and not null or undefined. This comes up in a few places.

For example, say we’ve written a framework for showing and hiding dialogs in a web app. Each dialog gets a unique ID, which we use to get a reference to the dialog’s DOM node. Once a dialog is removed from the DOM, we delete its ID, indicating that it’s no longer live in the DOM:

type Dialog = {
  id?: string
}

function closeDialog(dialog: Dialog) {
  if (!dialog.id) { 
    return
  }
  setTimeout(() => 
    removeFromDOM(
      dialog,
      document.getElementById(dialog.id) // Error TS2345: Argument of type
                                         // 'string | undefined' is not assignable
                                         // to parameter of type 'string'. 
    )
  )
}

function removeFromDOM(dialog: Dialog, element: Element) {
  element.parentNode.removeChild(element) // Error TS2531: Object is possibly
                                          //'null'. 
  delete dialog.id
}

If the dialog is already deleted (so it has no id), we return early.

We remove the dialog from the DOM on the next turn of the event loop, so that any other code that depends on dialog has a chance to finish running.

Because we’re inside the arrow function, we’re now in a new scope. TypeScript doesn’t know if some code mutated dialog between and , so it invalidates the refinement we made in . On top of that, while we know that if dialog.id is defined then an element with that ID definitely exists in the DOM (because we designed our framework that way), all TypeScript knows is that calling document.getElementById returns an HTMLElement | null. We know it’ll always be a nonnullable HTMLElement, but TypeScript doesn’t know that—it only knows about the types we gave it.

Similarly, while we know that the dialog is definitely in the DOM and it definitely has a parent DOM node, all TypeScript knows is that the type of element.parentNode is Node | null.

One way to fix this is to add a bunch of if (_ === null) checks everywhere. While that’s the right way to do it if you’re unsure if something is null or not, TypeScript comes with special syntax for when you’re sure it’s not null | undefined:

type Dialog = {
  id?: string
}

function closeDialog(dialog: Dialog) {
  if (!dialog.id) {
    return
  }
  setTimeout(() =>
    removeFromDOM(
      dialog,
      document.getElementById(dialog.id!)!
    )
  )
}

function removeFromDOM(dialog: Dialog, element: Element) {
  element.parentNode!.removeChild(element)
  delete dialog.id
}

Notice the sprinkling of nonnull assertion operators (!) that tell TypeScript that we’re sure dialog.id, the result of our document.getElementById call, and element.parentNode are defined. When a nonnull assertion follows a type that might be null or undefined, TypeScript will assume that the type is defined: T | null | undefined becomes a T, number | string | null becomes number | string, and so on.

When you find yourself using nonnull assertions a lot, it’s often a sign that you should refactor your code. For example, we could get rid of an assertion by splitting Dialog into a union of two types:

type VisibleDialog = {id: string}
type DestroyedDialog = {}
type Dialog = VisibleDialog | DestroyedDialog

We can then update closeDialog to take advantage of the union:

function closeDialog(dialog: Dialog) {
  if (!('id' in dialog)) {
    return
  }
  setTimeout(() =>
    removeFromDOM(
      dialog,
      document.getElementById(dialog.id)!
    )
  )
}

function removeFromDOM(dialog: VisibleDialog, element: Element) {
  element.parentNode!.removeChild(element)
  delete dialog.id
}

After we check that dialog has an id property defined—implying that it’s a VisibleDialog—even inside the arrow function TypeScript knows that the reference to dialog hasn’t changed: the dialog inside the arrow function is the same dialog outside the function, so the refinement carries over instead of being invalidated like it was in the last example.

Definite Assignment Assertions

TypeScript has special syntax for the special case of nonnull assertions for definite assignment checks (as a reminder, a definite assignment check is TypeScript’s way of making sure that by the time you use a variable, that variable has been assigned a value). For example:

let userId: string

userId.toUpperCase() // Error TS2454: Variable 'userId' is used
                     // before being assigned.

Clearly, TypeScript just did us a great service by catching this error. We declared the variable userId, but forgot to assign a value to it before we tried to convert it to uppercase. This would have been a runtime error if TypeScript hadn’t noticed it!

But, what if our code looks more like this?

let userId: string
fetchUser()

userId.toUpperCase() // Error TS2454: Variable 'userId' is used
                     // before being assigned.

function fetchUser() {
  userId = globalCache.get('userId')
}

We happen to have the world’s greatest cache, and when we query this cache we get a cache hit 100% of of the time. So after the call to fetchUser, userId is guaranteed to be defined. But TypeScript isn’t able to statically detect that, so it still throws the same error as before. We can use a definite assignment assertion to tell TypeScript that userId will definitely be assigned by the time we read it (notice the exclamation mark):

let userId!: string
fetchUser()

userId.toUpperCase() // OK

function fetchUser() {
  userId = globalCache.get('userId')
}

As with type assertions and nonnull assertions, if you find yourself using definite assignment assertions often, you might be doing something wrong.