Master TypeScript From Scratch

Learn TypeScript step by step with practical examples, interactive coding lessons, and real-world projects.

TypeScript Generic Constraints

Learn how to restrict generic type parameters using constraints, interfaces and keyof so generic functions can safely access required properties.

Simple Explanation: Generic constraints specify what a type parameter must support. They allow reusable functions to work with different types while ensuring that required properties and capabilities are available.

1. What are Generic Constraints?

Generics allow functions and classes to work with different types. However, without a constraint, TypeScript does not know which specific properties are available on an arbitrary type parameter.

We use the extends keyword to constrain a generic type parameter so that it must satisfy a particular type or structure.

Basic Syntax

interface HasLength {
    length: number;
}

function getLength<T extends HasLength>(value: T): number {
    return value.length;
}

console.log(getLength("TypeScript"));
console.log(getLength([10, 20, 30]));

Expected Output

10
3

The constraint requires the value to have a numeric length property. Strings and arrays satisfy this requirement.

2. Generic Constraints Workflow Diagram

Follow this workflow to understand how constraints restrict the types accepted by a generic function.

📝
Define Constraint

Specify the required structure or capability.

→
📥
Receive Type

A generic function receives a value of type T.

→
🔍
Check Constraint

TypeScript checks whether T satisfies the requirement.

→
✅
Use Members

The function can safely access the guaranteed members.

Remember: A constraint does not require T to be exactly the constraint type. T can be any type that satisfies the required structure.

3. Why Do We Need Generic Constraints?

A generic type parameter does not automatically provide access to properties that are not known to exist on every possible type. A constraint tells TypeScript which properties can safely be used.

Example with a Constraint

function displayLength<T extends { length: number }>(value: T): void {
    console.log("Length: " + value.length);
}

displayLength("Hello");
displayLength([1, 2, 3, 4]);

// This would cause a TypeScript error:
// displayLength(100);

Expected Output

Length: 5
Length: 4

A string and an array both have a numeric length property. A number does not, so it does not satisfy this constraint.

4. Constraints Using Interfaces

An interface can define the required properties of a generic type. Using that interface as a constraint allows the function to work with many object types that share the required structure.

Example: Employee Information

interface HasId {
    id: number;
}

function displayId<T extends HasId>(item: T): void {
    console.log("ID: " + item.id);
}

const employee = {
    id: 101,
    name: "Priya",
    department: "IT"
};

const product = {
    id: 501,
    name: "Keyboard",
    price: 1200
};

displayId(employee);
displayId(product);

Expected Output

ID: 101
ID: 501

How It Works

📋
HasId Interface

Requires an id property of type number.

💼
Employee Object

Contains an ID and additional employee information.

📦
Product Object

Contains an ID and additional product information.

Both objects satisfy HasId, so the same generic function can process them without knowing their complete structures.

5. Using keyof with Generic Constraints

The keyof operator creates a type from the keys of an object type. When used as a generic constraint, it can ensure that a requested property key actually exists on the object.

Example: Accessing Object Properties

function getProperty<T, K extends keyof T>(
    obj: T,
    key: K
): T[K] {
    return obj[key];
}

const student = {
    id: 101,
    name: "Rahul",
    age: 22
};

console.log(getProperty(student, "name"));
console.log(getProperty(student, "age"));
console.log(getProperty(student, "id"));

// This would cause a TypeScript error:
// getProperty(student, "salary");

Expected Output

Rahul
22
101

Understanding keyof

Expression Meaning
keyof T The union of keys available on type T.
K extends keyof T K must be one of the keys of T.
obj[key] Accesses the property corresponding to key.
T[K] The type of the property selected by K from T.
Important: The function preserves the relationship between the supplied key and the type of the property returned.

6. Combining Multiple Constraints

You can combine multiple structural requirements using an intersection type. The generic parameter must then satisfy all combined requirements.

Example

interface HasName {
    name: string;
}

interface HasAge {
    age: number;
}

function displayPerson<T extends HasName & HasAge>(person: T): void {
    console.log("Name: " + person.name);
    console.log("Age: " + person.age);
}

const employee = {
    name: "Amit",
    age: 28,
    department: "Development"
};

displayPerson(employee);

Expected Output

Name: Amit
Age: 28

Constraint Combination Diagram

👤
HasName

Requires name: string.

&
🎂
HasAge

Requires age: number.

→
✅
Valid Object

Must satisfy both structural requirements.

7. Generic Constraints with Arrays

Generic constraints can restrict a type parameter to arrays. This allows a function to perform array-specific operations safely.

Example

function getLastItem<T extends unknown[]>(items: T): T[number] | undefined {
    return items[items.length - 1];
}

console.log(getLastItem([10, 20, 30]));
console.log(getLastItem(["Rahul", "Priya"]));

console.log(getLastItem([]));

Expected Output

30
Priya
undefined

The constraint requires an array type. The function returns the final item or undefined when the array is empty.

8. Practical Example: Find Employee by ID

In a real application, multiple object types may share an ID field. A generic constraint lets one function search collections of these objects without requiring the function to know every property each object contains.

Example

interface HasId {
    id: number;
}

function findById<T extends HasId>(
    items: T[],
    id: number
): T | undefined {
    return items.find(item => item.id === id);
}

const employees = [
    { id: 1, name: "Amit", department: "IT" },
    { id: 2, name: "Priya", department: "HR" },
    { id: 3, name: "Rahul", department: "Testing" }
];

const employee = findById(employees, 2);

console.log(employee?.name);
console.log(employee?.department);

Expected Output

Priya
HR

Workflow Diagram

📋
Employee List

Contains objects with ID fields.

→
🔍
findById()

Searches for a matching ID.

→
✅
Matching Employee

Returns the matching object or undefined.

The function preserves the full type of the objects in the supplied array, so the result can be accessed using properties such as name and department.

9. Common Mistakes with Generic Constraints

Mistake Correct Approach
Accessing a property without declaring a constraint. Constrain T to a type that guarantees the property exists.
Assuming T must be exactly the constraint type. Remember that T can contain additional properties while satisfying the constraint.
Passing an object without a required property. Ensure the supplied object satisfies all constraint requirements.
Using an invalid property key in a generic lookup. Constrain K with keyof T.
Assuming constraints validate data at runtime. Use runtime validation when handling external data.

10. Advantages of Generic Constraints

Flexible Reusability

Build generic functions that work with multiple compatible types.

Type Safety

Ensure required properties and capabilities are available.

Better Type Inference

Preserve specific input and output types while checking constraints.

Maintainability

Express required structures clearly and reuse them across functions.

Summary

Generic constraints restrict type parameters using the extends keyword. Constraints can be defined with interfaces, object structures, array types and combinations of required structures. The keyof operator is useful for ensuring that a property key belongs to a particular object type.

Next, learn Utility Types and how to transform existing types using Partial, Required, Pick, Omit, Readonly and other built-in utilities.