TypeScript Generics. Discussing naming conventions

We can find the concept of generic types across many languages such as Java, C#. Naturally, they found their way into TypeScript. In this article, we discuss their purpose and provide various examples. We also discuss naming conventions for generics that we can stumble upon.

Introducing TypeScript Generics

One of the qualities that we strive for when developing software is the reusability of our components. The above also applies to TypeScript, as the types of our data are also subject to change. With Generics, we can write code that can adapt to a variety of types as opposed to enforcing them.

There is a high chance that you’ve already encountered generics. They are a common approach present, for example, in React.

import { ChangeEvent, useState, useCallback } from 'react';
 
function useInputManagement() {
  const [value, setValue] = useState('');
 
  const handleChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  }, []);
 
  return {
    value,
    handleChange
  }
}

The above example uses a custom React hook. If you want to know more on how to design custom hooks, check out The Facade pattern and applying it to React Hooks

We can use generics to create highly reusable classes, types, interfaces, and functions.

The most basic example is the one with the identity function that we can find in the official documentation . Let’s inspect it closely:

function identity(argument: number): number {
    return argument;
}

The above function returns the argument that we pass to it. Unfortunately, it means that we need to create a function for every return type. That, unfortunately, does not meet the criteria of reusability.

To improve the above code, we can introduce a type variable . To declare a type variable, we need to append it to the name of our function by writing  function identity < T > .

Now, we are free to use it within our function:

function identity<T>(argument: T): T {
  return argument;
}

Above, we indicate that the type of the argument and the return type of the  identity function should be the same.

The most straightforward way to use the above function is to pass the desired type when calling it:

identity<string>('Hello world!');

TypeScript is a bit smarter , though. Instead of explicitly setting  T to a  string , we can let the compiler figure out the type on its own:

identity('Hello world!');

Arrow functions

We can also do the above with the use of arrow functions :

const identity = <T>(argument: T): T => argument;

The only issue is with the . tsx files. The above code results in the following error:

Parsing error: JSX element ‘T’ has no corresponding closing tag

The easiest way to fix this issue is to add a trailing comma:

const identity = <T,>(argument: T): T => argument;

A more real-life example

The promise-based Fetch API is powerful and flexible, but might not work as you might expect, coming from libraries like axios .

If you want to know more about the above API, check out Comparing working with JSON using the XHR and the Fetch API

One of the things that we can do is always reject promises when the request fails. On success, we might want to call the json ( ) function to extract the data.

function request<T>(
  url: string,
  options?: RequestInit
): Promise<T> {
  return fetch(
    url,
    options,
  )
    .then((response) => {
      if (!response.ok) {
        return Promise.reject();
      }
      return response.json();
    });
}

The json method might throw an error in some cases, for example when there is no body in the response. It would be a good idea to make the above example more bug-proof.

The RequestInit is a built-in interface used for the options of the  fetch function.

interface User {
  id: number;
  name: string;
  email: string;
}

request<User[]>('https://jsonplaceholder.typicode.com/users')
  .then((users) => {
    console.log(`There are ${users.length} users`);
  });

There are a few interesting things happening above. When we pass a type to the request function, we pass it further to have a return type of  Promise < T > . The  Promise is a built-in interface that is also generic.

By calling request < User [ ] > ( 'https://jsonplaceholder.typicode.com/users' ) we indicate that our promise resolves with an array of users.

Generic interfaces and classes

Aside from using built-in generic interfaces such as Promise , we can surely create our own.

interface KeyValuePair<K, V> {
  key: K;
  value: V;
}

const keyValuePair: KeyValuePair<string, string> = {
  key: 'name',
  value: 'John'
}

As you can see above, our generics can have more than just a single type variable.

We can create generic classes with the same level of success.

class KeyValuePair <K, V> {
  public key: K;
  public value: V;
  constructor(key: K, value: V) {
    this.key = key;
    this.value = value;
  }
}

const keyValuePair = new KeyValuePair('name', 'John');

Generic constraints

Making our types very flexible is not always the most suitable approach. Consider this simple example:

function getEmailDomain<T>(entity: T) {
  return entity.email.split('@').pop();
}

Property ’email’ does not exist on type ‘T’

Above, we want to extract the email property from the  entity . Unfortunately, we can’t be sure if it exists.

To deal with the above issue, we can put a constraint on the T type variable.

interface WithEmail {
  email: string;
}

function getEmailDomain<T extends WithEmail>(entity: T) {
  return entity.email.split('@').pop();
}

While the getName is still generic, it now has a constraint: the type that we pass to it needs to extend the  HasName interface.

request<User>('https://jsonplaceholder.typicode.com/users/1')
  .then((user) => {
    console.log(`The email domain that user has is ${getEmailDomain(user)}`);
  });

If you want to read more about interfaces such as the one above, check out the Interface segregation principle from Applying SOLID principles to your TypeScript code .

If we attempt to pass an argument that does not meet the above constraints, we encounter an error.

Naming convention

Generics are a popular solution that derives from languages like Java and C#. Since it originated from the above languages, it also inherits their naming conventions. Let’s look into the Java Tutorials from the Oracle :

The above convention seems to be the most popular, also within the TypeScript community. Official documentation for C# and TypeScript also uses it. But are the above arguments still valid?

Modern IDEs do a good job of preventing you from mistaking a type variable for an ordinary variable. The more variables we introduce, the easier it is to mistake them due to one-character naming.

Other developers also stumbled upon the above issue. The Google Java Style Guide allows multi-character names, that end with a capital letter  T .

I don’t like one-character variable names. If the most popular convention is wrong, maybe we should shy away from it.

There seems to be a bit of discussion going on about the naming of the type variables. For example, there are quite a few comments on this article by Tim Boudreau . I like the approach suggested by Erwin Mueller that merely appending the word  Type .

Map<KeyType, ValueType>

Summary

In this article, we’ve gone through the generics in TypeScript. This includes generic functions, classes, and interfaces. We’ve also examined some examples of how and when to use them. We’ve also touched on a very important subject: the naming convention.

I’m looking forward to hearing about your personal opinion on them. Feel free to let me know in the comments.