Generic Constraint

A generic constraint in TypeScript restricts the set of types that can be substituted for a generic type parameter. By enforcing a specific structural contract using the extends keyword, constraints guarantee that a generic type possesses predefined properties, methods, or signatures. This allows the TypeScript compiler to safely resolve and validate property accesses on instances of that generic type during static analysis.

Without a constraint, a generic type parameter T is treated as an opaque type (effectively unknown), meaning the compiler will reject any attempt to access properties on it.

Base Syntax

The constraint is declared immediately after the type parameter using the extends keyword, followed by the target type (which can be an interface, type alias, class, or primitive).

function process<T extends ConstraintType>(arg: T): void {
    // Compiler guarantees 'arg' satisfies the structure of 'ConstraintType'
}

Compiler Behavior: Unconstrained vs. Constrained

When a generic is unconstrained, the compiler cannot guarantee the existence of any specific members.

// Unconstrained: Compilation Error
function logLength<T>(arg: T): void {
    console.log(arg.length); 
    // Error: Property 'length' does not exist on type 'T'.
}

Applying a constraint informs the compiler of the minimum structural requirements T must fulfill. Because TypeScript uses structural typing, any type passed to T must contain at least the properties defined in the constraint.

interface Lengthwise {
    length: number;
}

// Constrained: Compilation Success
function logLength<T extends Lengthwise>(arg: T): void {
    console.log(arg.length); 
    // Valid: The compiler knows 'T' is guaranteed to have a 'length' property of type 'number'.
}

Advanced Constraint Mechanics

1. Constraining with Type Parameters (keyof)

A type parameter can be constrained by the shape of another type parameter within the same signature. This is heavily utilized with the keyof operator to enforce that a generic key strictly exists on a generic object.

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

In this structure, K is constrained to the union of literal types representing the keys of T.

2. Multiple Constraints via Intersection

TypeScript does not support a comma-separated list of constraints. To enforce multiple constraints simultaneously, you must use an intersection type (&).

interface HasName { name: string; }
interface HasAge { age: number; }

// T must satisfy both HasName AND HasAge
function register<T extends HasName & HasAge>(entity: T): void {
    console.log(entity.name, entity.age);
}

3. Constraints with Default Types

Generic constraints can be combined with generic default types. The default type must strictly satisfy the constraint.

// The default type 'HTMLDivElement' satisfies the constraint 'HTMLElement'
interface Component<T extends HTMLElement = HTMLDivElement> {
    element: T;
    render(): void;
}

4. Primitive Constraints

Constraints are not limited to object shapes; they can restrict type parameters to specific primitives or literal unions.

type AllowedTypes = string | number;

function format<T extends AllowedTypes>(value: T): string {
    return String(value);
}

Master TypeScript with Deep Grasping Methodology!

Learn More