TypeScript Generics for People Who Gave Up on Understanding Generics

TypeScript Generics Too Hard?

// Confused by generics code like this?
function makePair<
  F extends number | string,
  S extends boolean | F
>()

If you’re (1) new to TypeScript, (2) new to generics, and (3) struggling to understand generics, then you’re exactly like me when I was learning Java 13 years ago.

Like TypeScript, the Java programming language supports generics. When I was studying Java in college, I was a beginner programmer, and generics felt very difficult to me. So I gave up on understanding generics at the time and used them without knowing what I was doing. I didn’t understand generics until I got a full time job after college.

Maybe you’re like me from 13 years ago and have felt that TypeScript generics are too difficult. If so, this tutorial is for you! I’ll try to help you actually understand generics.

Let’s talk about makeState()

First, I created a function called makeState() below. We’ll use this function to talk about generics.

function makeState() {
  let state: number
  function getState() {
    return state
  }
  function setState(x: number) {
    state = x
  }
  return { getState, setState }
}

When you run makeState(), it returns two functions: getState() and setState(). You can use these functions to set and get the variable called state.

Let’s try it out! What gets printed out to the console when you run the following code? Try to guess first, and then press the Run button.

const { getState, setState } = makeState()
setState(1)
console.log(getState())
setState(2)
console.log(getState())

It printed 1, then 2. Pretty simple, right?

Attempt 2: Use generics

This is where generics come in. Take a look below:

function makeState<S>() {
  let state: S
  function getState() {
    return state
  }
  function setState(x: S) {
    state = x
  }
  return { getState, setState }
}

makeState() is now defined as makeState<S>(). You can think of <S> as another thing that you have to pass in when you call the function. But instead of passing a value, you pass a type to it.

For example, you can pass the type number as S when you call makeState():

// It sets S as number
makeState<number>()

Then, inside the function definition of makeState(), S will become number:

// In the function definition of makeState()
let state: S // <- number
function setState(x: S /* <- number */) {
  state = x
}

Because state will be number and setState will only take number, it creates a number-only state.

// Creates a number-only state
const numState = makeState<number>()
numState.setState(1)
console.log(numState.getState())
// numState.setState('foo') will fail!

On the other hand, to create a string-only state, you can pass string as S when you call makeState():

// Creates a string-only state
const strState = makeState<string>()
strState.setState('foo')
console.log(strState.getState())
// strState.setState(1) will fail!

Note: We call makeState<S>() a “generic function” because it’s literally generic—you have a choice to make it number-only or string-only. And you know it’s a generic function if it takes a type parameter.

function makeState<S>() {
  let state: S
  function getState() {
    return state
  }
  function setState(x: S) {
    state = x
  }
  return { getState, setState }
}

Generic interfaces and type aliases

Let’s go back to our previous implementation of makePair(). Now, take a look at the type of pair:

function makePair<F, S>() {
  let pair: { first: F; second: S }
  // ...
}

This works as is, but if we want to, we can refactor { first: F, second: S } into an interface or a type alias so it can be reused.

Let’s first extract the type of pair into a generic interface. I’ll use A and B as type parameter names to distinguish them from the type parameters of makePair().

// Extract into a generic interface
// to make it reusable
interface Pair<A, B> {
  first: A
  second: B
}

We can then use this interface to declare the type for pair.

function makePair<F, S>() {
  // Usage: Pass F for A and S for B
  let pair: Pair<F, S>
  // ...
}

By extracting into a generic interface (an interface that takes type parameters), we can reuse it in other places if necessary.

Alternatively, we can extract it into a generic type alias. For object types, type aliases are basically identical to interfaces, so you can use whichever one you prefer.

// Extract into a generic type alias. It’s
// basically identical to using an interface
type Pair<A, B> = {
  first: A
  second: B
}

To summarize, you can create generic interfaces and type aliases, just as you can create generic functions.

Generic classes

The last thing we’ll cover is generic classes. First, let’s revisit the code for makeState(). This is the generic version that doesn’t use extends or default type parameters.

function makeState<S>() {
  let state: S
  function getState() {
    return state
  }
  function setState(x: S) {
    state = x
  }
  return { getState, setState }
}

We can turn makeState() into a generic class called State like below. It looks similar to makeState(), right?

class State<S> {
  state: S
  getState() {
    return this.state
  }
  setState(x: S) {
    this.state = x
  }
}

To use this, you just need to pass a type parameter on initialization.

// Pass a type parameter on initialization
const numState = new State<number>()
numState.setState(1)
// Prints 1
console.log(numState.getState())

To summarize, generic classes are just like generic functions. Generic functions take a type parameter when we call them, but generic classes take a type parameter when we instantiate them.

That’s all you need to know!

Thanks for reading! That’s all you need to know about generics in TypeScript. Hope I made generics less scary to you.

If you’d like me to write about some other topics on TypeScript, or if you have feedback, please let me know on Twitter at @chibicode.

The source code for this site is on GitHub: