Generics in TypeScript enable us to define components that can work with a variety of data types while maintaining strong type safety. Whether you’re building data structures like stacks and queues, or designing reusable functions and classes, understanding generics can improve the maintainability of your code. In this blog post, we’ll explore the fundamentals of generics in TypeScript, illustrate their use with practical examples, and highlight the advantages they bring to your TypeScript projects.

To begin with, let’s take a look at the array in TypeScript.

Array

In TypeScript, arrays are a fundamental construct for managing collections of values. Let’s start with a simple example:

let numbers = [1, 2, 3];

In this example, TypeScript infers the type of numbers based on the values it contains, telling that it is an array of numbers. However, we can also explicitly declare the type of the array for clarity and additional type-safety. This can be done in two syntactically different ways, both of which are equally valid in TypeScript.

First, the more commonly used shorthand notation is:

let numbers: number[] = [1, 2, 3];

Here, number[] effectively communicates that numbers is an array where each element is of type number. This notation is concise and preferred in the community for its readability and ease of understanding.

There’s another equally valid method to declare an array using TypeScript’s generics syntax:

This format utilises the Array type directly and specifies the element type within angle brackets. Here, Array<number> means exactly the same as number[]: an array composed solely of numbers.

This generics notation underscores the flexibility and power of TypeScript’s type system, allowing engineers to define types that can work over a variety of data types while still maintaining strict type-checking.

Let’s take a closer look at the Generics.

What are Generics?

Generics are one of the most powerful features in TypeScript, enabling you to write flexible, reusable, and type-safe code. At their core, generics allow components to work with any data type rather than a single data type. This capability significantly enhances the utility and versatility of several programming constructs like arrays, functions, and classes.

Anatomy of Generics

The fundamental structure of a generic involves three main parts.

1. Type Variable Declaration

This is the generic type parameter that we define using angle brackets, < >. It acts as a placeholder that will be replaced with an actual type when the generic is used.

In this example, <T> is a type variable that tells TypeScript this function can handle any type. The type of arg is specified as T, and the function returns a value of the same type T.

While T is commonly used as the placeholder for type variables, we’re not limited to just this naming convention. Any valid identifier can serve as a type variable name. The choice of T is largely due to convention, where it stands for “Type” and is widely recognised in the community for its use in generics. Additionally, we could use K for a key type in maps and V for value types.

2. Function Signature

The function’s parameters and return type can also use the type variable, making the function flexible yet type-safe.

Here, the generic type <string> replaces T when the function is called, enforcing that both the input and output are of type string.

3. Constraints

We can restrict the types that can be used with generics by using constraints. This ensures that the function or class operates on types that have certain properties.

This examples shows that this function adds a constraint T extends { length: number }, which means T must be a type that has a length property.

Revisited Array

Now let’s revisit the array we saw above.

let numbers: number[] = [1, 2, 3];

This array is specifically typed to hold numbers. If we wanted to have an array of strings or an array of objects, we would have to declare separate types for each.

let numbers: number[] = [1, 2, 3];
let strings: string[] = ['apple', 'banana', 'cherry'];
let booleans: boolean[] = [true, false, true];
let people: { name: string; age: number }[] = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 },
];

Generics let you abstract this into a single, reusable type. Here’s how we can refactor the example to use generics:

This example is to show how generics function to create flexible, type-safe collections but in practical scenarios, we can often omit the type parameters (the <type> part) when calling a generic function if the type can be inferred from the arguments we pass to the function. So we could simplify the function calls like this:

Next, let’s explore how to use explicit generic types with the fetch() function, which is necessary when TypeScript cannot automatically infer these types.

Fetch()

In modern web development, fetching data from remote servers is a common task that often requires handling various data types and structures. TypeScript enhances this process by allowing engineers to use explicit generic types with the fetch() function. This approach is crucial because TypeScript cannot automatically infer the types of data returned by remote APIs.

By specifying these types explicitly, engineers can ensure type checking and error handling, leading to more reliable and maintainable code. Here is an example code for fetchData.

Let’s take a closer look at how the generic is used in line 1. The async function keyword is used to define an asynchronous function that can execute asynchronous operations and will return a Promise. Within this function, <T> represents a generic type parameter that allows the function to handle various data types specified at the time of the function’s invocation, affecting the structure of the returned array. The parameter url: string is used to specify the URL from which the data will be fetched. The return type Promise<T[]> indicates that the function will return a promise which, upon resolution, will yield an array of the specified type T, aligning with the data structure expected from the API response.

Here are two examples of using fetchData with explicit type for an API returning an array of people and products.

For both fetchPeople() and fetchProducts(), fetchData is called with explicit type annotations to dictate what structure the returned data should adhere to:

fetchPeople(): { name: string; age: number } specifies that the fetched data will be an array of objects, each with a name (string) and an age (number).
fetchProducts(): { id: number; name: string; price: number } specifies that each object in the returned products array must have an id (number), a name (string), and a price (number).

The major benefit of using generics in these functions is the ability to reuse the fetchData function for different types of API responses without repeating the fetching logic.

While the code could be more optimised, I think it serves as a great demonstration of how generics operate for now. To further explore generics, let’s now see an example with Promise.

Promise

Let’s define a function delayedResolve that simulates fetching or calculating a result asynchronously and uses a generic type to return a promise. This function will take any input and return it after a specified delay, encapsulated in a promise.

By using the generic type parameter, <T>, the function can be utilised to work with any data type – integers, strings, arrays, objects, etc. – while maintaining full type safety. And the value parameter is the data that you want to be resolved by the promise. Since it’s of type T, it can be anything as specified when the function is called. And lastly, the return type of the function signifies that the function returns a promise which, when resolved, will provide a value of type T.

Let’s take a look at how we can use the delayedResolve generic promise function. This time, let’s see the use of the then() method as we already saw how to use async/await above.

As you can see from the examples, using generics makes the delayedResolve function extremely flexible as it can handle any data type, allowing us to use it in a wide array of scenarios without modification.

Moreover, despite its flexibility, it remains type-safe. We get compile-time checks and IntelliSense (in IDEs like Visual Studio Code), ensuring that we handle the resolved data correctly according to its type.

And also importantly we can reuse the same function across our application for various data types, which reduces code duplication and potential bugs associated with implementing similar logic multiple times.

Despite the benefits, even though generics provide significant benefits in terms of flexibility and type safety, they can sometimes create issues by being too permissive with the types they accept. To address this, TypeScript allows the use of constraints with generics, enabling developers to specify more precise type requirements and ensure that the generic functions or classes work only with types that possess certain properties or methods.

Generic Constraints

In TypeScript, generic constraints help engineers specify what requirements type parameters must meet, ensuring that functions and classes work safely and consistently across various types. This is accomplished by using the extends keyword in the generic declaration to limit the types that can be used, making sure they include certain properties or methods.

Let’s look at how to apply this concept by adding a constraint to the above function. First, we will convert the received value to a string using the toString() method.

However, it will lead to a TypeScript error stating “Property ‘toString’ does not exist on type ‘T'”.

This is because, in TypeScript, generics are assumed to be of the most basic type unless otherwise specified. At the moment, TypeScript treats T as potentially being any type, including those that might not have a toString() method such as null.

To resolve this issue, we need to constrain T to ensure that it includes the toString() method. We can modify the generic type parameter to include a constraint that requires T to extend an object structure that guarantees the presence of the toString() method. Here’s how we can do it:

With this change, T is now constrained to only types that have a toString() method, thus ensuring type safety.

Constraints with Interface

Using an interface to define a constraint for a generic function is a common and effective way to ensure type safety in TypeScript.

Let’s define an interface that mandates the presence of a toString() method, and use this interface as the constraint for the generic type T.

This interface acts as a contract for any type that needs to work with the delayedResolve function. By defining toString(): string; in the interface, we ensure that any type passed to the function can safely be converted to a string.

Generics with Classes

Using generics with classes allows engineers to write a single class that can operate on a variety of data types.

Let’s take a look at a simple Stack class example. We will deep dive into Stack & Queue in a future article so stay tuned for more complete Stack & Queue code.

This Stack class consists of 3 methods, constructor, push and pop and the elements property.

