TypeScript Generics are Actually Three Different Concepts

The TypeScript docs are mostly excellent. The TypeScript handbook is a shining example of what good docs look like. They're precise, well-maintained, well laid-out, and complete.

However, if there's one section could us a rewrite, it would be the section on Generics. This section assumes too much knowledge, teaches things in the wrong order, and misses out key information. The generics section of the TypeScript docs leaves you feeling that generics are complicated and mysterious.

Let's rectify that.

Type Helpers

Look at generics first on the type level. Imagine you have a type like this:

typescript
type Name = 'matt'

This is a literal string, matt, expressed in a type alias. This can't be altered later, so it behaves similarly to a const variable declaration in JavaScript:

typescript
const name = 'matt' 

Using generics, we can change Name to be a function. Add a type argument to it:

typescript
type Name<LastName> = 'matt' 

This adds a parameter to Name, meaning that whenever you use it, you'll need to pass in an argument:

ts
type User = { name: Name<'pocock'> } 

This turns the type from a variable to a function. Now, its equivalent in JavaScript would be:

typescript
const name = (lastName) => 'matt' 

Since it's now a function, let's name it something more function-like:

typescript
type GetName<LastName> = 'matt' 

LastName is currently unused, so as an example return an object from our type 'function':

typescript
type GetNameObject<LastName> = {
  firstName: 'matt'
  lastName: LastName
}

The JavaScript equivalent would be:

typescript
const getNameObject = (lastName) => {
  return {
    firstName: 'matt',
    lastName,
  }
}

You can then use our GetNameObject type function to create types, by passing it arguments:

typescript
type NameObject = GetNameObject<'pocock'>
// {
//   firstName: "matt";
//   lastName: "pocock";
// }

In Total TypeScript's Type Transformations workshop this pattern is called 'type helpers'. Type helpers are really useful on the type level to create new types to help DRY up your code.

A common example is a Maybe type helper:

typescript
type Maybe<T> = T | null | undefined
type MaybeString = Maybe<string>
// string | null | undefined

Generic functions

Now you know how to handle generics on the type level, what about generic functions?

Take a simple example, returnWhatIPassIn:

typescript
const returnWhatIPassIn = (input: any) => {
  return input
}

This function won't return whatever you pass in - it'll actually always return any on the type level. This is annoying, because it ruins your autocomplete on the thing you pass in:

typescript
const str = returnWhatIPassIn('matt')
str.touppercase() // No error here!

Imagine you wanted to create this on the type level. You'd create a type helper called ReturnWhatIPassIn:

typescript
type ReturnWhatIPassIn<TInput> = TInput
type Str = ReturnWhatIPassIn<'matt'>
//   "matt"

At the type level, you're taking in TInput - whatever it is - and returning it.

You can use a very similar syntax to annotate our function:

typescript
const returnWhatIPassIn = <TInput>(input: TInput): TInput => {
  return input
}

This is now a generic function. This means that when you call it, the type argument of TInput gets inferred from what you pass in:

typescript
const str = returnWhatIPassIn('matt')
// "matt"

Put this in simple terms.

A generic function is a type helper layered on top of a normal function.

This means that when you call the function, you're also passing a type to the 'type helper'.

Build up that function again, piece by piece to make it clearer starting from your JavaScript-only function again:

typescript
const returnWhatIPassIn = (input: any) => {
  return input
}

Get the structure of the 'type helper' set up first. You'll need to infer an TInput argument, and return that.

typescript
const returnWhatIPassIn = <TInput>(input: any): TInput => {
  return input
}

If you try and call this now, it'll infer what it returns as unknown:

typescript
const str = returnWhatIPassIn('matt')
// unknown

You haven't told the type helper which arguments to infer from. You need it to infer the type of TInput from the input argument. Fix that like this:

typescript
const returnWhatIPassIn = <TInput>(input: TInput): TInput => {
  return input
}

So inside (input: TInput), you perform a mapping between the runtime argument - input - and the type you want it to infer - TInput.

Summary

This is the right way to think about generics - as a type helper laid over your function, with a mapping between them.

Generics get a lot more complex from here - multiple generics, generic constraints, generics hidden deep within other types - but this mental model stays the same.

const sum = <T>(array: readonly T[], mapper: (item: T) => number): number => array.reduce((acc, item) => acc + mapper(item), 0)