TypeScript Generic Constraints: A Complete Guide to keyof and extends

Understanding TypeScript Generics Constraints

TypeScript generics are incredibly powerful, but they become truly useful when you understand how to constrain them. If you have ever wondered how to make your generic functions type-safe while still maintaining flexibility, this guide is for you.

Why Generic Constraints Matter

Without constraints, TypeScript generics are essentially "any" under the hood. You might write a function like this:

function getProperty<T, K>(obj: T, key: K) {
  return obj[key]; // Error: Type K cannot index type T
}

This fails because TypeScript has no guarantee that key exists on obj. This is where constraints come in.

The keyof Operator

The keyof operator creates a union type of all property names of a given type:

type Point = { x: number; y: number };
type PointKeys = keyof Point; // "x" | "y"

const key: PointKeys = "x"; // OK
const invalidKey: PointKeys = "z"; // Error

Using keyof with Generics

Here is the corrected version of our getProperty function:

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

const person = { name: "Alice", age: 30 };
getProperty(person, "name"); // Returns string
getProperty(person, "age");   // Returns number
getProperty(person, "email"); // Error: "email" is not a key of person

The extends Keyword in Generics

The extends keyword allows you to constrain generics to specific types or shapes:

// Constrain to object types only
function processObject<T extends object>(value: T): T {
  return value;
}

// Constrain to types with specific properties
interface HasId {
  id: number;
}

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

Real-World Example: API Response Handler

Here is a practical example of using generic constraints to build a type-safe API handler:

interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

async function fetchData<T extends { id: number }>(
  url: string,
  schema: T
): Promise<ApiResponse<T>> {
  const response = await fetch(url);
  const data = await response.json();
  return {
    data,
    status: response.status,
    message: response.statusText
  };
}

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

const result = await fetchData<User>("/api/user/1", {
  id: 0,
  name: "",
  email: ""
});
// TypeScript knows result.data is User

Common Patterns with extends

1. Extending Union Types

type Color = "red" | "green" | "blue";

function setColor<T extends Color>(color: T): void {
  console.log(color);
}

setColor("red");   // OK
setColor("yellow"); // Error

2. Extending Conditional Types

type IsString<T> = T extends string ? true : false;

type Test1 = IsString<"hello">; // true
type Test2 = IsString<42>;       // false

3. Utility Types with extends

// Make all properties optional
type Partial<T> = {
  [P in keyof T]?: T[P];
};

// Make all properties required
type Required<T> = {
  [P in keyof T]-?: T[P];
};

// Pick specific properties
type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};

Best Practices

• Be Specific: Always constrain your generics as narrowly as possible while maintaining the functionality you need.
• Use keyof: When accessing object properties, always use keyof to ensure type safety.
• Document Constraints: Add JSDoc comments explaining why you need specific constraints.
• Leverage Utility Types: TypeScript provides built-in utility types like Partial, Required, Pick, and Omit that use these patterns.

Conclusion

Generic constraints are essential for building robust, type-safe applications with TypeScript. By mastering keyof and extends, you can create flexible functions that still provide compile-time type checking—catching errors before your code even runs.

The key takeaway: generics without constraints are just any-types in disguise. Add constraints to unlock the full power of TypeScript type system.