The generic type <T> is used to specify that the Stack class can handle elements of any type. By using <T>, we allow the user of the class to specify the type of elements the stack should store when they create an instance of it. This makes the Stack class highly flexible because it can be used with any TypeScript valid type.

Let’s go through the code.

Class Definition

The Stack class accepts a generic type, T, and the line 2 declares a private member elements that is an array of type T. The private keyword restricts access to elements from outside the class, encapsulating it and preventing external code from directly modifying the array. The array is initialised as empty, ready to store the stack’s elements.

Constructor

constructor(initialElements: T[] = []) {
  this.elements = initialElements;
}

The constructor accepts an optional parameter initialElements, which is an array of type T. This parameter allows the instantiation of a stack with an initial set of elements. If no initial elements are provided, it defaults to an empty array. This is useful for creating a pre-populated stack or starting with an empty one.

Methods

push(element: T): void {
  this.elements.push(element);
}

pop(): T | undefined {
  return this.elements.pop();
}

The push() method adds an element to the stack. The element must be of type T, ensuring type safety. The void return type indicates that this method does not return a value.

The pop() method removes the top element from the stack and returns it. If the stack is empty, it returns undefined. The return type T | undefined reflects this possibility, providing a clear indication to the caller that they may receive a value of type T or undefined if no elements are left in the stack.

Utility Types

Utility types in TypeScript are built-in generics that provide powerful ways to transform one type into another, enabling more flexible type manipulation. These utilities can be used to modify properties of a type in various ways, such as making them optional, read-only, or excluding certain properties altogether. By leveraging utility types, engineers can write more maintainable and error-resistant code while minimising redundancy and increasing reusability.

Here are some commonly used utility types in TypeScript:

Partial<T>: Makes all properties of a type T optional. This is useful when creating objects that might not have a full set of properties defined.
Readonly<T>: Makes all properties of a type T read-only, meaning they cannot be reassigned after their initial declaration. This is particularly useful for ensuring immutability in your application.
Record<K, T>: Creates a type with a set of properties K of type T. This utility is useful for defining objects when property names and types are known beforehand.
Pick<T, K>: Constructs a type by picking the set of properties K from T. This is useful for creating types that only need a subset of the properties that exist on another type.
Omit<T, K>: Constructs a type by removing properties K from T. This is handy when you need to exclude certain properties from a type to create a new type definition.
NonNullable<T>: Constructs a type by excluding null and undefined from T, making sure that the type does not include these two types.

Generics Types vs Union Types

While generics and union types may seem similar at first glance, they serve distinct purposes and are best suited for different scenarios. Understanding when to use each can improve your code’s flexibility, readability, and safety.

We now understand how generics work, let’s explore the union types using the same Stack class example.

Union types

Union types allow a variable or a function parameter to accept multiple different types. This is useful when you need to handle a predefined set of types but not necessarily the same type across different instances.

Let’s modify the Stack class to use union types instead:

class Stack {
  private elements: (number | string)[] = [];

  constructor(initialElements: (number | string)[] = []) {
    this.elements = initialElements;
  }

  push(element: number | string): void {
    this.elements.push(element);
  }

  pop(): number | string | undefined {
    return this.elements.pop();
  }
}

and here is the usage example:

const mixedStack = new Stack();
mixedStack.push(10);
mixedStack.push("Hello");
console.log(mixedStack.pop()); // Outputs: "Hello"
console.log(mixedStack.pop()); // Outputs: 10

In this Stack class example, union types are utilised to allow the stack to handle elements of both number and string types. The union types provide type safety by ensuring that values are restricted to the specified types, number and string, but this flexibility is limited to the predefined set of types (in this case, number and string).

Comparison

Overall Generics provide greater flexibility and type safety for creating reusable components that can handle any type. They are ideal for data structures and functions that need to work with various types in a type-safe manner.

On the other hand, Union Types are useful when we need to handle a specific set of types and can manage the complexity of type checks. They are suitable for scenarios where the types are known and limited.

In the example of the Stack class, generics offer a more reusable solution, while union types provide a quick way to handle multiple predefined types.

~~~

I hope you enjoyed this article and now have a better understanding of how generics work in TypeScript. If you’re interested in learning more about TypeScript, be sure to subscribe below and connect with me on LinkedIn.